Installing Extensions

Install VillageSQL extensions to add custom types, functions, and capabilities to your database.

Command Syntax

INSTALL EXTENSION extension_name [VERSION 'version'];

When VERSION is supplied, the server opens {name}-{version}.veb, compares the version against the manifest, and aborts if they differ. Omit the clause to install {name}.veb, or — if only versioned VEBs are present — the unique {name}-{version}.veb. See Selecting a Version.

Extensions are distributed as .veb (VillageSQL Extension Bundle) files containing compiled libraries and metadata.

Selecting a Version

VEB files in veb_dir may be named either {name}.veb (unversioned) or {name}-{version}.veb (versioned). To install a specific versioned VEB, add a VERSION clause:

INSTALL EXTENSION vsql_uuid VERSION '0.2.0';

With VERSION, the server opens vsql_uuid-0.2.0.veb and verifies that the version in its manifest.json matches 0.2.0. Without VERSION, the server resolves the file as follows:

If {name}.veb exists, install it; the version is read from its manifest.json.
Otherwise, if exactly one {name}-{version}.veb exists, install it; the version in the filename is verified against its manifest.json.
Otherwise, the install fails and you must specify a version.

If multiple versioned VEBs are present and no unversioned VEB exists, INSTALL EXTENSION fails with

Multiple versions of extension '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> VERSION 'x.y.z'

. Re-run with an explicit VERSION clause.

Extension Naming Conventions

VillageSQL uses different naming conventions in different contexts:

SQL commands: Use underscores: INSTALL EXTENSION vsql_uuid
Repository names: Use hyphens: github.com/villagesql/vsql-uuid
File names: Use underscores: vsql_uuid.veb
manifest.json: Use underscores to match SQL: "name": "vsql_uuid"

Example:

# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# But .veb file uses underscores
ls vsql_uuid.veb

# Install with underscores (no quotes)
INSTALL EXTENSION vsql_uuid;

Prerequisites

Running VillageSQL Server instance
Administrative access (root or equivalent)

Installing Built-in Extensions

Built-in extensions included with VillageSQL are already in the veb_dir. Simply enable them:

-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;

Verify Installation

-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

Output:

+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
+------------------+-------------------+

Test Functionality

-- Create a database first
CREATE DATABASE test_db;
USE test_db;

-- Test extension functions
CREATE TABLE test (id INT, value COMPLEX);
INSERT INTO test VALUES (1, '(3,4)');
SELECT complex_abs(value) FROM test;  -- Returns 5.0

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;

Installing External Extensions

For extensions downloaded or built separately:

Your server must have veb_dir configured before you can install external extensions. See Configuring veb_dir.

1. Copy the .veb File

Find your server’s extension directory, then copy the .veb file into it:

-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';

cp /path/to/my_extension.veb /path/to/veb_dir/

2. Install Extension

INSTALL EXTENSION my_extension;

To pin the expected version — useful in CI or scripted rollouts — include the VERSION clause:

INSTALL EXTENSION my_extension VERSION '1.2.0';

If the manifest reports a different version, the install fails and nothing is registered:

ERROR 3219 (HY000): Version mismatch in 'my_extension-1.2.0.veb':
filename says '1.2.0' but manifest says '0.0.1'

3. Verify Installation

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

Troubleshooting

Issue	Solution
`Extension not found`	Verify the `.veb` file is in `veb_dir`: `SHOW VARIABLES LIKE 'veb_dir'`
`Permission denied`	Check file permissions: `chmod 644 extension.veb`
`extension name mismatch`	Extension’s internal name doesn’t match the `.veb` filename. Rebuild the extension.
`vef_register not found`	The `.veb` file doesn’t export a valid VEF entry point. Rebuild against the correct SDK.
`vef_register returned an error: ...`	Extension registration failed. Read the appended message for details.
`Version mismatch in 'name-Y.veb': filename says 'Y' but manifest says 'X'`	The `VERSION` clause selects `{name}-{version}.veb` but the manifest inside reports a different version. Re-run with the manifest version, or fix the filename.
`Multiple versions of extension 'name' found in '<dir>'; specify a version with INSTALL EXTENSION name VERSION 'x.y.z'`	Multiple `{name}-{version}.veb` files exist with no unversioned `{name}.veb`. Re-run with an explicit `VERSION` clause.

For more troubleshooting, see Managing Extensions.

Next Steps

Managing Extensions

Monitor and troubleshoot installed extensions

Available Extensions

Browse extensions you can install

Create Extensions

Build your own extensions

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

Command Syntax

Selecting a Version

Extension Naming Conventions

Prerequisites

Installing Built-in Extensions

Verify Installation

Test Functionality

Installing External Extensions

1. Copy the .veb File

2. Install Extension

3. Verify Installation

Troubleshooting

Next Steps

Managing Extensions

Available Extensions

Create Extensions

​Command Syntax

​Selecting a Version

​Extension Naming Conventions

​Prerequisites

​Installing Built-in Extensions

​Verify Installation

​Test Functionality

​Installing External Extensions

​1. Copy the .veb File

​2. Install Extension

​3. Verify Installation

​Troubleshooting

​Next Steps

Managing Extensions

Available Extensions

Create Extensions

Command Syntax

Selecting a Version

Extension Naming Conventions

Prerequisites

Installing Built-in Extensions

Verify Installation

Test Functionality

Installing External Extensions

1. Copy the .veb File

2. Install Extension

3. Verify Installation

Troubleshooting

Next Steps