A comprehensive UUID extension for VillageSQL Server that adds UUID generation, introspection, and comparison capabilities with support for UUID versions 1, 3, 4, 5, 6, and 7.
- Full UUID Support: Generate UUIDs v1 (time-based), v3 (MD5-based), v4 (random), v5 (SHA1-based), v6 (reordered time), and v7 (Unix epoch time)
- Custom UUID Type: Native 16-byte binary UUID storage with automatic string conversion
- UUID Introspection: Extract version and timestamp from existing UUIDs
- High Performance: Optimized C++ implementation with minimal overhead
- VillageSQL build tree (specified via
VillageSQL_BUILD_DIR) - CMake 3.16 or higher
- C++17 compatible compiler
- OpenSSL development libraries (for cryptographic hash functions in v3/v5 UUID generation)
📚 Full Documentation: Visit villagesql.com/docs for comprehensive guides on building extensions, architecture details, and more.
-
Clone the repository:
git clone https://github.com/villagesql/vsql-uuid.git cd vsql-uuid -
Configure CMake with required paths:
Linux:
mkdir -p build cd build cmake .. -DVillageSQL_BUILD_DIR=$HOME/build/villagesql
macOS:
mkdir -p build cd build cmake .. -DVillageSQL_BUILD_DIR=~/build/villagesql
Note:
VillageSQL_BUILD_DIRshould point to your VillageSQL build directory. -
Build the extension:
make -j $(($(getconf _NPROCESSORS_ONLN) - 2))This creates the
vsql_uuid.vebpackage in the build directory. -
Install the VEB (optional):
make install
This copies the VEB to the directory specified by
VEB_INSTALL_DIR. If not usingmake install, you can manually copy the VEB file to your desired location.
After installation, the extension provides the following functions. Functions can be called with or without the extension prefix:
The extension provides a custom UUID type for efficient binary storage:
-- Create table with UUID column
CREATE TABLE users (
id UUID PRIMARY KEY,
name VARCHAR(100)
);
-- Insert with generated UUID
INSERT INTO users VALUES (UUID_V4(), 'John Doe');-- Generate UUID v4 (random)
SELECT UUID_V4();
-- Result: 550e8400-e29b-41d4-a716-446655440000
-- Generate UUID v1 (time-based)
SELECT UUID_V1();
-- Generate UUID v1 with random MAC (multicast)
SELECT UUID_V1MC();
-- Generate UUID v3 (name-based, MD5)
SELECT UUID_V3('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'example.com');
-- Generate UUID v5 (name-based, SHA1)
SELECT UUID_V5('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'example.com');
-- Generate UUID v6 (reordered time-based, sortable)
SELECT UUID_V6();
-- Generate UUID v7 (Unix epoch time-based, sortable)
SELECT UUID_V7();These functions take a uuid column value, not a string. Use them against
a table column or a UUID generation function:
-- Get UUID version from a column
SELECT UUID_VERSION(id) FROM users WHERE name = 'John Doe'; -- Returns 4
-- Get UUID version from a generated value
SELECT UUID_VERSION(UUID_V7()); -- Returns 7
-- Get timestamp from v1, v6, or v7 UUID column
SELECT UUID_TIMESTAMP(id) FROM events;
-- Returns: 1998-02-04 22:13:53 (NULL for v3/v4/v5)
-- Get Unix epoch timestamp from a v1, v6, or v7 UUID column
SELECT UUID_EPOCH(id) FROM events;
-- Returns: 886630433 (NULL for v3/v4/v5)
-- Compare two UUID columns (-1, 0, or 1)
SELECT UUID_COMPARE(a.id, b.id) FROM users a, users b
WHERE a.name = 'Alice' AND b.name = 'Bob';
-- Introspection functions are deterministic — usable in generated columns
-- and CHECK constraints:
CREATE TABLE audit_log (
id uuid NOT NULL,
ver INT AS (UUID_VERSION(id)) STORED,
CHECK (UUID_VERSION(id) IN (4, 7)) -- only v4 or v7 UUIDs allowed
);The extension includes comprehensive tests using the MySQL Test Runner (MTR) framework.
Option 1 (Default): Using installed VEB
This method assumes you have successfully run make install to install the VEB to your veb_dir.
Linux:
cd $HOME/build/villagesql/mysql-test
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-test
# Run individual test
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-test uuid_basicmacOS:
cd ~/build/villagesql/mysql-test
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-test
# Run individual test
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-test uuid_basicOption 2: Using a specific VEB file
Use this to test a specific VEB build without installing it first:
Linux:
cd $HOME/build/villagesql/mysql-test
VSQL_UUID_VEB=/path/to/vsql-uuid/build/vsql_uuid.veb \
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-testmacOS:
cd ~/build/villagesql/mysql-test
VSQL_UUID_VEB=/path/to/vsql-uuid/build/vsql_uuid.veb \
perl mysql-test-run.pl --suite=/path/to/vsql-uuid/mysql-testvsql-uuid/
├── src/
│ └── uuid.cc # VDF implementations, core UUID logic, and extension registration
├── cmake/
│ └── FindVillageSQL.cmake # CMake module to locate VillageSQL SDK
├── mysql-test/
│ ├── t/ # MTR test files
│ └── r/ # MTR expected results
├── manifest.json # VEB package manifest
├── CMakeLists.txt # Build configuration
└── AGENTS.md # AI coding assistant instructions
make- Build the extension and create thevsql_uuid.vebpackage
If you encounter a bug or have a feature request, please open an issue using GitHub Issues. Please provide as much detail as possible, including:
- A clear and descriptive title.
- A detailed description of the issue or feature request.
- Steps to reproduce the bug (if applicable).
- Your environment details (OS, VillageSQL version, etc.).
License information can be found in the LICENSE file.
VillageSQL welcomes contributions from the community. For more information, please see the VillageSQL Contributing Guide.
We are excited you want to be part of the Village that makes VillageSQL happen. You can interact with us and the community in several ways:
- File a bug or issue and we will review
- Start a discussion in the project discussions
- Join the Discord channel