> ## 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 的版本管理规范和 MySQL 兼容性矩阵。

## 概述

VillageSQL 遵循明确的版本控制和兼容性策略，以帮助您做出关于部署和升级的明智决策。

## VillageSQL 版本控制

VillageSQL 使用 [语义化版本](https://semver.org/) (SemVer) 来传达每个版本中更改的性质和影响。

### 版本格式

版本遵循以下格式：**MAJOR.MINOR.PATCH**

```
0.0.1
│ │ │
│ │ └─ PATCH version
│ └─── MINOR version
└───── MAJOR version
```

### 版本递增规则

* **MAJOR 版本**（例如，1.0.0 → 2.0.0）：可能需要代码修改或数据库迁移的破坏性变更
* **MINOR 版本**（例如，0.1.0 → 0.2.0）：以向后兼容的方式添加的新功能
* **PATCH 版本**（例如，0.0.1 → 0.0.2）：向后兼容的错误修复和次要改进

<Note>
  VillageSQL 目前处于 1.0 之前的开发阶段（版本 0.x.x）。在此阶段，随着平台逐步稳定，API 和扩展接口可能会更频繁地更改。
</Note>

### 开发版本

带有预发布后缀的版本（例如，`0.0.6-dev`）是开发版本。默认情况下，服务器会阻止从使用开发版本初始化的数据库进行升级。开发版本未经过升级兼容性测试，并且可能包含破坏性模式或协议更改。

要允许这样做，请使用 `--villagesql-allow-unsafe-dev-upgrade` 启动服务器：

```bash theme={null}
mysqld --villagesql-allow-unsafe-dev-upgrade --datadir=/path/to/data
```

若不指定该标志，且服务器检测到开发版本数据库，则会出错退出：

```
Upgrading from a development version (0.0.6-dev) is not allowed. Use --villagesql-allow-unsafe-dev-upgrade to permit this.
```

如果使用了该标志，服务器会记录警告并继续：

```
Upgrading from a development version (0.0.6-dev); --villagesql-allow-unsafe-dev-upgrade was specified.
```

如果指定了该标志但当前版本不是开发版本，服务器将出错退出：

```
--villagesql-allow-unsafe-dev-upgrade specified, but current version (0.0.3) is not a development version.
```

或者如果没有执行模式升级：

```
--villagesql-allow-unsafe-dev-upgrade specified, but no upgrade is being performed.
```

<h3 id="minimal-upgrades">
  最小升级
</h3>

使用 `--upgrade=MINIMAL` 启动服务器会跳过并非绝对必要的升级步骤。VillageSQL 的模式升级不在其跳过的步骤之列。当需要执行服务器升级且以此模式启动服务器时，服务器会记录一条已跳过服务器升级的警告，然后在存储的 VillageSQL 模式版本与构建版本不匹配时运行 VillageSQL 的模式升级。

```bash theme={null}
mysqld --upgrade=MINIMAL --datadir=/path/to/data
```

如果在此模式下 VillageSQL 的模式升级失败，服务器将中止启动。由开发版本初始化的数据目录在此模式下仍会被拒绝。要允许这样做，请使用 `--villagesql-allow-unsafe-dev-upgrade` 启动。

<h3 id="code-base-changes">
  代码库变更
</h3>

每个 VillageSQL 版本都与一个代码库相关联，即服务器所基于的上游分支。例如，`mysql-9.7_0.0.6` 是 `mysql-9.7` 代码库的 0.0.6 版本。来自不同代码库的版本号无法比较，因此在代码库之间迁移不是受支持的升级：您可以从 `mysql-9.7_0.0.5` 升级到 `mysql-9.7_0.0.6`，但无法从 `mysql-9.7_0.0.6` 升级到 `mysql-8.4_0.0.6`。

数据目录会将创建它的服务器的代码库记录为 [`villagesql_schema_version`](/docs/zh/mysql-9.7/stable/reference#villagesql_schema_version)。如果您在该数据目录上启动一个由不同代码库构建的服务器，启动将失败，并且错误日志会以与 `villagesql_schema_version` 相同的 `{codebase}_{version}` 格式指出这两个版本：

```
Cannot upgrade the VillageSQL schema across code bases: this data directory was created by a <data-directory-version> build, but this server is a <server-version> build. Use the original server binary for this data directory.
```

没有受支持的方法可以在代码库之间迁移数据目录。请继续使用创建该数据目录的代码库的服务器二进制文件。`--upgrade=MINIMAL` 不会绕过此项检查。

## 扩展兼容性

VillageSQL 扩展是特定于版本的。为 VillageSQL 的一个版本构建的扩展可能无法在另一个版本中正常运行。

升级 VillageSQL 时：

1. 检查新版本的扩展兼容性
2. 根据需要更新或重新构建扩展
3. 在生产环境中部署之前，在开发环境中测试扩展

请参阅 [升级指南](/docs/guides/upgrade)，了解详细的升级步骤。