> ## 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 9.7 구문의 일부가 아닙니다.
</Note>

**알려진 열:**

| 열                       | 유형       | 설명                             |
| ----------------------- | -------- | ------------------------------ |
| `EXTENSION_NAME`        | varchar  | 설치된 확장의 이름                     |
| `EXTENSION_VERSION`     | varchar  | 확장에서 보고한 버전 문자열                |
| `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.2.1             |
+------------------+-------------------+
```

`EXTENSION_NAME` 값은 `make_extension()`에 전달된 이름과 일치하는 소문자입니다.

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

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

***

### 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` 배열을 포함합니다. |

***

## 일반 쿼리

### 확장 종속성 찾기

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

```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/
```

단일 디렉토리만 지원됩니다. 배치 및 문제 해결을 위해 [확장 관리](/docs/ko/mysql-9.7/stable/managing)를 참조하세요.

***

### villagesql\_server\_version

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

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

-- 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-9.7_0.0.6
```

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

***

### 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는 가변 길이 커스텀 유형 지원을 추가하고, 함수가 문자열 결과의
최대 길이를 선언할 수 있게 합니다. V4는 옵트인 개발용 ABI에서 활발히 개발
중이며 안정화되기 전에 변경될 수 있습니다. 확장을 개발하는 경우, 각 프로토콜
버전에서 사용할 수 있는 기능은
[유형 연산](/docs/ko/mysql-9.7/stable/type-operations)과
[C++로 확장 만들기](/docs/ko/mysql-9.7/stable/create)를 참조하세요.

이 값은 컴파일 타임 상수 `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  | 호스트 운영 체제: `"Linux-6.18.15"` 또는 `"Darwin-24.3.0"`                  |
| `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;
```

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

`SET GLOBAL`이 아니라 `SET PERSIST`를 사용하세요. 미리보기 확장은 서버 시작 시 로드되므로 이 값은 재시작 후에도 유지되어야 하며, `mysqld-auto.cnf`에 값을 기록하는 것은 `SET PERSIST`뿐입니다. 그런 이유로 `SET GLOBAL`은 거부됩니다. `mysqld-auto.cnf`가 아직 존재하지 않는 경우(서버를 처음 시작하는 경우 등)에는 대신 `mysqld` 명령줄에서 `--vsql_allow_preview_extensions=ON`을 전달하세요.

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

사용 가능한 미리보기 기능 목록과 확장이 이를 어떻게 사용하는지는 [미리보기 기능](/docs/ko/mysql-9.7/stable/preview-capabilities)을 참조하세요.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="확장 관리" icon="sliders" href="/docs/ko/mysql-9.7/stable/managing">
    확장 모니터링 및 문제 해결
  </Card>

  <Card title="확장 설치" icon="download" href="/docs/ko/mysql-9.7/stable/install">
    새로운 확장 추가
  </Card>

  <Card title="확장 아키텍처" icon="sitemap" href="/docs/ko/mysql-9.7/stable/architecture">
    내부 구조 이해
  </Card>

  <Card title="사용 가능한 확장" icon="list" href="/docs/ko/mysql-9.7/stable/extensions">
    확장 카탈로그 브라우징
  </Card>
</CardGroup>