> ## 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

> Get up and running with VillageSQL Server.

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:

```bash theme={null}
docker run -d --name vsql -e MYSQL_ROOT_PASSWORD=<your-password> -p 3306:3306 villagesql/server:mysql-9.7_latest
```

### 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.

```bash theme={null}
curl -fsSL https://install.villagesql.com | bash
```

The script asks which codebase to install and how to install it. A source build also asks which version. Choose **MySQL 9.7** at the first question to get the server
these pages describe.

Where there is no terminal to answer the questions — a CI job, a Dockerfile, an
AI agent — pass the answers instead. Set them on the `bash` side of the pipe:

```bash theme={null}
curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-9.7 INSTALL_METHOD=prebuilt bash
```

`VSQL_CODEBASE` takes `mysql-8.4`, `percona-8.4`, or `mysql-9.7`. The Percona
build tracks MySQL 8.4 only.
`INSTALL_METHOD` takes `docker`, `prebuilt`, or `source`. A source build also
needs `VSQL_VERSION=stable|nightly|latest`; Docker and prebuilt installs are
always the stable release.

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](https://villagesql.com/docs/en/9.7/dev/source.md) to compile from the latest code.

### What the shell script sets up

The shell script (Option B) installs the server under `~/.villagesql/` and starts it on port 3306; if you choose Docker at the script's install-method question, it starts a container named `vsql` instead. 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` exists and is writable, 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 in a Docker volume mounted at `/var/lib/mysql` in the container.

## Step 2: Connect to the Server

**Docker (Option A).** Connect with any MySQL client, and enter the root password you set with `MYSQL_ROOT_PASSWORD`. 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.

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u root -p
```

If you have no MySQL client on your machine, use the one inside the container:

```bash theme={null}
docker exec -it vsql mysql -u root -p
```

**Shell script (Option B).** The script installs its own MySQL client, but it does not put it on your `PATH`. Run the `Connect` command that the script saved in `~/.villagesql/credentials.txt`. The root password is in the same file. For a prebuilt install, the command looks like this:

```bash theme={null}
~/.villagesql/prebuilt/bin/mysql -u root -p --socket="$HOME/.villagesql/mysql.sock"
```

For a source build, the client is in `~/.villagesql/build/bin/` instead. If you chose Docker at the script's install-method question, the script printed the password on screen and saved no `credentials.txt`; connect as in Option A.

## 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](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt).
* `vsql_complex` and `vsql_simple`, reference extensions used elsewhere in these docs (see [C++ Extension Examples](https://villagesql.com/docs/en/sdk/cpp/examples.md)) 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](https://github.com/villagesql/vsql-uuid) before continuing, or skip ahead using `vsql_complex` in its place — see [Installing Extensions](https://villagesql.com/docs/en/extensions/install.md).

Install the `vsql_uuid` extension to add native UUID generation and a `UUID` column type:

```sql theme={null}
INSTALL EXTENSION vsql_uuid;
```

Verify installation:

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

You should see `vsql_uuid` listed.

For more details, see [Installing Extensions](https://villagesql.com/docs/en/extensions/install.md).

## 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.

```sql theme={null}
-- 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. Each UUID_V7() embeds a millisecond
-- timestamp, so rows inserted in the same statement can land in the same
-- millisecond and tie-break on their random bits instead of insertion
-- order — insert separately, with a gap, to see the ordering clearly.
INSERT INTO events VALUES (UUID_V7(), 'signup');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'login');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (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, first drop everything that uses its types:

```sql theme={null}
DROP DATABASE demo;
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`. If you chose Docker at the script's install-method question, use the Docker commands above.

## Next Steps

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

> [card] [Managing Extensions](https://villagesql.com/docs/en/extensions/managing.md)
>
> Learn how to install and manage other extensions.

> [card] [Create an Extension](https://villagesql.com/docs/en/extensions/build/create.md)
>
> Learn how to build your own extensions for VillageSQL.

> [card] [Upgrade Guide](https://villagesql.com/docs/en/guides/upgrade.md)
>
> Upgrading from a prior version or migrating from MySQL.

## Troubleshooting

### Server Won't Start

Common issues:

* Port 3306 already in use: stop the other server, or run the installer with `PORT=<port>` set. With Docker, change the host side of `-p`.
* Permissions: Ensure files are readable/executable


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.