> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL과 비교한 VEF 커버리지

> VillageSQL 확장 프레임워크와 PostgreSQL의 확장 프레임워크를 비교하여, VEF가 현재 지원하는 인터페이스와 훅, 그리고 남은 작업이 어디에서 추적되는지 보여주는 페이지입니다.

VillageSQL 확장 프레임워크(VEF)는 확장이 정해진 방식으로 데이터베이스 내부 동작에 접근할 수 있게 합니다. PostgreSQL은 오픈소스 데이터베이스 중 가장 성숙한 확장 프레임워크를 갖추고 있으므로, 이 페이지는 PostgreSQL을 기준점으로 삼아 VEF의 현재 기능과 계획된 기능을 파악할 수 있게 합니다.

이 페이지는 완성된 상태가 아니라 특정 시점의 스냅샷으로 읽어야 합니다. VEF는 릴리스마다 변경됩니다. PostgreSQL의 훅 기능을 정확히 일치시키는 것이 목표는 아닙니다. MySQL과 PostgreSQL은 서로 다른 데이터베이스이며, 사용자의 요구 사항도 종종 다릅니다.

<h2 id="capabilities-specific-to-villagesql">
  VillageSQL 고유 기능
</h2>

VEF가 제공하는 기능 중 일부는 아래 표에서 비교할 대상이 없습니다. MySQL의 구조가 다르기 때문이거나, VillageSQL 확장 작성자가 PostgreSQL이 자체 확장에 제공하지 않는 기능을 필요로 했기 때문입니다.

