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 8.4 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`	text	Version the extension will change to at the next restart, or `NULL`
`PENDING_REQUESTED_AT`	text	When a pending version change was requested, or `NULL`
`PENDING_LAST_ERROR`	text	Message from a failed version change, or `NULL`
`PENDING_LAST_ERROR_AT`	text	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`	`longtext`	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-8.4). 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-8.4_0.0.5

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

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. Extension authors can compare this value against the protocol constants in types.h to determine which ABI features are available during registration.

SELECT @@villagesql_vef_server_protocol;

Property	Value
Scope	Global
Access	Read-only
Type	Unsigned integer (`0`–`255`)
Current value	`4` (`VEF_PROTOCOL_4`)

What Protocol V4 adds Extensions negotiating VEF_PROTOCOL_4 or higher gain access to the variable_length field on vef_type_desc_t. When set to true, the type’s persisted size is determined per value rather than being a single fixed footprint. Variable-length types must also declare max_persisted_length as an upper bound. Use the variable_length_type() builder method on TypeBuilder to set this flag — do not write variable_length directly. The field is read by the server only when the negotiated protocol is VEF_PROTOCOL_4 or higher. VEF_PROTOCOL_4 also adds the max_result_length field on vef_func_desc_t. A function may declare the maximum length (in characters) of its STRING result so a materialized result — GROUP BY/DISTINCT temp tables, CREATE TABLE ... SELECT, UNION — holds the full value instead of truncating at the argument width. 0 falls back to the argument width; it is STRING-only and capped at VEF_MAX_RESULT_LENGTH (16 MiB / 16777216 bytes). A larger declared value is capped to it. Set it with the max_result_length() builder method on FuncBuilder. Protocol V4 is under active development. Extensions that opt in must be built with -DVSQL_USE_DEV_ABI=ON and should expect ABI changes before it stabilises. See abi/types.h for the full vef_type_desc_t and vef_func_desc_t definitions, type_builder.h for variable_length_type(), and func_builder.h for max_result_length(). 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"`
`build_host`	string	Hostname of the build machine
`build_os`	string	Host operating system: `"linux"` or `"macos"`
`build_arch`	string	Host CPU architecture: `"x86_64"`, `"aarch64"`, or `"arm64"`

Scope: Global, read-only. Cannot be set at runtime. A clean release build has is_dirty: false and all three file-count fields at zero. A build from a modified work tree will show non-zero counts in files_added, files_deleted, or files_modified.

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_vef_server_protocol

villagesql_build_info

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_vef_server_protocol

​villagesql_build_info

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

villagesql_build_info

Next Steps