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

<Note>
  `INSTALL EXTENSION` and `UNINSTALL EXTENSION` are VillageSQL SQL extensions.
  They are not part of standard MySQL 8.4 syntax.
</Note>

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

```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](/mysql-8.4/0.0.5/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`   | `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:

```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](/mysql-8.4/0.0.5/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-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.

```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_%';
```

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

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

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

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

<CardGroup cols={2}>
  <Card title="Managing Extensions" icon="sliders" href="/mysql-8.4/0.0.5/managing">
    Monitor and troubleshoot extensions
  </Card>

  <Card title="Install Extensions" icon="download" href="/mysql-8.4/0.0.5/install">
    Add new extensions
  </Card>

  <Card title="Extension Architecture" icon="sitemap" href="/mysql-8.4/0.0.5/architecture">
    Understand the internals
  </Card>

  <Card title="Available Extensions" icon="list" href="/extensions">
    Browse extension catalog
  </Card>
</CardGroup>