> ## 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.

# 시스템 참조

> 확장 메타데이터 및 서버 상태를 쿼리하는 VillageSQL 시스템 뷰와 변수

아래 표준 SQL 인터페이스를 사용하여 확장 메타데이터 및 서버 상태를 쿼리합니다.

***

## 시스템 뷰

### INFORMATION\_SCHEMA.EXTENSIONS

현재 설치된 VillageSQL 확장을 모두 나열합니다.

> [!NOTE]
>
> `INSTALL EXTENSION` 및 `UNINSTALL EXTENSION`은 VillageSQL SQL 확장입니다.
> 이는 표준 MySQL 8.4 구문의 일부가 아닙니다.

**알려진 열:**

| 열 | 유형 | 설명 |
| - | - | - |
| `EXTENSION_NAME` | varchar | 설치된 확장의 이름 |
| `EXTENSION_VERSION` | varchar | 확장의 `manifest.json`에 있는 버전 문자열 |
| `PENDING_VERSION` | longtext | 다음 재시작 시 확장이 변경될 버전, 또는 `NULL` |
| `PENDING_REQUESTED_AT` | longtext | 대기 중인 버전 변경이 요청된 시점, 또는 `NULL` |
| `PENDING_LAST_ERROR` | longtext | 실패한 버전 변경에서 발생한 메시지, 또는 `NULL` |
| `PENDING_LAST_ERROR_AT` | longtext | 해당 실패가 기록된 시점, 또는 `NULL` |

**예시:**

```sql theme={null}
-- Install an extension (VillageSQL-specific syntax)
INSTALL EXTENSION vsql_complex;

-- List all installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

-- Check a specific extension's version
SELECT EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_complex';
```

**예시 출력** (실제 버전 문자열은 설치된 확장에 따라 다름):

```
+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
| vsql_uuid        | 0.0.8             |
+------------------+-------------------+
```

`EXTENSION_NAME` 값은 확장의 `manifest.json`에 있는 `name` 필드와 일치합니다.

이 뷰는 현재 설치된 상태를 반영합니다.

