System Reference

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:

-- 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 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:

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

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:

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

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

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.

SHOW VARIABLES LIKE 'veb_dir';

Scope: Global, read-only at runtime. Configure in my.cnf:

[mysqld]
veb_dir=/path/to/extensions/

Only a single directory is supported. See Managing Extensions 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.

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.

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.

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 and Creating Extensions in C++ 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.

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:

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:

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 for the list of preview capabilities and what an extension does with them.

Next Steps

Managing Extensions

Monitor and troubleshoot extensions

Install Extensions

Add new extensions

Extension Architecture

Understand the internals

Available Extensions

Browse extension catalog

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

System Views

INFORMATION_SCHEMA.EXTENSIONS

INFORMATION_SCHEMA.COLUMNS (Custom Types)

INFORMATION_SCHEMA.EXTENSION_REGISTRATION

Common Queries

Find Extension Dependencies

List All Extensions and Their Custom Type Columns

Find Tables Using Extension Types

System Variables

veb_dir

villagesql_server_version

villagesql_schema_version

villagesql_vef_server_protocol

villagesql_build_info

vsql_allow_preview_extensions

Next Steps

Managing Extensions

Install Extensions

Extension Architecture

Available Extensions

​System Views

​INFORMATION_SCHEMA.EXTENSIONS

​INFORMATION_SCHEMA.COLUMNS (Custom Types)

​INFORMATION_SCHEMA.EXTENSION_REGISTRATION

​Common Queries

​Find Extension Dependencies

​List All Extensions and Their Custom Type Columns

​Find Tables Using Extension Types

​System Variables

​veb_dir

​villagesql_server_version

​villagesql_schema_version

​villagesql_vef_server_protocol

​villagesql_build_info

​vsql_allow_preview_extensions

​Next Steps

Managing Extensions

Install Extensions

Extension Architecture

Available Extensions

System Views

INFORMATION_SCHEMA.EXTENSIONS

INFORMATION_SCHEMA.COLUMNS (Custom Types)

INFORMATION_SCHEMA.EXTENSION_REGISTRATION

Common Queries

Find Extension Dependencies

List All Extensions and Their Custom Type Columns

Find Tables Using Extension Types

System Variables

veb_dir

villagesql_server_version

villagesql_schema_version

villagesql_vef_server_protocol

villagesql_build_info

vsql_allow_preview_extensions

Next Steps