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

# Quickstart

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

```bash theme={null}
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](/mysql-8.4/0.0.5/source) 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.

```bash theme={null}
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:

```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](/mysql-8.4/0.0.5/install).

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

```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
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:

```sql theme={null}
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:

<CardGroup cols={2}>
  <Card title="Managing Extensions" icon="puzzle-piece" href="/mysql-8.4/0.0.5/managing">
    Learn how to install and manage other extensions.
  </Card>

  <Card title="Create an Extension" icon="code" href="/mysql-8.4/0.0.5/create">
    Learn how to build your own extensions for VillageSQL.
  </Card>

  <Card title="Upgrade Guide" icon="arrow-up" href="/guides/upgrade">
    Upgrading from a prior version or migrating from MySQL.
  </Card>
</CardGroup>

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