Skip to main content

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.

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

​
Command Syntax

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

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

​
3. Verify Installation

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

​
Troubleshooting

IssueSolution
Extension not foundVerify the .veb file is in veb_dir: SHOW VARIABLES LIKE 'veb_dir'
Permission deniedCheck file permissions: chmod 644 extension.veb
extension name mismatchExtension’s internal name doesn’t match the .veb filename. Rebuild the extension.
vef_register not foundThe .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.
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