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

# MySQL からのアップグレード

> アップストリームの MySQL から VillageSQL へアップグレードする手順ガイド。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

VillageSQL Server は MySQL のドロップイン代替です。サードパーティのプラグインがない単一インスタンスの素の MySQL 8.4 インストールでは、VillageSQL への移行は機能的にマイナーバージョンのアップグレード(例: 8.4.5 から 8.4.6)と同じで、既存のデータは保持されます。非標準のプラグインに依存するものは、先にコピーでテストしてください。

## 前提条件

* **VillageSQL のバイナリ**: VillageSQL のバイナリ(ソースからコンパイルしたもの、またはダウンロードしたもの)を用意してください。
* **MySQL のバージョン**: VillageSQL は MySQL 8.4 LTS に基づいています。MySQL 8.4 からのアップグレードがサポートされる経路です。

> [!WARNING]
>
> **アップグレードを実行する前に、必ずデータをバックアップしてください。**
> このプロセスは安全になるように設計されていますが、データベースのアップグレードには常にリスクが伴います。

## ステップ 1: データのバックアップ

システムファイルやサービスに触れる前に、データベースの完全なバックアップを作成します。

### オプション A: 論理バックアップ(mysqldump)

すべてのデータベースの SQL ダンプを作成します。これが最も安全で移植性の高い方法です。

```bash theme={null}
mysqldump -u root -p --all-databases --events --routines --triggers > full_backup.sql
```

### オプション B: 物理バックアップ(データディレクトリ)

データセットが大きい場合は、サーバーを停止してデータディレクトリをコピーします。

```bash theme={null}
# Stop the server first (see Step 2)
cp -r /var/lib/mysql /var/lib/mysql-backup
```

## ステップ 2: MySQL サーバーの停止

データファイルのロックを解放するために、現在実行中の MySQL サーバーインスタンスを停止します。

**Systemd を使う場合(Linux):**

```bash theme={null}
sudo systemctl stop mysql
# OR
sudo systemctl stop mysqld
```

**SysV Init を使う場合:**

```bash theme={null}
sudo service mysql stop
```

**手動インストールの場合:**

```bash theme={null}
mysqladmin -u root -p shutdown
```

## ステップ 3: バイナリの置き換え

アップグレードの中核は、実行可能ファイル(`mysqld`、`mysql` など)をアップストリームの MySQL 版から VillageSQL 版に切り替えることです。

### 方法 A: インストールディレクトリの入れ替え(推奨)

MySQL を tarball でインストールした場合(例: `/usr/local/mysql` へ)、最もきれいな方法は、VillageSQL をその隣にインストールしてシンボリックリンクを切り替えることです。

1. **VillageSQL を展開/インストール**して、新しいディレクトリ(例: `/usr/local/villagesql-8.4`)に置きます。
2. **シンボリックリンクを更新**します。
   ```bash theme={null}
   # Remove link to old MySQL
   sudo unlink /usr/local/mysql

   # Link to VillageSQL
   sudo ln -s /usr/local/villagesql-8.4 /usr/local/mysql
   ```
3. **権限を確認**します。データベースを実行するユーザー(通常は `mysql`)が新しいバイナリの実行権限を持っていることを確認します。

### 方法 B: バイナリの上書き

VillageSQL をソースからコンパイルし、システムのインストール(例: `/usr/bin` または `/usr/local/bin`)を上書きしたい場合は次のようにします。

```bash theme={null}
# Assuming you are in the VillageSQL build directory
sudo make install
```

> [!NOTE]
>
> MySQL をパッケージマネージャー(`apt`、`yum`)でインストールした場合、バイナリを手動で上書きするのは危険です。パッケージマネージャーが更新時にそれらを元に戻してしまう可能性があるからです。`mysql-server` パッケージをアンインストールする(データファイルは残します!)か、利用できるなら `update-alternatives` を使うことをお勧めします。

## ステップ 4: 設定の確認

設定ファイル(通常は `/etc/my.cnf` または `/etc/mysql/my.cnf`)が既存のデータディレクトリを指していることを確認します。

```ini theme={null}
[mysqld]
datadir=/var/lib/mysql  # Should point to your EXISTING data
socket=/var/run/mysqld/mysqld.sock
```

VillageSQL は標準の MySQL 設定オプションを使うので、既存の `my.cnf` は変更なしで動作するはずです。

## ステップ 5: VillageSQL の起動

サービスマネージャーを使うか、手動でサーバーを起動します。

**Systemd を使う場合:**

```bash theme={null}
sudo systemctl start mysql
```

**手動起動:**

```bash theme={null}
/usr/local/mysql/bin/mysqld_safe --user=mysql &
```

### 自動アップグレード

起動時に、VillageSQL はデータファイルが古いバージョンのものかどうかを自動的に検出し、システムテーブルに必要なアップグレードを実行します。

エラーログ(通常は `/var/log/mysql/error.log` または `datadir` の中)を確認して、アップグレードが正常に完了したことを確認します。次の行を探してください。
`[System] [MY-013381] [Server] Server upgrade from '...' to '...' completed.`

## ステップ 6: インストールの確認

サーバーに接続し、VillageSQL が実行されていることを確認します。

```bash theme={null}
mysql -u root -p
```

次のクエリを実行します。

```sql theme={null}
SELECT @@version, @@version_comment;
```

これでデータが無傷であることを確認し、`INSTALL EXTENSION` のような VillageSQL 独自の機能を使い始められます。

## トラブルシューティング

* **"Data Dictionary Upgrade Failed"**: サーバーが起動を拒否する場合、ダウングレード(例: 8.4 から 8.0)を試みているか、データファイルが破損している可能性があります。エラーログを確認してください。
* **権限エラー**: `mysql` OS ユーザーが `datadir` と新しい VillageSQL インストールディレクトリを所有していることを確認してください。
  ```bash theme={null}
  sudo chown -R mysql:mysql /var/lib/mysql
  ```

## 関連項目

* [MySQL のスキーマ移行](https://villagesql.com/docs/ja/guides/schema-migrations.md) — アップグレード後に安全な DDL 変更を実行する
* [MySQL のバックアップ戦略](https://villagesql.com/docs/ja/guides/backup-strategies.md) — アップグレード前にバックアップする
* [Docker 上の MySQL](https://villagesql.com/docs/ja/guides/mysql-on-docker.md) — 代わりにコンテナで MySQL または VillageSQL を実行する
* [サポート終了後の MySQL 8.0 から 8.4 へのアップグレード](https://villagesql.com/docs/ja/guides/mysql-80-eol-upgrade.md) — まだ 8.0 の場合は、先に 8.4 に上げる


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