* **키링 접근** — `vsql::preview::keyring`을 사용하면 확장이 서버의 키링에서 비밀 값을 읽을 수 있습니다.
* **확장 전용 파일 저장소** — `vsql::preview::storage`는 확장에 서버가 관리하는 디스크 공간을 제공합니다. PostgreSQL 확장은 서버 측 API 없이 자체적으로 파일을 관리합니다.
* **대체 프로토콜 핸들러** — [#299](https://github.com/villagesql/villagesql-server/issues/299)는 확장이 MySQL 와이어 프로토콜이 아닌 다른 방식으로 클라이언트에 서비스를 제공할 수 있게 합니다.

MySQL의 구조 때문에 존재하는 기능이 두 가지 더 있습니다. 바이너리 로그 쓰기 및 플러시 관찰([#297](https://github.com/villagesql/villagesql-server/issues/297))과 복제 채널 관찰([#341](https://github.com/villagesql/villagesql-server/issues/341))은 모두 MySQL의 바이너리 로그와 다중 소스 복제 채널을 읽습니다. PostgreSQL은 WAL의 논리적 디코딩과 구독 메커니즘으로 비슷한 영역을 다루는데, 이는 유사한 목적을 위한 다른 설계입니다.

<h2 id="how-to-read-the-tables">
  표를 읽는 방법
</h2>

| 상태        | 의미                                                             |
| --------- | -------------------------------------------------------------- |
| **사용 가능** | 오늘 확장에서 이 작업을 수행할 수 있습니다. 해당 행에 이를 제공하는 기능 또는 SDK 함수 이름이 있습니다. |
| **부분 지원** | 일부가 오늘 작동합니다. 해당 행 또는 표 아래의 설명에 무엇이 빠져 있는지 나와 있습니다.            |
| **진행 중**  | 일부 작업이 완료되었습니다. 링크된 이슈에 나머지 작업이 있습니다.                          |
| **계획됨**   | 아직 사용할 수 없습니다. 링크된 이슈가 해당 작업을 추적합니다.                           |

**사용 가능**으로 표시되지 않은 모든 행은 해당 작업이 추적되고 논의되는 GitHub 이슈로 연결됩니다.

미리보기 기능을 통해 **사용 가능**으로 표시된 항목은 `vsql_allow_preview_extensions = ON`이 필요합니다 — [미리보기 기능](/docs/ko/mysql-9.7/stable/preview-capabilities)을 참조하세요.

<h2 id="c-and-rust">
  C++와 Rust
</h2>

VillageSQL 확장은 C++ 또는 Rust로 작성할 수 있습니다. VEF는 서버 측 기능이고 각 SDK는 그 위의 바인딩입니다. Rust 바인딩은 더 최근에 나왔기 때문에, 현재로서는 일부 기능을 C++에서만 사용할 수 있습니다.

| 기능          | C++ SDK | Rust SDK                                                                      |
| ----------- | ------- | ----------------------------------------------------------------------------- |
| 스칼라 함수(VDF) | 예       | 예                                                                             |
| 사용자 정의 유형   | 예       | 예                                                                             |
| 시스템 및 상태 변수 | 예       | 예                                                                             |
| 백그라운드 워커    | 예       | 예                                                                             |
| 키링 접근       | 예       | 예                                                                             |
| 집계 함수       | 예       | 예                                                                             |
| 로드 및 언로드 콜백 | 예       | 아직 미지원 — [rust-sdk#13](https://github.com/villagesql/vsql-rust-sdk/issues/13) |
| 확장에서 SQL 실행 | 예       | 아직 미지원 — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| 문장 완료 이벤트   | 예       | 아직 미지원 — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| 인증 방식       | 예       | 아직 미지원 — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| 확장 전용 저장소   | 예       | 아직 미지원 — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |

<h2 id="pluggable-interfaces">
  플러그형 인터페이스
</h2>

가장 널리 알려진 PostgreSQL 확장들은 아래쪽의 훅이 아니라 이 인터페이스들 위에 구축되어 있습니다. 또한 VEF가 가장 완전하게 다루는 프레임워크 영역이므로 여기에서 시작하세요.

| PostgreSQL 인터페이스       | 기능                                    | VillageSQL                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_PG_init`, `_PG_fini` | 모듈 로드 시 설정을 실행하고, 언로드 시 정리를 실행        | **사용 가능** — 확장 빌더의 `on_init()` 및 `on_deinit()`                                                                                                                                                                                                                                        |
| 사용자 정의 데이터 유형 및 연산자    | 자체 저장 및 비교 동작을 가진 새 기본 유형 등록          | **사용 가능** — [C++에서 사용자 정의 유형 만들기](/docs/ko/mysql-9.7/stable/custom-types) 참조                                                                                                                                                                                                               |
| 집계 함수                  | 사용자 정의 집계 등록                          | **사용 가능** — `make_aggregate_func`, [C++ 개발](/docs/ko/mysql-9.7/stable/development) 참조                                                                                                                                                                                                      |
| 사용자 정의 구성 변수           | 운영자가 런타임에 변경할 수 있는 설정과 읽을 수 있는 카운터 정의 | **사용 가능** — 설정에는 `vsql::sys_var`, 카운터에는 `vsql::status_var`                                                                                                                                                                                                                            |
| 백그라운드 워커               | 데이터베이스 접근이 가능한 장기 실행 프로세스를 서버 내부에서 실행 | **사용 가능** — `vsql::preview::thread_worker`                                                                                                                                                                                                                                            |
| SPI(서버 내부에서 SQL 실행)    | 확장 코드에서 SQL 실행                        | **부분 지원** — `vsql::preview::sql_query`, 아래에 명시된 제한 있음                                                                                                                                                                                                                                 |
| 집합 반환 함수               | 함수에서 결과 집합 반환                         | 계획됨 — [#549](https://github.com/villagesql/villagesql-server/issues/549)                                                                                                                                                                                                              |
| C로 작성된 프로시저            | 스칼라 함수가 아니라 `CALL`로 작업 노출             | 계획됨 — [#596](https://github.com/villagesql/villagesql-server/issues/596)                                                                                                                                                                                                              |
| 인덱스 접근 메서드             | 빌드, 유지 관리, 검색을 포함한 인덱스 유형 전체 등록       | 진행 중 — [#264](https://github.com/villagesql/villagesql-server/issues/264), [#265](https://github.com/villagesql/villagesql-server/issues/265), [#266](https://github.com/villagesql/villagesql-server/issues/266), [#268](https://github.com/villagesql/villagesql-server/issues/268) |
| 사용자 정의 스캔 제공자          | 확장이 정의한 노드를 실행기에 추가                   | 계획됨 — [#276](https://github.com/villagesql/villagesql-server/issues/276)                                                                                                                                                                                                              |
| 테이블 접근 메서드             | 행 저장, 가시성, 배큠 동작 대체                   | 계획됨 — [#290](https://github.com/villagesql/villagesql-server/issues/290), [#291](https://github.com/villagesql/villagesql-server/issues/291), [#292](https://github.com/villagesql/villagesql-server/issues/292)                                                                      |
| 외부 데이터 래퍼              | 외부 시스템을 테이블로 노출하며, 조건자 푸시다운 및 쓰기 지원   | 계획됨 — [#277](https://github.com/villagesql/villagesql-server/issues/277), [#278](https://github.com/villagesql/villagesql-server/issues/278), [#279](https://github.com/villagesql/villagesql-server/issues/279), [#280](https://github.com/villagesql/villagesql-server/issues/280)  |
| 논리적 디코딩 출력 플러그인        | 행 변경 스트림 소비                           | 계획됨 — [#283](https://github.com/villagesql/villagesql-server/issues/283), [#284](https://github.com/villagesql/villagesql-server/issues/284), [#285](https://github.com/villagesql/villagesql-server/issues/285)                                                                      |
| 확장 상태용 시스템 뷰           | 확장 상태를 쿼리 가능한 테이블로 게시                 | 계획됨 — [#271](https://github.com/villagesql/villagesql-server/issues/271)                                                                                                                                                                                                              |
| 절차적 언어                 | 저장 루틴용 언어 런타임 추가                      | 계획됨 — [#342](https://github.com/villagesql/villagesql-server/issues/342)                                                                                                                                                                                                              |

`on_init()`과 `on_deinit()`은 `_PG_init`과 달리 서버에 접근하지 않고 확장 내부에서 실행됩니다. CPU별 함수 포인터 선택과 같은 로컬 설정에 적합합니다. 서버와 통신해야 하는 설정은 기능의 populate 단계에 두어야 합니다.

`vsql::preview::sql_query`에는 SPI를 중심으로 구축된 확장에 영향을 주는 세 가지 제한이 있습니다. 문장은 바인드 인자를 받지 않으므로 값을 직접 이스케이프해야 합니다([#627](https://github.com/villagesql/villagesql-server/issues/627)). 확장은 동시 세션이 아니라 단일 세션을 사용합니다([#626](https://github.com/villagesql/villagesql-server/issues/626)). 또한 VDF 내부에서는 호출할 수 없습니다([#597](https://github.com/villagesql/villagesql-server/issues/597)).

<h2 id="hook-variables">
  훅 변수
</h2>

훅은 서버가 문장 처리 도중 확장에 제어권을 넘겨, 서버가 수행하려는 작업을 읽거나 변경할 수 있게 하는 지점입니다. PostgreSQL은 고정된 훅 집합을 전역 함수 포인터로 선언합니다. 아래 표는 그 전부를 다루며, 각 훅이 실행되는 쿼리 처리 단계별로 묶었습니다.

<h3 id="parsing-and-ddl">
  파싱 및 DDL
</h3>

| PostgreSQL 훅                                   | 기능                                         | VillageSQL                                                               |
| ---------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `post_parse_analyze_hook`                      | 구문 분석 후 문장을 검사하거나 재작성                      | 계획됨 — [#701](https://github.com/villagesql/villagesql-server/issues/701) |
| `ProcessUtility_hook`                          | DDL 및 기타 유틸리티 문장이 실행되기 전에 가로채기, 차단 또는 리디렉션 | 계획됨 — [#272](https://github.com/villagesql/villagesql-server/issues/272) |
| `object_access_hook`, `object_access_hook_str` | 카탈로그 객체가 생성, 변경, 삭제 또는 접근될 때 알림 수신         | 계획됨 — [#270](https://github.com/villagesql/villagesql-server/issues/270) |

<h3 id="planner">
  플래너
</h3>

| PostgreSQL 훅                                      | 기능                           | VillageSQL                                                               |
| ------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| `planner_hook`                                    | 문장에 대한 플래너를 감싸거나 대체          | 계획됨 — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `set_rel_pathlist_hook`                           | 테이블 하나에 대한 후보 스캔 경로 추가 또는 제거 | 계획됨 — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `set_join_pathlist_hook`                          | 후보 조인 경로 추가 또는 제거            | 계획됨 — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `join_search_hook`                                | 조인 순서 탐색 자체를 대체              | 계획됨 — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `create_upper_paths_hook`                         | 그룹화 및 정렬과 같은 스캔 이후 단계의 경로 추가 | 계획됨 — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `get_relation_info_hook`                          | 플래너가 보는 릴레이션 및 인덱스 메타데이터 조정  | 계획됨 — [#268](https://github.com/villagesql/villagesql-server/issues/268) |
| `get_relation_stats_hook`, `get_index_stats_hook` | 카탈로그 대신 열 또는 인덱스의 통계 제공      | 계획됨 — [#274](https://github.com/villagesql/villagesql-server/issues/274) |
| `get_attavgwidth_hook`                            | 비용 추정을 위한 평균 열 너비 제공         | 계획됨 — [#274](https://github.com/villagesql/villagesql-server/issues/274) |

<h3 id="executor">
  실행기
</h3>

| PostgreSQL 훅              | 기능                             | VillageSQL                                                               |
| ------------------------- | ------------------------------ | ------------------------------------------------------------------------ |
| `ExecutorStart_hook`      | 쿼리 실행이 시작되기 전에 실행              | 계획됨 — [#702](https://github.com/villagesql/villagesql-server/issues/702) |
| `ExecutorRun_hook`        | 마스킹, 변환 또는 행별 집계를 위해 행 생성을 감싸기 | 계획됨 — [#289](https://github.com/villagesql/villagesql-server/issues/289) |
| `ExecutorFinish_hook`     | 마지막 행 이후, 정리 전에 실행             | 계획됨 — [#287](https://github.com/villagesql/villagesql-server/issues/287) |
| `ExecutorEnd_hook`        | 완료된 문장과 그 실행 통계 관찰             | **사용 가능** — `vsql::preview::statement_event`, post-execute 단계            |
| `ExecutorCheckPerms_hook` | 문장에 필요한 테이블 및 열 권한 승인 또는 거부    | 계획됨 — [#314](https://github.com/villagesql/villagesql-server/issues/314) |

연산자별 세부 정보가 필요한 PostgreSQL 확장은 노드 수준에서 `ExecutorRun_hook`을 감싸서 이를 얻습니다. VEF에서 이는 별도 작업이며 [#340](https://github.com/villagesql/villagesql-server/issues/340)에서 추적됩니다.

<h3 id="explain">
  EXPLAIN
</h3>

| PostgreSQL 훅                    | 기능                      | VillageSQL                                                               |
| ------------------------------- | ----------------------- | ------------------------------------------------------------------------ |
| `ExplainOneQuery_hook`          | 문장을 설명하는 방식을 대체하거나 확장   | 계획됨 — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_per_plan_hook`         | 설명된 계획마다 한 번씩 확장 출력 추가  | 계획됨 — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_per_node_hook`         | 각 계획 노드마다 확장 출력 추가      | 계획됨 — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_get_index_name_hook`   | 출력에 표시되는 인덱스 이름 재정의     | 계획됨 — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_validate_options_hook` | 확장이 정의한 `EXPLAIN` 옵션 허용 | 계획됨 — [#317](https://github.com/villagesql/villagesql-server/issues/317) |

<h3 id="authentication-and-security">
  인증 및 보안
</h3>

| PostgreSQL 훅                                                                  | 기능                             | VillageSQL                                                               |
| ----------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------ |
| `ClientAuthentication_hook`                                                   | 인증에 참여하고 그 결과를 관찰              | **부분 지원** — 아래 참조                                                        |
| `check_password_hook`                                                         | 비밀번호 설정 시 비밀번호 정책 적용           | 계획됨 — [#456](https://github.com/villagesql/villagesql-server/issues/456) |
| `ldap_password_hook`                                                          | `ldap` 인증 방식이 사용하는 LDAP 바인드 대체 | **사용 가능** — `vsql::preview::auth`로 인증 방식 자체를 구현                          |
| `openssl_tls_init_hook`                                                       | 시작 시 서버의 TLS 컨텍스트 조정           | 계획됨 — [#458](https://github.com/villagesql/villagesql-server/issues/458) |
| `row_security_policy_hook_permissive`, `row_security_policy_hook_restrictive` | 세션을 기준으로 쿼리에 행 필터 조건자 추가       | 계획됨 — [#315](https://github.com/villagesql/villagesql-server/issues/315) |

PostgreSQL 확장은 `ClientAuthentication_hook`을 두 가지 다른 용도로 사용하며, VEF는 그중 하나를 다룹니다. 확장은 `vsql::preview::auth` 기능을 통해 자체 인증 방식을 구현할 수 있으며, `vsql-oauth2`가 이 위에 구축되어 있습니다. 아직 직접 처리하지 않은 인증의 결과는 관찰할 수 없는데, 이는 PostgreSQL의 `auth_delay`와 로그인 실패 추적기가 작동하는 방식입니다. 그 부분은 [#464](https://github.com/villagesql/villagesql-server/issues/464)입니다.

PostgreSQL은 훅이 아니라 `pg_ident.conf`를 통해 외부 ID를 데이터베이스 계정에 매핑합니다. VEF는 동일한 `vsql::preview::auth` 기능으로 이를 다룹니다. `set_active_roles()`는 인증 플러그인이 외부 ID를 확인한 후 세션에 역할을 할당할 수 있게 하고, `auto_grant_roles()`는 토큰의 클레임을 기준으로 역할을 자동으로 부여하는 콜백을 등록합니다. 둘 다 `villagesql/sdk/include/villagesql/preview/auth.h`에 선언되어 있습니다.

<h3 id="logging">
  로깅
</h3>

| PostgreSQL 훅    | 기능                                   | VillageSQL                                                               |
| --------------- | ------------------------------------ | ------------------------------------------------------------------------ |
| `emit_log_hook` | 각 로그 메시지가 기록되기 전에 확인하고 필터링하거나 다시 라우팅 | 계획됨 — [#316](https://github.com/villagesql/villagesql-server/issues/316) |

<h3 id="startup-and-shared-memory">
  시작 및 공유 메모리
</h3>

| PostgreSQL 훅         | 기능                | VillageSQL                                                               |
| -------------------- | ----------------- | ------------------------------------------------------------------------ |
| `shmem_request_hook` | 시작 중 공유 메모리 요청    | 계획됨 — [#282](https://github.com/villagesql/villagesql-server/issues/282) |
| `shmem_startup_hook` | 공유 메모리가 생성된 후 초기화 | 계획됨 — [#282](https://github.com/villagesql/villagesql-server/issues/282) |

<h3 id="function-manager">
  함수 관리자
</h3>

| PostgreSQL 훅                   | 기능                                | VillageSQL                                                               |
| ------------------------------ | --------------------------------- | ------------------------------------------------------------------------ |
| `fmgr_hook`, `needs_fmgr_hook` | 감사 또는 샌드박싱을 위해 모든 함수 호출 전후에 코드 실행 | 계획됨 — [#287](https://github.com/villagesql/villagesql-server/issues/287) |

<h2 id="tell-us-what-you-need">
  필요한 기능을 알려주세요
</h2>

우리는 확장 작성자의 요청을 기준으로 이 작업의 우선순위를 정합니다. 위 항목 중 하나가 구축하려는 확장을 가로막고 있다면, 해당 이슈에 👍를 추가하고 댓글로 사용 사례를 설명해 주세요.