Quickstart

Get a VillageSQL Server instance running, connect to it, and try out the extension system.

Step 1: Install VillageSQL

Option A: Docker (Recommended)

Run VillageSQL in a container with no host-side installation:

docker run -d --name vsql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -p 3306:3306 villagesql/server:stable

Option B: Shell Script

Install VillageSQL directly on your machine using the official installation script. It downloads and configures the server binary for your platform.

curl -fsSL https://install.villagesql.com | bash

To inspect the script before running it: curl -fsSL https://install.villagesql.com | less

Option C: Build from Source

For development or custom builds, follow the Clone and Build from Source Guide to compile from the latest code.

What the shell script sets up

The shell script (Option B) installs everything under ~/.villagesql/ and starts the server on port 3306. The locations that matter:

Path	What it is
`~/.villagesql/credentials.txt`	Your generated root password, plus ready-to-run start, stop, and connect commands (readable only by you)
`~/.villagesql/data/`	Database data directory
`~/.villagesql/mysql.sock`	Server socket
`~/.villagesql/mysql.log`	Server error log

If ~/.local/bin is on your PATH, the script also adds shortcuts: villagesql (client), villagesql-server (server), and villagesql-admin (admin tool). Docker (Option A) and manual source builds don’t create ~/.villagesql/ — Docker keeps its data inside the container.

Step 2: Connect to the Server

Connect with any standard MySQL client. Use -h 127.0.0.1 rather than the default localhost: localhost makes the client look for a Unix socket, which isn’t reachable when the server runs in Docker, so connect over TCP instead.

mysql -h 127.0.0.1 -P 3306 -u root -p

Docker (Option A): the container starts with an empty root password — press Enter at the password prompt.
Shell script (Option B): your generated root password is saved in ~/.villagesql/credentials.txt.

Step 3: Install Your First Extension

INSTALL EXTENSION <name> looks for <name>.veb in the server’s VEB directory — run SHOW VARIABLES LIKE 'veb_dir'; to see where that is. If you installed with Docker (Option A) or the shell script (Option B), a set of .veb files is already in veb_dir — no download or copying needed. Two kinds of extension ship there:

Extensions, such as vsql_uuid (UUID types and generators) and the other extensions in the bundled extensions list.
vsql_complex and vsql_simple, reference extensions used elsewhere in these docs (see C++ Extension Examples) to show how the extension framework works.

If you built VillageSQL from source (Option C), vsql_complex and vsql_simple are already in veb_dir too — make install builds them unconditionally. vsql_uuid and the other extensions are not: they live in separate repositories and need to be built and installed on their own. If you used Option C, clone and build vsql-uuid before continuing, or skip ahead using vsql_complex in its place — see Installing Extensions. Install the vsql_uuid extension to add native UUID generation and a UUID column type:

INSTALL EXTENSION vsql_uuid;

Verify installation:

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

You should see vsql_uuid listed. For more details, see Installing Extensions.

Step 4: Use Extended Data Types

Now that the extension is active, you can use the UUID type in your tables just like native types, with generators for each standard version — UUID_V1(), UUID_V1MC(), UUID_V3(), UUID_V4(), UUID_V5(), UUID_V6() and UUID_V7() (there is no UUID_V2()) — plus functions to introspect stored values. The example below uses v7, whose values carry an embedded timestamp and sort by creation time when generated more than a millisecond apart; values generated within the same millisecond are ordered by random bits, not by call order: a sequential-friendly key without hand-rolled BINARY(16) generation.

-- Create a database and use it
CREATE DATABASE demo;
USE demo;

-- Create a table with a UUID primary key
CREATE TABLE events (
    id UUID PRIMARY KEY,
    label VARCHAR(50)
);

-- Insert rows with generated v7 UUIDs
INSERT INTO events VALUES
    (UUID_V7(), 'signup'),
    (UUID_V7(), 'login'),
    (UUID_V7(), 'purchase');

-- v7 keys sort in creation order
SELECT id, label FROM events ORDER BY id;

-- Introspect the stored UUIDs
SELECT
    label,
    UUID_VERSION(id) AS version,
    UUID_TIMESTAMP(id) AS created_at
FROM events
ORDER BY id;

To uninstall an extension:

UNINSTALL EXTENSION vsql_uuid;

Stopping and Restarting the Server

You stop and start the server by controlling its container (Docker) or its background process (shell install) — the database comes up and down with it.

Docker (Option A): docker stop vsql stops the server; docker start vsql brings it back.
Shell script (Option B): the start, stop, and connect commands for your install — with the data directory, socket, and port already filled in — are in ~/.villagesql/credentials.txt.

Next Steps

Now that you have VillageSQL running and have verified the extension system, explore more:

Managing Extensions

Learn how to install and manage other extensions.

Create an Extension

Learn how to build your own extensions for VillageSQL.

Upgrade Guide

Upgrading from a prior version or migrating from MySQL.

Troubleshooting

Server Won’t Start

Common issues:

Port 3306 already in use: configure your server to use a different port
Permissions: Ensure files are readable/executable

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

Step 1: Install VillageSQL

Option A: Docker (Recommended)

Option B: Shell Script

Option C: Build from Source

What the shell script sets up

Step 2: Connect to the Server

Step 3: Install Your First Extension

Step 4: Use Extended Data Types

Stopping and Restarting the Server

Next Steps

Managing Extensions

Create an Extension

Upgrade Guide

Troubleshooting

Server Won’t Start

​Step 1: Install VillageSQL

​Option A: Docker (Recommended)

​Option B: Shell Script

​Option C: Build from Source

​What the shell script sets up

​Step 2: Connect to the Server

​Step 3: Install Your First Extension

​Step 4: Use Extended Data Types

​Stopping and Restarting the Server

​Next Steps

Managing Extensions

Create an Extension

Upgrade Guide

​Troubleshooting

​Server Won’t Start

Step 1: Install VillageSQL

Option A: Docker (Recommended)

Option B: Shell Script

Option C: Build from Source

What the shell script sets up

Step 2: Connect to the Server

Step 3: Install Your First Extension

Step 4: Use Extended Data Types

Stopping and Restarting the Server

Next Steps

Troubleshooting

Server Won’t Start