서버 프로그래밍 인터페이스
서버 프로그래밍 인터페이스 (Server Programming Interface)
C 언어로 사용자 정의 함수를 만들 때, 그 함수 안에서 SQL 명령을 실행하고 싶은 경우가 있어요. 그때 쓰는 공식적인 통로가 바로 SPI(Server Programming Interface)예요. 파서·플래너·실행기에 쉽게 접근할 수 있게 해주는 일련의 인터페이스 함수들이라고 생각하면 돼요.
SPI가 뭘 해주나요
Server Programming Interface (SPI) 는 사용자 정의 C 함수를 작성하는 사람이 함수나 프로시저(procedure) 안에서 SQL 명령을 실행할 수 있게 해줘요. SPI는 파서(parser), 플래너(planner), 실행기(executor)에 접근을 단순화하는 인터페이스 함수 모음이고, 메모리 관리(memory management) 일부도 처리해 줘요.
참고: 사용 가능한 절차형 언어(procedural language)들은 대부분 함수에서 SQL 명령을 실행하는 다양한 수단을 제공해요. 그리고 이들 기능은 대부분 SPI에 기반하고 있어서, 그 언어들을 쓰는 사용자에게도 이 문서가 유용할 수 있어요.
꼭 알아둘 점: 실패하면 제어가 안 돌아와요
SPI로 호출한 명령이 실패하면, 제어가 C 함수로 돌아오지 않아요. 대신 C 함수가 실행되고 있던 트랜잭션(transaction) 또는 서브트랜잭션(subtransaction)이 롤백(rollback)돼요. SPI 함수들이 대부분 오류 반환 규칙을 문서화하고 있다는 점을 고려하면 조금 놀랍게 느껴질 수 있는데, 이 동작이 기본 원칙이에요.
SPI 함수는 성공하면 음이 아닌 결과를 반환해요 (반환된 정수 값 또는 아래에서 설명하는 전역 변수 SPI_result를 통해). 오류가 나면 음수 결과 또는 NULL이 반환돼요.
SPI를 사용하는 소스 코드 파일은 헤더 파일 executor/spi.h를 포함해야 해요.
장 구성 (Chapter 45 목차)
45.1. SPI 함수 (SPI Functions)
연결과 실행, 명령 실행과 계획 관련 함수들이 여기 있어요.
- 연결/해제:
SPI_connect— C 함수를 SPI 관리자에 연결,SPI_finish— 연결 해제 - 명령 실행:
SPI_execute— 명령 실행,SPI_exec— 읽기/쓰기 명령 실행,SPI_execute_extended,SPI_execute_with_args— out-of-line 파라미터로 명령 실행 - 계획 준비:
SPI_prepare,SPI_prepare_cursor,SPI_prepare_extended,SPI_prepare_params— 아직 실행하지 않고 문장을 준비 - 계획 정보:
SPI_getargcount— 필요한 인자 수,SPI_getargtypeid— 인자의 데이터 타입 OID,SPI_is_cursor_plan— 커서로 쓸 수 있는지 여부 - 계획 실행:
SPI_execute_plan,SPI_execute_plan_extended,SPI_execute_plan_with_paramlist,SPI_execp— 준비된 문장 실행 - 커서 관리:
SPI_cursor_open,SPI_cursor_open_with_args,SPI_cursor_open_with_paramlist,SPI_cursor_parse_open,SPI_cursor_find,SPI_cursor_fetch,SPI_cursor_move,SPI_scroll_cursor_fetch,SPI_scroll_cursor_move,SPI_cursor_close - 계획 저장:
SPI_keepplan,SPI_saveplan— 준비된 문장 저장 - 이름 있는 관계 등록:
SPI_register_relation,SPI_unregister_relation— 임시 이름 있는 관계를 SPI 쿼리에서 사용,SPI_register_trigger_data— 임시 트리거 데이터 제공
45.2. 데이터 접근 (Data Access)
결과에서 컬럼 이름·번호, 값을 읽어오는 함수들이에요.
SPI_fname— 컬럼 번호로 이름,SPI_fnumber— 이름으로 번호SPI_getvalue— 문자열 값,SPI_getbinval— 바이너리 값,SPI_gettype— 데이터 타입 이름,SPI_gettypeid— 데이터 타입 OIDSPI_getrelname— 관계 이름,SPI_getnspname— 네임스페이스SPI_result_code_string— 오류 코드를 문자열로
45.3. 메모리 관리 (Memory Management)
상위 실행기 컨텍스트에서 메모리를 다루는 함수들이에요.
SPI_palloc/SPI_repalloc/SPI_pfree— 상위 실행기 컨텍스트에서 메모리 할당·재할당·해제SPI_copytuple— 행 복사,SPI_returntuple— 튜플을 Datum으로 반환 준비,SPI_modifytuple— 지정 필드 교체로 행 생성SPI_freetuple— 행 해제,SPI_freetuptable—SPI_execute로 만든 행 집합 해제,SPI_freeplan— 저장된 준비 문장 해제
45.4. 트랜잭션 관리 (Transaction Management)
SPI_commit— 현재 트랜잭션 커밋,SPI_rollback— 현재 트랜잭션 중단,SPI_start_transaction— 폐기된(obsolete) 함수