> ## 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 と拡張インターフェイスがより頻繁に変更される可能性があります。

### 開発ビルド

プレリリースサフィックスが付いたバージョン（例: `0.0.7-dev`）は、開発ビルドです。デフォルトでは、開発ビルドで初期化されたデータベースからのアップグレードは、サーバーによってブロックされます。開発ビルドは、アップグレードの互換性についてテストされておらず、破壊的なスキーマまたはプロトコルの変更が含まれる可能性があります。

これを許可するには、サーバーを `--villagesql-allow-unsafe-dev-upgrade` フラグ付きで起動します。

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

フラグがない場合、サーバーは開発バージョンデータベースを検出するとエラーで終了します。

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

フラグが指定されている場合、サーバーは警告をログに記録して続行します。

```
Upgrading from a development version (mysql-8.4_0.0.7-dev); --villagesql-allow-unsafe-dev-upgrade was specified.
```

フラグが指定されているが、現在のバージョンが開発ビルドでない場合、サーバーはエラーで終了します。

```
--villagesql-allow-unsafe-dev-upgrade specified, but current version (mysql-8.4_0.0.6) is not a development version.
```

### 最小限のアップグレード

`--upgrade=MINIMAL` を付けてサーバーを起動すると、絶対に必要というわけではないアップグレード手順がスキップされます。VillageSQL のスキーマアップグレードは、スキップされる手順には含まれません。サーバーのアップグレードが必要な状態でこのモードでサーバーを起動すると、サーバーのアップグレードをスキップしたという警告がログに記録され、保存されている VillageSQL スキーマバージョンがビルドバージョンと一致しない場合は VillageSQL のスキーマアップグレードが実行されます。

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

このモードで VillageSQL のスキーマアップグレードが失敗した場合、サーバーは起動を中止します。開発ビルドで初期化されたデータディレクトリは、このモードでも拒否されます。これを許可するには、`--villagesql-allow-unsafe-dev-upgrade` を付けて起動してください。

### コードベースの変更

すべての VillageSQL バージョンは、コードベース（サーバーがビルドの基盤とするアップストリームのフォーク）に結び付けられています。たとえば、`mysql-8.4_0.0.6` は `mysql-8.4` コードベースのバージョン 0.0.6 です。異なるコードベースのバージョン番号は比較できないため、コードベース間の移動はサポートされるアップグレードではありません。`mysql-8.4_0.0.5` から `mysql-8.4_0.0.6` へのアップグレードは可能ですが、`mysql-8.4_0.0.6` から `mysql-9.7_0.0.6` へのアップグレードはできません。

データディレクトリは、それを作成したサーバーのコードベースを [`villagesql_schema_version`](https://villagesql.com/docs/ja/8.4/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. 本番環境にデプロイする前に、開発環境で拡張機能をテストします。

詳細なアップグレード手順については、[アップグレードガイド](https://villagesql.com/docs/en/guides/upgrade.md)を参照してください。

## 次のステップ

> [card] [クイックスタート](https://villagesql.com/docs/en/quickstart.md)
>
> 1 つのコマンドで VillageSQL をインストールするか、コーディングエージェントにセットアップを任せます。

> [card] [インストール](https://villagesql.com/docs/ja/8.4/stable/install-server.md)
>
> すべてのインストール方法を確認し、接続して、最初の拡張機能を読み込みます。


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