Managing Extensions

Viewing Installed Extensions

Query installed extensions using the INFORMATION_SCHEMA view:

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

Output:

+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
| vsql_uuid        | 0.2.1             |
+------------------+-------------------+

Usage:

Use in both interactive sessions and scripts
Standard SQL interface compatible with MySQL tools

Checking Extension Functions

Verify extension functions work after installation:

-- Test a function directly
SELECT complex_abs('(1.0,2.0)');

Extension Directory

Check where VillageSQL looks for .veb files:

SHOW VARIABLES LIKE 'veb_dir';

List available extensions:

ls -la /path/to/veb_dir/*.veb

Configuring veb_dir

To change the extension directory location, set veb_dir in your MySQL configuration file: my.cnf / my.ini:

[mysqld]
veb_dir=/custom/path/to/extensions/

Requirements:

Path must be absolute (not relative)
Directory must exist before server start
MySQL user must have read permissions on the directory
Only one veb_dir is supported (cannot have multiple paths)
Changes require server restart to take effect

Verify after restart:

SHOW VARIABLES LIKE 'veb_dir';

Troubleshooting

Quick Reference

Issue	Quick Fix
Extension not found	Verify `.veb` file exists in veb_dir with correct name
Permission denied	Check permissions: `chmod 644 extension.veb`
Cannot uninstall: types in use	Attempt `UNINSTALL EXTENSION`; the error identifies blocking columns by name
Version mismatch	Restart server to clear cache

Extension Not Found

Error: Extension 'my_extension' not found Debug steps:

# 1. Check veb_dir location
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"

# 2. List .veb files
ls -la /path/to/veb_dir/

# 3. Verify filename matches extension name
# File: my_extension.veb
# Install: INSTALL EXTENSION my_extension;

# 4. Check permissions
ls -l /path/to/veb_dir/my_extension.veb
sudo chmod 644 /path/to/veb_dir/my_extension.veb

Function Not Available After Install

Error: FUNCTION my_func does not exist Debug steps:

-- 1. Verify extension installed
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

Cannot Uninstall Extension

Error: Cannot uninstall extension: types in use Solution:

-- Attempt uninstall; the error identifies blocking columns by name
UNINSTALL EXTENSION my_extension;
-- If blocked: ERROR HY000: Cannot drop extension `my_extension` as 1 column(s) depend on it,
--             e.g. mydb.mytable.my_column has type MYTYPE

-- Drop or alter the identified column(s), then retry
DROP TABLE mydb.mytable;
-- OR
ALTER TABLE mydb.mytable DROP COLUMN my_column;

UNINSTALL EXTENSION my_extension;

Library Loading Errors

Error: Cannot load library: undefined symbol Causes:

Missing library dependencies
ABI compatibility mismatch
Incorrect MySQL version

Debug:

# Check library dependencies (Linux)
ldd /path/to/veb_dir/_expanded/my_extension/sha256/lib/my_extension.so

# Check library dependencies (macOS)
otool -L /path/to/veb_dir/_expanded/my_extension/sha256/lib/my_extension.so

Extension Name Validation Errors

Error: Failed to load VEF extension 'extension_name' with log message Extension name mismatch Cause: The extension name in manifest.json doesn’t match the VEB filename or the name registered in the extension code. Debug steps:

Check VEB filename matches manifest:

# VEB filename: my_extension.veb
# manifest.json should have:
{
  "name": "my_extension",  # Must match VEB filename (without .veb)
  ...
}

Verify manifest.json name field:

# Extract and check manifest from VEB
tar -xOf /path/to/veb_dir/my_extension.veb manifest.json | grep name

Check extension registration in code:

// In your extension source, these must all match:
VEF_GENERATE_ENTRY_POINTS(
  make_extension("my_extension", "1.0.0")  // Must match manifest name
    ...
)

Solution: All three names must be identical (using underscores, not hyphens):

VEB filename: my_extension.veb
manifest.json: "name": "my_extension"
Extension code: make_extension("my_extension", ...)

Common mistakes:

Using hyphens in manifest: "name": "my-extension" ❌
VEB filename doesn’t match: my-extension.veb vs "name": "my_extension" ❌
Code registration differs: make_extension("myextension", ...) ❌

Correct example:

// manifest.json
{
  "name": "my_extension",
  "version": "1.0.0"
}

// extension.cc
VEF_GENERATE_ENTRY_POINTS(
  make_extension("my_extension", "1.0.0")
    .func(...)
)

# VEB filename
my_extension.veb

Monitoring Extension Usage

Query Performance

Track UDF execution times using performance_schema:

-- Enable statement instrumentation
UPDATE performance_schema.setup_instruments
SET ENABLED = 'YES', TIMED = 'YES'
WHERE NAME LIKE '%statement%';

-- Query UDF execution times
SELECT
    DIGEST_TEXT,
    COUNT_STAR as executions,
    ROUND(SUM_TIMER_WAIT/1000000000, 2) as total_ms,
    ROUND(AVG_TIMER_WAIT/1000000000, 2) as avg_ms
FROM performance_schema.events_statements_summary_by_digest
WHERE DIGEST_TEXT LIKE '%complex_%'
ORDER BY total_ms DESC
LIMIT 10;

Custom Type Usage

Track which tables use custom types:

-- 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 DATA_TYPE, TABLE_SCHEMA, TABLE_NAME;

Updating Extensions

To update an extension to a newer version, use the manual update process:

ALTER EXTENSION UPDATE is not supported in v0.0.2 and is planned for a future release.

Manual Update Process

Uninstall the current version:
UNINSTALL EXTENSION extension_name;

Replace the .veb file:

# Remove old .veb file
sudo rm /path/to/veb_dir/extension_name.veb

# Copy new .veb file
sudo cp new_extension_name.veb /path/to/veb_dir/

Install the new version:
INSTALL EXTENSION extension_name;

Verify the update:

SELECT EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'extension_name';

Data Safety: If tables use custom types from the extension, you must drop or alter those tables before uninstalling. Back up your data first.

Example:

-- Find columns using vsql_complex types before updating
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';

-- If columns exist, back up data and drop/alter them first
-- Then proceed with update
UNINSTALL EXTENSION vsql_complex;
-- (replace .veb file)
INSTALL EXTENSION vsql_complex;

Cleaning Up

Remove Orphaned Expansion Directories

VillageSQL expands .veb files to _expanded/{name}/{sha256}/. Old versions accumulate over time.

# List expansion directories
ls -la /path/to/veb_dir/_expanded/

# Compare with installed extensions
mysql -u root -p -e "SELECT EXTENSION_NAME FROM INFORMATION_SCHEMA.EXTENSIONS;"

# Manually remove unused SHA256 directories
rm -rf /path/to/veb_dir/_expanded/my_extension/old_sha256_hash/

Server restart automatically cleans up orphaned expansion directories.

Getting Help

If you encounter issues not covered here:

Check Error Log: Most extension errors are logged with details
Review Extension Docs: Extension-specific troubleshooting may exist
Ask on Discord: Join the VillageSQL Discord
File an Issue: Report bugs on GitHub Issues

Next Steps

System Reference

Query system tables and views

Uninstall Extensions

Remove extensions safely

Extension Architecture

Understand the internals

Getting Started

Using Extensions

Creating Extensions

Viewing Installed Extensions

Checking Extension Functions

Extension Directory

Configuring veb_dir

Troubleshooting

Quick Reference

Extension Not Found

Function Not Available After Install

Cannot Uninstall Extension

Library Loading Errors

Extension Name Validation Errors

Monitoring Extension Usage

Query Performance

Custom Type Usage

Updating Extensions

Manual Update Process

Cleaning Up

Remove Orphaned Expansion Directories

Getting Help

Next Steps

System Reference

Uninstall Extensions

Extension Architecture

​Viewing Installed Extensions

​Checking Extension Functions

​Extension Directory

​Configuring veb_dir

​Troubleshooting

​Quick Reference

​Extension Not Found

​Function Not Available After Install

​Cannot Uninstall Extension

​Library Loading Errors

​Extension Name Validation Errors

​Monitoring Extension Usage

​Query Performance

​Custom Type Usage

​Updating Extensions

​Manual Update Process

​Cleaning Up

​Remove Orphaned Expansion Directories

​Getting Help

​Next Steps

System Reference

Uninstall Extensions

Extension Architecture

Viewing Installed Extensions

Checking Extension Functions

Extension Directory

Configuring veb_dir

Troubleshooting

Quick Reference

Extension Not Found

Function Not Available After Install

Cannot Uninstall Extension

Library Loading Errors

Extension Name Validation Errors

Monitoring Extension Usage

Query Performance

Custom Type Usage

Updating Extensions

Manual Update Process

Cleaning Up

Remove Orphaned Expansion Directories

Getting Help

Next Steps