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

VillageSQL ships with example extensions you can install immediately. INSTALL EXTENSION <name> looks for <name>.veb in the server’s VEB directory — run SHOW VARIABLES LIKE 'veb_dir'; to see where that is. The example extensions ship pre-placed there, so no copying is needed on your part. 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 every standard version — UUID_V1() through UUID_V7() — plus functions to introspect stored values. The example below uses v7, whose time-ordered values sort by creation time and carry an embedded timestamp: 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