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

# 快速入门

> 开始使用 VillageSQL Server。

运行一个 VillageSQL Server 实例，连接到它，并试用扩展系统。

## 步骤 1：安装 VillageSQL

### 选项 A：Docker（推荐）

在容器中运行 VillageSQL，无需进行主机端安装：

```bash theme={null}
docker run -d --name vsql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -p 3306:3306 villagesql/server:mysql-9.7_0.0.6-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
```

镜像标签由代码库、VillageSQL 版本和架构组成，上面的命令会通过 `uname` 读取架构。在 PowerShell 中请自行填写后缀：Intel 和 AMD 使用 `-amd64`，ARM 使用 `-arm64`。

### 选项 B：Shell 脚本

使用官方安装脚本直接在您的机器上安装 VillageSQL。它会下载并配置适用于您平台的服务器二进制文件。

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

脚本会询问三个问题：安装哪个代码库、用哪种方式安装、安装哪个版本。在第一个问题中选择 **MySQL 9.7**，即可获得本文档描述的服务器。

如果没有终端来回答这些问题（CI 任务、Dockerfile、AI 智能体），请用环境变量传入答案，并设置在管道的 `bash` 一侧：

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

`VSQL_CODEBASE` 接受 `mysql-8.4`、`percona-8.4` 或 `mysql-9.7`。`INSTALL_METHOD` 接受 `docker`、`prebuilt` 或 `source`。源码构建还接受 `VSQL_VERSION=stable|nightly|latest`；Docker 和预编译安装始终使用稳定版本。

在运行脚本之前检查脚本：`curl -fsSL https://install.villagesql.com | less`

### 选项 C：从源代码构建

对于开发或自定义构建，请按照[从源代码克隆和构建指南](/docs/zh/mysql-9.7/stable/source)进行操作，以从最新代码进行编译。

### Shell 脚本设置了哪些内容

Shell 脚本（选项 B）会将所有内容安装到 `~/.villagesql/` 下，并在端口 3306 上启动服务器。重要的位置如下：

| 路径                              | 内容说明                                   |
| ------------------------------- | -------------------------------------- |
| `~/.villagesql/credentials.txt` | 生成的 root 密码，以及可直接运行的启动、停止和连接命令（仅您本人可读） |
| `~/.villagesql/data/`           | 数据库数据目录                                |
| `~/.villagesql/mysql.sock`      | 服务器套接字                                 |
| `~/.villagesql/mysql.log`       | 服务器错误日志                                |

如果 `~/.local/bin` 位于您的 `PATH` 中，该脚本还会添加快捷命令：`villagesql`（客户端）、`villagesql-server`（服务器）和 `villagesql-admin`（管理工具）。

Docker（选项 A）和手动源代码构建不会创建 `~/.villagesql/` — Docker 将其数据保存在容器内部。

## 步骤 2：连接到服务器

使用任何标准的 MySQL 客户端进行连接。请使用 `-h 127.0.0.1`，而不是默认的 `localhost`：`localhost` 会让客户端去查找 Unix 套接字，而当服务器在 Docker 中运行时该套接字不可访问，因此请改用 TCP 连接。

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

* **Docker（选项 A）：** 容器启动时 root 密码为空 — 在密码提示处按 Enter 键即可。
* **Shell 脚本（选项 B）：** 生成的 root 密码保存在 `~/.villagesql/credentials.txt` 中。

## 步骤 3：安装您的第一个扩展

`INSTALL EXTENSION <name>` 会在服务器的 VEB 目录中查找 `<name>.veb` — 运行 `SHOW VARIABLES LIKE 'veb_dir';` 可以查看该目录的位置。

如果您使用 Docker（选项 A）或 shell 脚本（选项 B）安装，`veb_dir` 中已经有一批 `.veb` 文件——无需下载或复制。那里预置了两类扩展：

* 扩展，例如 `vsql_uuid`（UUID 类型和生成器），以及[捆绑扩展列表](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt)中的其他扩展。
* `vsql_complex` 和 `vsql_simple`，是本文档其他章节中使用的参考扩展（参见 [C++ 扩展示例](/docs/zh/mysql-9.7/stable/examples)），用于演示扩展框架的工作原理。

如果您从源代码构建了 VillageSQL（选项 C），`vsql_complex` 和 `vsql_simple` 也已经在 `veb_dir` 中——`make install` 会无条件构建它们。但 `vsql_uuid` 及其他扩展不会：它们位于各自独立的代码仓库中，需要单独构建和安装。如果您使用的是选项 C，请先克隆并构建 [vsql-uuid](https://github.com/villagesql/vsql-uuid) 再继续，或者跳到后面改用 `vsql_complex`——参见[安装扩展](/docs/zh/mysql-9.7/stable/install)。

安装 `vsql_uuid` 扩展，以添加原生 UUID 生成功能和 `UUID` 列类型：

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

验证安装：

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

您应该能看到 `vsql_uuid` 出现在列表中。

有关更多详细信息，请参阅[安装扩展](/docs/zh/mysql-9.7/stable/install)。

## 步骤 4：使用扩展数据类型

现在扩展已激活，您可以在表中像使用原生类型一样使用 `UUID` 类型，它配有针对每个标准版本的生成器 — `UUID_V1()`、`UUID_V1MC()`、`UUID_V3()`、`UUID_V4()`、`UUID_V5()`、`UUID_V6()` 和 `UUID_V7()`（没有 `UUID_V2()`）— 以及用于检查已存储值的函数。下面的示例使用 v7，其值携带内嵌的时间戳，当生成时间相隔超过一毫秒时会按创建时间排序；在同一毫秒内生成的值按随机位排序，而不是按调用顺序排序：这提供了一个适合顺序排列的键，无需手工编写 `BINARY(16)` 生成逻辑。

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

要卸载扩展：

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

## 停止和重启服务器

您可以通过控制服务器的容器（Docker）或其后台进程（Shell 安装）来停止和启动服务器 — 数据库会随之启动和关闭。

* **Docker（选项 A）：** `docker stop vsql` 停止服务器；`docker start vsql` 将其重新启动。
* **Shell 脚本（选项 B）：** 适用于您的安装的启动、停止和连接命令（已经填好数据目录、套接字和端口）位于 `~/.villagesql/credentials.txt` 中。

## 后续步骤

现在您已经运行了 VillageSQL 并验证了扩展系统，可以进一步探索：

<CardGroup cols={2}>
  <Card title="管理扩展" icon="puzzle-piece" href="/docs/zh/mysql-9.7/stable/managing">
    了解如何安装和管理其他扩展。
  </Card>

  <Card title="创建扩展" icon="code" href="/docs/zh/mysql-9.7/stable/create">
    了解如何为 VillageSQL 构建您自己的扩展。
  </Card>

  <Card title="升级指南" icon="arrow-up" href="/docs/guides/upgrade">
    从先前版本升级或从 MySQL 迁移。
  </Card>
</CardGroup>

## 故障排除

### 服务器无法启动

常见问题：

* 端口 3306 已经被占用：配置您的服务器以使用不同的端口
* 权限：确保文件可读/可执行