> ## 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 用 vsql_rest 拡張機能

> vsql_rest 拡張機能は、URL フィルター、ストアド関数の呼び出し、JWT 認証、および行数の上限を備え、サーバープロセスの内部から MySQL のテーブルを HTTP エンドポイントとして提供します。

`vsql_rest` は、データベースプロセスの内部からテーブルを HTTP 経由で提供します。クライアントは接続ではなく URL で行を読み取り、クエリパラメーターで絞り込み、`/rpc/` の下でストアド関数を呼び出します。書くべきアプリケーションも、実行すべき第 2 のプロセスもありません。

| | |
| - | - |
| **メンテナー** | VillageSQL |
| **ソースと完全なドキュメント** | [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) |
| **ライセンス** | GPL-2.0 |
| **機能** | プレビュー |

> [!WARNING]
>
> この拡張機能はプレビュー機能を使用するため、`vsql_allow_preview_extensions` が `ON` である必要があります。サーバーを `--vsql_allow_preview_extensions=ON` で起動するか、`SET PERSIST vsql_allow_preview_extensions = ON` を実行してください。そうでない場合、`INSTALL EXTENSION` は拒否されます。

## インストール

インストールスクリプト、Docker イメージ、またはリリース tarball で VillageSQL をインストールした場合、`vsql_rest.veb` はすでにサーバーの `lib/veb/` ディレクトリにあります。1 つのステートメントでサーバーにインストールします。

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

インストールされたことを確認します。

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_rest';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_rest      |
+----------------+
```

自分でビルドするには、[リポジトリ](https://github.com/villagesql/vsql-rest)のビルド手順に従ってください。

## 追加される機能

SQL 関数は追加しません。`SET GLOBAL` で設定し、応答するすべてのリクエストは HTTP 経由で届きます。

| 設定 | デフォルト | 制御内容 |
| - | - | - |
| `vsql_rest.vsql_rest_enabled` | `OFF` | リスナーを実行するかどうか |
| `vsql_rest.schema` | 空 | 提供するデータベース。これが設定されるまで、すべてのテーブルおよび RPC リクエストは `503` (コード `VSQL0007`) を受け取る |
| `vsql_rest.allowed_tables` | 空 | 到達可能なテーブル。空はすべてを意味する |
| `vsql_rest.table_methods` | 空 | 各テーブルが受け付ける HTTP メソッド。`table:GET,POST\|table2:GET` と書く。空は、すべてのテーブルで `GET`、`POST`、`PATCH`、および `DELETE` を意味する |
| `vsql_rest.allowed_routines` | 空 | `/rpc/` の下で呼び出せる関数。空はすべてを意味する |
| `vsql_rest.port` | `3000` | HTTP ポート |
| `vsql_rest.ssl_port` | `3443` | HTTPS ポート |
| `vsql_rest.ssl_cert`, `vsql_rest.ssl_key` | 空 | HTTPS 用の証明書と鍵 |
| `vsql_rest.require_auth` | `OFF` | リクエストに JWT を必須とするかどうか |
| `vsql_rest.jwt_secret`, `vsql_rest.jwt_public_key` | 空 | その JWT の検証方法 |
| `vsql_rest.max_rows` | `1000` | リクエストに `?limit` がないときに返る行数 |
| `vsql_rest.schema_ttl` | `60` | キャッシュされたテーブルレイアウトを再利用する時間 (秒)。`vsql_rest.schema` を変更するか、`vsql_rest_enabled` をオフにしてオンにすると、次のリクエストで再構築される |

## 例

リスナーは起動時にデータベースのレイアウトをキャッシュし、`schema_ttl` 秒間保持するため、先にテーブルを作成します。

```sql theme={null}
CREATE DATABASE extdocs;
USE extdocs;

CREATE TABLE people (id INT PRIMARY KEY, name VARCHAR(32));

INSERT INTO people VALUES
    (1, 'Jonathan Smith'),
    (2, 'John Smyth'),
    (3, 'Joan Smithe'),
    (4, 'Peter Brown');
```

次に、データベースとテーブルを指定してリスナーをオンにします。

```sql theme={null}
SET GLOBAL vsql_rest.schema = 'extdocs';
SET GLOBAL vsql_rest.allowed_tables = 'people';
SET GLOBAL vsql_rest.vsql_rest_enabled = ON;
```

HTTP 経由でテーブルを読み取ります。

```bash theme={null}
curl http://127.0.0.1:3000/people
```

```json theme={null}
[{"id":1,"name":"Jonathan Smith"},{"id":2,"name":"John Smyth"},{"id":3,"name":"Joan Smithe"},{"id":4,"name":"Peter Brown"}]
```

クエリパラメーターで絞り込みます。

```bash theme={null}
curl "http://127.0.0.1:3000/people?id=eq.2"
```

```json theme={null}
[{"id":2,"name":"John Smyth"}]
```

設定をオフにするとポートが閉じます。

```sql theme={null}
SET GLOBAL vsql_rest.vsql_rest_enabled = OFF;
```

> [!WARNING]
>
> デフォルトでは、認証は無効、すべてのテーブルが提供され、サポートされるすべての HTTP メソッド (`GET`、`POST`、`PATCH`、`DELETE`) が許可され、リスナーは起動した瞬間からすべてのインターフェイスにバインドします。ホストに到達できるものは何でも、スキーマ内のすべてのテーブルを読み書きできます。リスナーをオンにする前に、`allowed_tables`、`table_methods`、および `require_auth` を設定し、JWT のシークレットまたは公開鍵を構成し、ポートをファイアウォールの内側に置いてください。バインドアドレスの設定はありません。

> [!NOTE]
>
> `SET PERSIST` で書き込んだ設定は再起動後も残りますが、`UNINSTALL EXTENSION` はそれを削除します。アンインストールと再インストールの後は、すべての設定がデフォルトに戻り、再起動しても古い値は戻りません。

> [!NOTE]
>
> すべての文字列設定はサーバーを通して読み戻され、サーバーは最大 1022 バイトを返します。これより長い `schema`、`allowed_tables`、`allowed_routines`、`table_methods`、`jwt_secret`、または `jwt_public_key` は、すべてのリクエストを `500` で失敗させます。これより長い `ssl_cert` または `ssl_key` は、リスナーの起動を妨げます。

## 関連項目

* [テーブルを REST API として提供する](https://villagesql.com/docs/en/guides/rest-api-from-tables.md) — フィルター、テーブルごとのメソッド、および最初に変更すべきデフォルト
* [拡張機能の管理](https://villagesql.com/docs/ja/extensions/managing.md) — 拡張機能の設定の読み書き方法
* [プレビュー機能](https://villagesql.com/docs/ja/extensions/build/preview-capabilities.md) — プレビューフラグが有効にするものと、それが約束するもの
* [利用可能な拡張機能](https://villagesql.com/docs/ja/extensions/catalog) — 完全なカタログ
* [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) — ソース、完全なルート構文、および既知の制限事項


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