> ## 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_ROOT_PASSWORD=<your-password> -p 3306:3306 villagesql/server:mysql-9.7_latest
```

### オプション B: シェルスクリプト

公式のインストールスクリプトを使用して、マシンに 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` を受け付けます。Percona ビルドは MySQL 8.4 のみに追随します。`INSTALL_METHOD` は `docker`、`prebuilt`、`source` を受け付けます。ソースビルドでは `VSQL_VERSION=stable|nightly|latest` も必要です。Docker とビルド済みバイナリのインストールは、常に安定版リリースです。

スクリプトを実行する前に確認するには: `curl -fsSL https://install.villagesql.com | less`

### オプション C: ソースコードからのビルド

開発またはカスタムビルドの場合は、[ソースコードからのクローンとビルドガイド](https://villagesql.com/docs/ja/9.7/stable/source.md)に従って、最新のコードからコンパイルします。

### シェルスクリプトがセットアップする内容

シェルスクリプト (オプション B) は、サーバーを `~/.villagesql/` の下にインストールし、ポート 3306 で起動します。スクリプトのインストール方法の質問で Docker を選んだ場合は、代わりに `vsql` という名前のコンテナを起動します。重要な場所は次のとおりです。

| パス | 内容 |
| - | - |
| `~/.villagesql/credentials.txt` | 生成された root パスワードと、すぐに実行できる起動、停止、接続の各コマンド (自分だけが読み取り可能) |
| `~/.villagesql/data/` | データベースのデータディレクトリ |
| `~/.villagesql/mysql.sock` | サーバーのソケット |
| `~/.villagesql/mysql.log` | サーバーのエラーログ |

`~/.local/bin` が存在し、書き込み可能な場合、スクリプトはショートカットも追加します: `villagesql` (クライアント)、`villagesql-server` (サーバー)、`villagesql-admin` (管理ツール)。

Docker (オプション A) と手動のソースビルドは `~/.villagesql/` を作成しません。Docker は、コンテナ内の `/var/lib/mysql` にマウントされた Docker ボリュームにデータを保持します。

## ステップ 2: サーバーへの接続

**Docker (オプション A)。** 任意の MySQL クライアントで接続し、`MYSQL_ROOT_PASSWORD` で設定した root パスワードを入力します。デフォルトの `localhost` ではなく `-h 127.0.0.1` を使用してください。`localhost` を指定するとクライアントは Unix ソケットを探しますが、サーバーが Docker で実行されている場合はそのソケットに到達できません。

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

マシンに MySQL クライアントがない場合は、コンテナ内のクライアントを使用します。

```bash theme={null}
docker exec -it vsql mysql -u root -p
```

**シェルスクリプト (オプション B)。** スクリプトは独自の MySQL クライアントをインストールしますが、`PATH` には追加しません。スクリプトが `~/.villagesql/credentials.txt` に保存した `Connect` コマンドを実行してください。root パスワードも同じファイルにあります。ビルド済みバイナリのインストールでは、コマンドは次のようになります。

```bash theme={null}
~/.villagesql/prebuilt/bin/mysql -u root -p --socket="$HOME/.villagesql/mysql.sock"
```

ソースビルドの場合、クライアントは代わりに `~/.villagesql/build/bin/` にあります。スクリプトのインストール方法の質問で Docker を選んだ場合は、スクリプトはパスワードを画面に表示し、`credentials.txt` は保存しません。オプション A と同じ方法で接続してください。

## ステップ 3: 最初の拡張機能のインストール

`INSTALL EXTENSION <name>` は、サーバーの VEB ディレクトリ内で `<name>.veb` を探します。その場所を確認するには `SHOW VARIABLES LIKE 'veb_dir';` を実行してください。

Docker(オプション A)またはシェルスクリプト(オプション B)でインストールした場合、`.veb` ファイル一式はすでに `veb_dir` に配置されています。ダウンロードやコピーは不要です。そこには 2 種類の拡張機能が含まれています。

* 拡張機能。`vsql_uuid`(UUID 型と生成関数)や、[バンドルされた拡張機能の一覧](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt)に載っているその他の拡張機能がこれにあたります。
* `vsql_complex` と `vsql_simple`。拡張機能フレームワークの仕組みを示すために本ドキュメントの他の箇所(「[C++ 拡張の例](https://villagesql.com/docs/ja/sdk/cpp/examples.md)」を参照)で使われるリファレンス拡張機能です。

ソースからビルドした場合(オプション C)も、`vsql_complex` と `vsql_simple` はすでに `veb_dir` にあります。`make install` がこれらを無条件にビルドするためです。一方、`vsql_uuid` をはじめとするその他の拡張機能はそうではありません。これらは別のリポジトリで管理されており、個別にビルドしてインストールする必要があります。オプション C を使った場合は、続ける前に [vsql-uuid](https://github.com/villagesql/vsql-uuid) をクローンしてビルドするか、代わりに `vsql_complex` を使ってこの先に進んでください。詳しくは「[拡張機能のインストール](https://villagesql.com/docs/ja/extensions/install.md)」を参照してください。

`vsql_uuid` 拡張機能をインストールして、ネイティブな UUID 生成と `UUID` 列型を追加します。

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

インストールを確認します。

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

`vsql_uuid` がリストされているはずです。

詳細については、[拡張機能のインストール](https://villagesql.com/docs/ja/extensions/install.md) を参照してください。

## ステップ 4: 拡張データ型の使用

拡張機能がアクティブになったので、テーブルで `UUID` 型をネイティブ型と同様に使用できます。標準の各バージョン用のジェネレーター — `UUID_V1()`、`UUID_V1MC()`、`UUID_V3()`、`UUID_V4()`、`UUID_V5()`、`UUID_V6()`、`UUID_V7()` (`UUID_V2()` は存在しません) — に加えて、格納された値を調べる関数も使用できます。以下の例では v7 を使用します。v7 の値は埋め込まれたタイムスタンプを持ち、1 ミリ秒を超える間隔で生成された場合は作成時刻順にソートされます。同じミリ秒内に生成された値は、呼び出し順ではなくランダムビットによって順序付けられます。つまり、`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. Each UUID_V7() embeds a millisecond
-- timestamp, so rows inserted in the same statement can land in the same
-- millisecond and tie-break on their random bits instead of insertion
-- order — insert separately, with a gap, to see the ordering clearly.
INSERT INTO events VALUES (UUID_V7(), 'signup');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'login');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (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}
DROP DATABASE demo;
UNINSTALL EXTENSION vsql_uuid;
```

## サーバーの停止と再起動

サーバーの停止と起動は、そのコンテナ (Docker) またはバックグラウンドプロセス (シェルインストール) を制御することで行います。データベースはそれに合わせて起動および停止します。

* **Docker (オプション A):** `docker stop vsql` でサーバーを停止し、`docker start vsql` で再び起動します。
* **シェルスクリプト (オプション B):** データディレクトリ、ソケット、ポートがすでに設定された、お使いのインストール用の起動、停止、接続の各コマンドは `~/.villagesql/credentials.txt` にあります。スクリプトのインストール方法の質問で Docker を選んだ場合は、上記の Docker のコマンドを使用してください。

## 次のステップ

VillageSQL を起動し、拡張機能システムを検証したので、さらに詳しく調べてみましょう。

> [card] [拡張機能の管理](https://villagesql.com/docs/ja/extensions/managing.md)
>
> 他の拡張機能をインストールおよび管理する方法を学びます。

> [card] [拡張機能の作成](https://villagesql.com/docs/ja/extensions/build/create.md)
>
> VillageSQL 用に独自の拡張機能を作成する方法を学びます。

> [card] [アップグレードガイド](https://villagesql.com/docs/en/guides/upgrade.md)
>
> 以前のバージョンからのアップグレード、または MySQL からの移行。

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

### サーバーが起動しない

一般的な問題:

* ポート 3306 がすでに使用されている: 他のサーバーを停止するか、`PORT=<port>` を設定してインストーラーを実行してください。Docker の場合は、`-p` のホスト側を変更します。
* 権限: ファイルが読み取り/実行可能であることを確認します。


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