> ## 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. # System Reference > VillageSQL system views and variables for querying extension metadata and server state Query extension metadata and server state using the standard SQL interfaces below. *** ## System Views ### INFORMATION\_SCHEMA.EXTENSIONS Lists all currently installed VillageSQL extensions. `INSTALL EXTENSION` and `UNINSTALL EXTENSION` are VillageSQL SQL extensions. They are not part of standard MySQL 9.7 syntax. **Known columns:** | Column | Type | Description | | ----------------------- | -------- | ------------------------------------------------------------------- | | `EXTENSION_NAME` | varchar | Name of the installed extension | | `EXTENSION_VERSION` | varchar | Version string reported by the extension | | `PENDING_VERSION` | longtext | Version the extension will change to at the next restart, or `NULL` | | `PENDING_REQUESTED_AT` | longtext | When a pending version change was requested, or `NULL` | | `PENDING_LAST_ERROR` | longtext | Message from a failed version change, or `NULL` | | `PENDING_LAST_ERROR_AT` | longtext | When that failure was recorded, or `NULL` | **Example:** ```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'; ``` **Illustrative output** (actual version strings depend on installed extensions): ``` +------------------+-------------------+ | EXTENSION_NAME | EXTENSION_VERSION | +------------------+-------------------+ | vsql_complex | 0.0.1 | | vsql_uuid | 0.2.1 | +------------------+-------------------+ ``` `EXTENSION_NAME` values are lowercase, matching the name passed to `make_extension()`. The view reflects the current installed state. The four `PENDING_*` columns track a scheduled `ALTER EXTENSION ... AT RESTART` version change. See [Managing Extensions](/docs/mysql-9.7/dev/managing) for the workflow. *** ### INFORMATION\_SCHEMA.COLUMNS (Custom Types) Columns using custom extension types are visible through the standard `INFORMATION_SCHEMA.COLUMNS` view. Custom types appear as `extension_name.type_name` in the `DATA_TYPE` and `COLUMN_TYPE` columns (e.g., `vsql_complex.COMPLEX`). **Example:** ```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.%'; ``` **Sample Output:** ``` +--------------+------------+-------------+---------------------+ | TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | DATA_TYPE | +--------------+------------+-------------+---------------------+ | mydb | signals | impedance | vsql_complex.COMPLEX| | mydb | signals | frequency | vsql_complex.COMPLEX| +--------------+------------+-------------+---------------------+ ``` *** ### INFORMATION\_SCHEMA.EXTENSION\_REGISTRATION Exposes the in-memory VEF registration struct for each loaded extension as a JSON document. Use it to verify that the server parsed your extension's functions, types, and system variables correctly after `INSTALL EXTENSION`. ```sql theme={null} SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL, REGISTRATION_JSON FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION WHERE EXTENSION_NAME = 'vsql_complex'; ``` | Column | Type | Description | | --------------------- | ----------------- | -------------------------------------------------------------------------------------------- | | `EXTENSION_NAME` | `VARCHAR(64)` | Name of the installed extension. | | `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | VEF protocol version negotiated between the extension and the server. | | `REGISTRATION_JSON` | `VARCHAR(65535)` | JSON serialization of the `vef_registration_t` struct, including `funcs` and `types` arrays. | *** ## Common Queries ### Find Extension Dependencies Find which columns use a specific extension's types before uninstalling: ```sql theme={null} SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE DATA_TYPE LIKE 'vsql_complex.%'; ``` ### List All Extensions and Their Custom Type Columns ```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; ``` ### Find Tables Using Extension Types ```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; ``` *** ## System Variables ### veb\_dir Read-only at runtime. Path to the directory where the server looks for `.veb` extension bundle files. Set in `my.cnf` under `[mysqld]`; cannot be changed without a server restart. ```sql theme={null} SHOW VARIABLES LIKE 'veb_dir'; ``` **Scope:** Global, read-only at runtime. Configure in `my.cnf`: ```ini theme={null} [mysqld] veb_dir=/path/to/extensions/ ``` Only a single directory is supported. See [Managing Extensions](/docs/mysql-9.7/dev/managing) for placement and troubleshooting. *** ### villagesql\_server\_version Read-only global variable. Returns the VillageSQL version string compiled into the server binary. The format is `{codebase}_{major}.{minor}.{patch}[-prerelease]`, where `codebase` names the upstream fork this build derives from (here, `mysql-9.7`). This is distinct from `villagesql_schema_version`, which reports the version stamped on the internal metadata catalog in the same `{codebase}_{version}` format. ```sql theme={null} SELECT @@villagesql_server_version; -- Example output: mysql-9.7_0.0.6-dev -- 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'); ``` **Scope:** Global, read-only. Cannot be set at runtime. *** ### villagesql\_schema\_version Read-only global variable. Returns the version stamped on the internal metadata catalog, in the same `{codebase}_{version}` format as `villagesql_server_version`. An empty string means the VillageSQL schema has not been initialized in this data directory. ```sql theme={null} SELECT @@villagesql_schema_version; -- Example output: mysql-9.7_0.0.6-dev ``` **Scope:** Global, read-only. Cannot be set at runtime. *** ### villagesql\_vef\_server\_protocol Read-only global variable. Returns the highest VEF protocol version supported by this server build. When an extension is installed, the server and the extension settle on the highest protocol version both support. An extension built against an obsolete unstable protocol version cannot be installed — `INSTALL EXTENSION` fails with `Failed to load VEF extension`. ```sql theme={null} SELECT @@villagesql_vef_server_protocol; ``` | Property | Value | | ----------------- | ---------------------------- | | **Scope** | Global | | **Access** | Read-only | | **Type** | Unsigned integer (`0`–`255`) | | **Current value** | `4` (`VEF_PROTOCOL_4`) | Protocol V4 adds support for variable-length custom types and lets a function declare the maximum length of its string results. It is under active development behind the opt-in dev ABI and may change before it stabilises. If you are developing extensions, see [Type Operations](/docs/mysql-9.7/dev/type-operations) and [Creating Extensions in C++](/docs/mysql-9.7/dev/create) for what each protocol version enables. The value reflects the compile-time constant `vef_server_protocol_version` and cannot be changed at runtime. *** ### villagesql\_build\_info Read-only global variable. Returns a JSON object with metadata about how this server binary was built: the source commit, work-tree state, and build environment. ```sql theme={null} SELECT @@villagesql_build_info; ``` | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | `git_sha` | string | Full 40-character source commit SHA, or `"unknown"` if unavailable | | `is_dirty` | bool | `true` if the work tree had uncommitted changes at build time | | `files_added` | integer | Added or untracked files at build time | | `files_deleted` | integer | Deleted files at build time | | `files_modified` | integer | Modified files at build time | | `build_timestamp` | string | ISO-8601 UTC timestamp, e.g. `"2026-06-17T12:34:56Z"`; empty on a release build | | `build_host` | string | Hostname of the build machine; empty on a release build | | `build_os` | string | Host operating system and kernel version, as `uname -s` and `uname -r` report them on the build machine, e.g. `"Linux-6.18.15"` | | `build_arch` | string | Host CPU architecture: `"x86_64"`, `"aarch64"`, or `"arm64"` | **Scope:** Global, read-only. Cannot be set at runtime. A build from a modified work tree shows non-zero counts in `files_added`, `files_deleted`, or `files_modified`, and `is_dirty` is then `true`. A release build — one whose version carries no pre-release suffix — forces those three counts to zero and leaves `build_timestamp` and `build_host` empty so that identical sources produce an identical binary, which is why `is_dirty` is always `false` on a release. *** ### vsql\_allow\_preview\_extensions Controls whether the server accepts extensions that require a preview capability. While it is `OFF`, installing one fails: ```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 ``` Turn it on with `SET PERSIST`: ```sql theme={null} SET PERSIST vsql_allow_preview_extensions = ON; ``` | Property | Value | | ----------- | -------------------------------- | | **Scope** | Global | | **Access** | Readable; set with `SET PERSIST` | | **Type** | Boolean | | **Default** | `OFF` | Use `SET PERSIST`, not `SET GLOBAL`. Preview extensions are loaded at server startup, so the value has to survive a restart, and only `SET PERSIST` writes it to `mysqld-auto.cnf`; `SET GLOBAL` is rejected for that reason. Before `mysqld-auto.cnf` exists — on a server being started for the first time — pass `--vsql_allow_preview_extensions=ON` on the `mysqld` command line instead. Turning it back off is rejected while any extension using a preview capability is still installed, because those extensions require the setting to be ON when the server starts. Uninstall them first. See [Preview Capabilities](/docs/mysql-9.7/dev/preview-capabilities) for the list of preview capabilities and what an extension does with them. *** ## Next Steps Monitor and troubleshoot extensions Add new extensions Understand the internals Browse extension catalog