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

**알려진 열:**

| 열                       | 유형      | 설명                             |
| ----------------------- | ------- | ------------------------------ |
| `EXTENSION_NAME`        | varchar | 설치된 확장의 이름                     |
| `EXTENSION_VERSION`     | varchar | 확장에서 보고한 버전 문자열                |
| `PENDING_VERSION`       | text    | 다음 재시작 시 확장이 변경될 버전, 또는 `NULL` |
| `PENDING_REQUESTED_AT`  | text    | 대기 중인 버전 변경이 요청된 시점, 또는 `NULL` |
| `PENDING_LAST_ERROR`    | text    | 실패한 버전 변경에서 발생한 메시지, 또는 `NULL` |
| `PENDING_LAST_ERROR_AT` | text    | 해당 실패가 기록된 시점, 또는 `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-8.4/0.0.5/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`   | `longtext`        | `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-8.4/0.0.5/managing)를 참조하세요.

***

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

-- Show all VillageSQL system variables at once
SHOW VARIABLES LIKE 'villagesql_%';
```

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

***

### villagesql\_vef\_server\_protocol

읽기 전용 글로벌 변수입니다. 이 서버 빌드에서 지원하는 가장 높은 VEF 프로토콜 버전을 반환합니다. 확장 작성자는 이 값을 `types.h`의 프로토콜 상수와 비교하여 등록 중 사용 가능한 ABI 기능을 결정할 수 있습니다.

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

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

**프로토콜 V4가 추가하는 것**

`VEF_PROTOCOL_4` 이상을 협상하는 확장은 `vef_type_desc_t`의
`variable_length` 필드에 접근할 수 있습니다. `true`로 설정되면 해당
유형의 저장 크기는 단일 고정 크기가 아니라 값별로 결정됩니다.
가변 길이 유형은 상한값으로 `max_persisted_length`도 선언해야 합니다.
이 플래그를 설정하려면 `TypeBuilder`의 `variable_length_type()` 빌더
메서드를 사용하세요 — `variable_length`를 직접 설정하지 마세요.
이 필드는 협상된 프로토콜이 `VEF_PROTOCOL_4` 이상일 때만 서버가 읽습니다.

`VEF_PROTOCOL_4`는 또한 `vef_func_desc_t`에 `max_result_length` 필드를 추가합니다.
함수는 자신의 `STRING` 결과의 최대 길이 (문자 단위)를 선언하여, 구체화된 결과 —
GROUP BY/DISTINCT 임시 테이블, `CREATE TABLE ... SELECT`,
UNION — 가 인수 너비에서 잘리지 않고 전체 값을 담도록 할 수 있습니다. `0`은
인수 너비로 대체되며, STRING 전용이고
`VEF_MAX_RESULT_LENGTH` (16 MiB / 16777216 바이트)로 제한됩니다. 선언된 값이 더 크면
이 값으로 제한됩니다. `FuncBuilder`의 `max_result_length()` 빌더 메서드로
설정합니다.

프로토콜 V4는 활발히 개발 중입니다. 옵트인하는 확장은
`-DVSQL_USE_DEV_ABI=ON`으로 빌드해야 하며, 안정화되기 전에 ABI 변경을
예상해야 합니다.

전체 `vef_type_desc_t` 및 `vef_func_desc_t` 정의는 `abi/types.h`,
`variable_length_type()`는 `type_builder.h`, `max_result_length()`는
`func_builder.h`를 참조하세요.

이 값은 컴파일 타임 상수 `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"` 또는 `"macos"`                  |
| `build_arch`      | string  | 호스트 CPU 아키텍처: `"x86_64"`, `"aarch64"` 또는 `"arm64"` |

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

깨끗한 릴리스 빌드는 `is_dirty: false`이며 세 개의 파일 개수 필드가 모두 0입니다.
수정된 작업 트리에서 빌드하면 `files_added`,
`files_deleted` 또는 `files_modified`에 0이 아닌 개수가 표시됩니다.

***

## 다음 단계

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

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

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

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