네 개의 `PENDING_*` 열은 예약된 `ALTER EXTENSION ... AT RESTART`
버전 변경을 추적합니다. 워크플로에 대해서는 [확장 관리](https://villagesql.com/docs/ko/extensions/managing.md)를 참조하세요.

***

### INFORMATION\_SCHEMA.COLUMNS (사용자 정의 유형)

사용자 정의 확장 유형을 사용하는 열은 표준 `INFORMATION_SCHEMA.COLUMNS` 뷰를 통해 표시됩니다. 사용자 정의 유형은 `DATA_TYPE` 및 `COLUMN_TYPE` 열에서 `extension_name.type_name` 형식으로 표시됩니다 (예: `vsql_complex.COMPLEX`).

**예시:**

```sql theme={null}
-- Find all columns using custom extension types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE '%.%'
ORDER BY TABLE_SCHEMA, TABLE_NAME;

-- Find columns using a specific extension's types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

**샘플 출력:**

```
+--------------+------------+-------------+---------------------+
| TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | DATA_TYPE           |
+--------------+------------+-------------+---------------------+
| mydb         | signals    | impedance   | vsql_complex.COMPLEX|
| mydb         | signals    | frequency   | vsql_complex.COMPLEX|
+--------------+------------+-------------+---------------------+
```

***

### INFORMATION\_SCHEMA.EXTENSION\_REGISTRATION

로드된 각 확장에 대한 메모리 내 VEF 등록 구조체를 JSON 문서로 노출합니다. `INSTALL EXTENSION` 후 서버가 확장의 함수와 유형을 올바르게 해석했는지 확인하기 위해 사용합니다.

```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL, REGISTRATION_JSON
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION
WHERE EXTENSION_NAME = 'vsql_complex';
```

| 열 | 유형 | 설명 |
| - | - | - |
| `EXTENSION_NAME` | `VARCHAR(64)` | 설치된 확장의 이름. |
| `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | 확장과 서버 간 협상된 VEF 프로토콜 버전. |
| `REGISTRATION_JSON` | `VARCHAR(65535)` | `vef_registration_t` 구조체의 JSON 직렬화로, `funcs` 및 `types` 배열과 확장이 빌드된 SDK 버전을 보고하는 `sdk_version` 키를 포함합니다. |

***

## 일반 쿼리

### 확장 종속성 찾기

제거하기 전에 특정 확장의 유형을 사용하는 열을 찾습니다:

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

### 모든 확장 및 사용자 정의 유형 열 목록

```sql theme={null}
-- All installed extensions
SELECT EXTENSION_NAME, EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
ORDER BY EXTENSION_NAME;

-- All columns using custom types across all extensions
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE '%.%'
ORDER BY DATA_TYPE, TABLE_SCHEMA, TABLE_NAME;
```

### 확장 유형을 사용하는 테이블 찾기

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%'
ORDER BY TABLE_SCHEMA, TABLE_NAME;
```

***

## 시스템 변수

### veb\_dir

런타임 시 읽기 전용입니다. 서버가 `.veb` 확장 패키지 파일을 찾는 디렉토리 경로입니다. `[mysqld]` 섹션의 `my.cnf`에서 설정해야 하며, 서버 재시작 없이는 변경할 수 없습니다.

```sql theme={null}
SHOW VARIABLES LIKE 'veb_dir';
```

**범위:** 글로벌, 런타임 시 읽기 전용입니다. `my.cnf`에서 구성합니다:

```ini theme={null}
[mysqld]
veb_dir=/path/to/extensions/
```

단일 디렉토리만 지원됩니다. 배치 및 문제 해결을 위해 [확장 관리](https://villagesql.com/docs/ko/extensions/managing.md)를 참조하세요.

***

### villagesql\_server\_version

읽기 전용 글로벌 변수입니다. 서버 바이너리에 컴파일된 VillageSQL 버전 문자열을 반환합니다. 형식은
`{codebase}_{major}.{minor}.{patch}[-prerelease]`이며, 여기서 `codebase`는
이 빌드가 파생된 상위 포크의 이름입니다 (여기서는 `mysql-8.4`). 이는
내부 메타데이터 카탈로그에 찍힌 버전을 동일한 `{codebase}_{version}` 형식으로
보고하는 `villagesql_schema_version`과 구분됩니다.

```sql theme={null}
SELECT @@villagesql_server_version;
-- Example output: mysql-8.4_0.0.7

-- All VillageSQL system variables at once. Not every one of them starts with
-- villagesql_, so a LIKE 'villagesql_%' pattern on its own misses some.
SHOW VARIABLES WHERE Variable_name LIKE 'villagesql\_%'
  OR Variable_name IN ('veb_dir', 'vsql_allow_preview_extensions');
```

**범위:** 글로벌, 읽기 전용입니다. 런타임 시 설정할 수 없습니다.

***

### villagesql\_schema\_version

읽기 전용 글로벌 변수입니다. 내부 메타데이터 카탈로그에 찍힌 버전을 `villagesql_server_version`과 동일한 `{codebase}_{version}` 형식으로 반환합니다. 빈 문자열은 이 데이터 디렉터리에서 VillageSQL 스키마가 초기화되지 않았음을 의미합니다.

```sql theme={null}
SELECT @@villagesql_schema_version;
-- Example output: mysql-8.4_0.0.7
```

**범위:** 글로벌, 읽기 전용입니다. 런타임 시 설정할 수 없습니다.

***

### villagesql\_vef\_server\_protocol

읽기 전용 글로벌 변수입니다. 이 서버 빌드에서 지원하는 가장 높은 VEF 프로토콜 버전을 반환합니다. 확장을 설치할 때 서버와 확장은 양쪽 모두 지원하는 가장 높은 프로토콜 버전을 사용합니다. 폐기된 불안정 프로토콜 버전으로 빌드된 확장은 설치할 수 없으며, `INSTALL EXTENSION`이 `Failed to load VEF extension` 오류로 실패합니다.

```sql theme={null}
SELECT @@villagesql_vef_server_protocol;
```

| 속성 | 값 |
| - | - |
| **범위** | 글로벌 |
| **접근** | 읽기 전용 |
| **유형** | 부호 없는 정수 (`0`–`255`) |
| **현재 값** | `4` (`VEF_PROTOCOL_4`) |

프로토콜 V4는 가변 길이 커스텀 유형 지원을 추가하고, 함수가 문자열 결과의
최대 길이를 선언할 수 있게 합니다. 또한 `on_init` / `on_deinit` 로드 및
언로드 훅을 추가하며, 서버는 확장이 요구하는 기능이 채워진 후와 해제되기 전에
이 훅을 호출합니다. 세 번째 추가 사항은 `bind_and_check_types`로, 함수가
내장 명확화 규칙에 의존하는 대신 해석 시점에 자신의 반환 유형 매개변수를
직접 결정할 수 있게 하는 훅입니다. V4는 옵트인 개발용 ABI에서 활발히 개발
중이며 안정화되기 전에 변경될 수 있습니다. 확장을 개발하는 경우, 각 프로토콜
버전에서 사용할 수 있는 기능은
[유형 연산](https://villagesql.com/docs/ko/sdk/cpp/type-operations.md)과
[C++로 확장 만들기](https://villagesql.com/docs/ko/extensions/build/create.md)를 참조하세요.

이 값은 컴파일 타임 상수 `vef_server_protocol_version`을 반영하며, 런타임 시 변경할 수 없습니다.

***

### villagesql\_build\_info

읽기 전용 글로벌 변수입니다. 이 서버 바이너리가 어떻게 빌드되었는지에 대한
메타데이터를 담은 JSON 객체를 반환합니다: 소스 커밋, 작업 트리 상태 및 빌드
환경.

```sql theme={null}
SELECT @@villagesql_build_info;
```

| 필드 | 유형 | 설명 |
| - | - | - |
| `git_sha` | string | 전체 40자 소스 커밋 SHA, 또는 사용할 수 없는 경우 `"unknown"` |
| `is_dirty` | bool | 빌드 시 작업 트리에 커밋되지 않은 변경 사항이 있었으면 `true` |
| `files_added` | integer | 빌드 시 추가되거나 추적되지 않은 파일 |
| `files_deleted` | integer | 빌드 시 삭제된 파일 |
| `files_modified` | integer | 빌드 시 수정된 파일 |
| `build_timestamp` | string | ISO-8601 UTC 타임스탬프, 예: `"2026-06-17T12:34:56Z"`. 릴리스 빌드에서는 비어 있습니다 |
| `build_host` | string | 빌드 머신의 호스트 이름. 릴리스 빌드에서는 비어 있습니다 |
| `build_os` | string | 빌드 머신에서 `uname -s`와 `uname -r`이 보고하는 호스트 운영 체제와 커널 버전, 예: `"Linux-6.18.15"` |
| `build_arch` | string | 호스트 CPU 아키텍처: `"x86_64"`, `"aarch64"` 또는 `"arm64"` |

**범위:** 글로벌, 읽기 전용입니다. 런타임 시 설정할 수 없습니다.

수정된 작업 트리에서 빌드하면 `files_added`, `files_deleted` 또는 `files_modified`에
0이 아닌 개수가 표시되며, 이 경우 `is_dirty`는 `true`가 됩니다. 릴리스 빌드
(버전에 사전 릴리스 접미사가 없는 빌드)는 동일한 소스에서 동일한 바이너리가
생성되도록 이 세 개의 카운트를 강제로 0으로 만들고 `build_timestamp`와
`build_host`를 비워 둡니다. 이것이 릴리스 빌드에서 `is_dirty`가 항상 `false`인
이유입니다.

***

### vsql\_allow\_preview\_extensions

서버가 미리보기 기능이 필요한 확장을 허용할지 여부를 제어합니다. `OFF`인 동안에는 해당 확장 설치가 실패합니다:

```text theme={null}
ERROR 3219 (HY000): Failed to load VEF extension 'vsql_keyring_reader': extension requires preview capabilities but vsql_allow_preview_extensions is OFF
```

`SET PERSIST`로 켭니다:

```sql theme={null}
SET PERSIST vsql_allow_preview_extensions = ON;
```

| 속성 | 값 |
| - | - |
| **범위** | 글로벌 |
| **접근** | 읽기 가능; `SET PERSIST`로 설정 |
| **유형** | 불리언 |
| **기본값** | `OFF` |

`SET GLOBAL`이 아니라 `SET PERSIST`를 사용하세요. 미리보기 확장은 서버 시작 시 로드되므로 이 값은 재시작 후에도 유지되어야 하며, `mysqld-auto.cnf`에 값을 기록하는 것은 `SET PERSIST`뿐입니다. 그런 이유로 `SET GLOBAL`은 거부됩니다. 첫 시작 전에 켜려면 `mysqld` 명령줄에서 `--vsql_allow_preview_extensions=ON`을 전달하세요.

미리보기 기능을 사용하는 확장이 하나라도 설치되어 있는 동안에는 이 값을 다시 OFF로 되돌릴 수 없습니다. 서버 시작 시 이 설정이 ON이어야 하기 때문입니다. 먼저 해당 확장을 제거하세요.

사용 가능한 미리보기 기능 목록과 확장이 이를 어떻게 사용하는지는 [미리보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities.md)을 참조하세요.

***

## 다음 단계

> [card] [확장 관리](https://villagesql.com/docs/ko/extensions/managing.md)
>
> 확장 모니터링 및 문제 해결

> [card] [확장 설치](https://villagesql.com/docs/ko/extensions/install.md)
>
> 새로운 확장 추가

> [card] [확장 아키텍처](https://villagesql.com/docs/ko/extensions/build/architecture.md)
>
> 내부 구조 이해

> [card] [사용 가능한 확장](https://villagesql.com/docs/ko/extensions/catalog)
>
> 확장 카탈로그 브라우징


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.