> ## 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.
# Installing Extensions
> How to add new capabilities to VillageSQL using extensions.
Install VillageSQL extensions to add custom types, functions, and capabilities to your database.
## Command Syntax
```sql theme={null}
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](#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:
```sql theme={null}
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 '' found in ''; specify a version with INSTALL EXTENSION 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:**
```bash theme={null}
# 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:
```sql theme={null}
-- Connect to VillageSQL
mysql -u root -p
-- Install the extension
INSTALL EXTENSION vsql_complex;
```
### Verify Installation
```sql theme={null}
-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
**Output:**
```
+------------------+-------------------+
| EXTENSION_NAME | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex | 0.0.1 |
+------------------+-------------------+
```
### Test Functionality
```sql theme={null}
-- 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](/mysql-8.4/0.0.5/managing#configuring-veb_dir).
### 1. Copy the .veb File
Find your server's extension directory, then copy the `.veb` file into it:
```sql theme={null}
-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';
```
```bash theme={null}
cp /path/to/my_extension.veb /path/to/veb_dir/
```
### 2. Install Extension
```sql theme={null}
INSTALL EXTENSION my_extension;
```
To pin the expected version — useful in CI or scripted rollouts — include
the `VERSION` clause:
```sql theme={null}
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
```sql theme={null}
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 ''; 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](/mysql-8.4/0.0.5/managing).
## Next Steps
Monitor and troubleshoot installed extensions
Browse extensions you can install
Build your own extensions