快速入门

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

步骤 1：安装 VillageSQL

选项 A：Docker（推荐）

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

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。它会下载并配置适用于您平台的服务器二进制文件。

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

脚本会询问三个问题：安装哪个代码库、用哪种方式安装、安装哪个版本。在第一个问题中选择 MySQL 9.7，即可获得本文档描述的服务器。如果没有终端来回答这些问题（CI 任务、Dockerfile、AI 智能体），请用环境变量传入答案，并设置在管道的 bash 一侧：

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：从源代码构建

对于开发或自定义构建，请按照从源代码克隆和构建指南进行操作，以从最新代码进行编译。

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 连接。

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 类型和生成器），以及捆绑扩展列表中的其他扩展。
vsql_complex 和 vsql_simple，是本文档其他章节中使用的参考扩展（参见 C++ 扩展示例），用于演示扩展框架的工作原理。

如果您从源代码构建了 VillageSQL（选项 C），vsql_complex 和 vsql_simple 也已经在 veb_dir 中——make install 会无条件构建它们。但 vsql_uuid 及其他扩展不会：它们位于各自独立的代码仓库中，需要单独构建和安装。如果您使用的是选项 C，请先克隆并构建 vsql-uuid 再继续，或者跳到后面改用 vsql_complex——参见安装扩展。安装 vsql_uuid 扩展，以添加原生 UUID 生成功能和 UUID 列类型：

INSTALL EXTENSION vsql_uuid;

验证安装：

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

您应该能看到 vsql_uuid 出现在列表中。有关更多详细信息，请参阅安装扩展。

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

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

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

要卸载扩展：

UNINSTALL EXTENSION vsql_uuid;

停止和重启服务器

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

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

后续步骤

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

管理扩展

了解如何安装和管理其他扩展。

创建扩展

了解如何为 VillageSQL 构建您自己的扩展。

升级指南

从先前版本升级或从 MySQL 迁移。

故障排除

服务器无法启动

常见问题：

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

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

步骤 1：安装 VillageSQL

选项 A：Docker（推荐）

选项 B：Shell 脚本

选项 C：从源代码构建

Shell 脚本设置了哪些内容

步骤 2：连接到服务器

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

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

停止和重启服务器

后续步骤

管理扩展

创建扩展

升级指南

故障排除

服务器无法启动

​步骤 1：安装 VillageSQL

​选项 A：Docker（推荐）

​选项 B：Shell 脚本

​选项 C：从源代码构建

​Shell 脚本设置了哪些内容

​步骤 2：连接到服务器

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

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

​停止和重启服务器

​后续步骤

管理扩展

创建扩展

升级指南

​故障排除

​服务器无法启动

步骤 1：安装 VillageSQL

选项 A：Docker（推荐）

选项 B：Shell 脚本

选项 C：从源代码构建

Shell 脚本设置了哪些内容

步骤 2：连接到服务器

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

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

停止和重启服务器

后续步骤

故障排除

服务器无法启动