Zektor

zektor

Zektor.io のマネージドデータベースおよびキャッシュ用コマンドラインクライアントです。

ベータ版です。 CLI とその MCP サーバーはサポートされており、利用できますが、まだ登場して間もありません。使われ方を学びながら、コマンドを追加し、使いにくい部分を改善していく予定です。

ベータ版であることは、現在の機能の安定性についての警告ではありません。1.0.0 でコマンドのインターフェースが確定します。 メジャーバージョンが変わらない限り、フラグ、出力形式、終了コードは変更されないため、スクリプトで --json を安全に解析でき、今作成したトークンも引き続き使用できます。

インストール

npm install -g zektor

インストールせずに実行することもできます。

npx zektor whoami

Node 18 以降が必要です。

認証

ダッシュボードの Settings → Access tokens でトークンを作成し、次のコマンドを実行します。

zektor login

トークンは ~/.config/zektor/config.json にモード 0600 で保存されます。書き込む前に API で検証されるため、トークンの入力ミスは次回のコマンドで混乱するのではなく、この時点でエラーになります。

--token はスクリプト用にありますが、キーボードを使える環境ではプロンプトを使うことをおすすめします。引数はシェルの履歴に残ります。

CI での使用

ZEKTOR_TOKEN を設定し、login を省略します。

ZEKTOR_TOKEN=zk_… zektor whoami

ZEKTOR_TOKEN は常に設定ファイルより優先されます。zektor whoami では、どちらから認証情報が提供されたかを確認できます。通常、ログインしたアカウントが意図せず環境変数で上書きされていることに気づく手掛かりになります。

コマンド

コマンド	説明
zektor try	次の 1 時間利用できる Postgres データベースを作成します。アカウントは不要です（下記参照）。
zektor login	このマシンにトークンを保存します
zektor logout	保存したトークンを削除します。トークンは失効しません。同じトークンがほかの場所で使用されている可能性があります。アクセスを終了するには Settings で失効させてください。
zektor whoami	アカウント、API URL、トークンの取得元を表示します
zektor list	自分のインスタンスを一覧表示します
zektor show <id>	1 つのインスタンスを表示します
zektor db create / zektor cache create	データベースまたはキャッシュをプロビジョニングします
zektor delete <id>	インスタンスを削除します。インスタンス名の入力を求められます。--yes を指定すると確認を省略します。
zektor connect <id>	キャッシュに対して redis-cli を開きます
zektor scale <id> --tier=…	インスタンスを別のプランに変更します
zektor storage show|resize|autoscale <id>	Postgres ストレージの料金を確認し、容量を増やし、自動拡張を設定します（下記参照）。
zektor mcp	MCP サーバーとして実行し、エディターやエージェントから API を操作できるようにします（下記参照）。

すべての読み取りコマンドで --json を指定できます。

アカウントなしで試す

psql "$(npx zektor try)"

zektor try は接続文字列を標準出力に、利用可能時間と引き継ぎリンクを標準エラー出力に表示します。データベースへの接続は 60 分間可能です。3 時間以内に引き継ぎリンクを開いてサインアップし、支払い方法を追加すると、データは自分専用のデータベースに移行されます。そうしない場合、データは削除されます。容量は最大 200 MB、接続数は 3 つまでで、スーパーユーザー権限はありません（pgcrypto などの信頼済み拡張機能は使用できます）。1 つのネットワークにつき、1 日 3 回まで試用できます。--json を指定すると、すべて JSON で出力されます。CLI を使わずに同じことを行うこともできます。

curl -X POST https://api.zektor.io/api/trial

作成

zektor db create --name=my-db --tier=AKPG-5 --region=nbg1 --engine=postgres@17

--tier、--region、--engine には、ダッシュボードに表示される名前を指定します。対応する ID は自動的に取得されます。--tier と --region は必須です。どちらかを省略するか、無効な値を指定すると、有効な値の一覧がエラーに表示されます。

作成処理はバックグラウンドで実行されます。インスタンスの準備ができるまで待つには --wait を追加してください。作成に失敗した場合、コマンドは理由を表示し、ゼロ以外の終了コードを返します。

--storage は指定できません。ストレージはプランに含まれる容量から開始します。容量を増やすには、後から zektor storage resize を実行してください。

接続

キャッシュの場合、connect は redis-cli を開きます。Postgres の場合は、代わりにコマンドの形式を表示します。ロールの作成時またはローテーション時にパスワードが一度だけ表示され、サーバーには保存されないため、CLI が取得できる認証情報がありません。まずダッシュボードでロールを作成するか、ローテーションしてください。

スケーリングとストレージ

zektor scale 42 --tier=AKPG-10
zektor storage show 42
zektor storage resize 42 --size=50
zektor storage autoscale 42 --on --limit=100

scale はインスタンスを再起動するため、インスタンス名の入力を求めます。 --yes を指定すると、この確認を省略できます。ダウングレード時には、 小さいプランのメモリが、インスタンスで現在使用されている可能性のある量より 少ないことを警告します。対象のプランに含まれるストレージがデータベースの 請求対象の容量より少ない場合、scale は --yes の有無にかかわらず、 差額の料金も表示します。

scale と storage resize もバックグラウンドで実行され、--wait を指定できます。 これを指定すると、変更が完了するまで処理をブロックします。失敗した場合は 理由を表示し、ゼロ以外の終了コードで終了します。指定しない場合、インスタンスが 以前のプランのままになるだけなので、スケールに失敗しても気づきにくくなります。

ストレージは PostgreSQL のみ です。キャッシュのサイズはプランによって決まるため、 scale を使用してください。

• プランに含まれる容量。 すべてのプランにストレージが含まれます。AKPG-5 から AKPG-40 までは 5 GB、AKPG-80、160、320 では 10、20、40 GB です。新しい データベースはこの容量で開始します。
• 拡張。 storage resize を使うと、いつでも最大 1000 GB まで拡張できます。 再起動は不要で、オンラインで実行されます。新しいサイズの料金は標準エラー出力に 表示されます。
• 縮小不可。 ストレージは拡張のみ可能です。ユーザー自身、プランの変更、 リストアのいずれによっても縮小できません。料金を減らすには、pg_dump で 新しいデータベースに移行し、古いデータベースを削除するしかありません。
• 料金。 プランに含まれる容量を超えた分について、GB 単位で月あたり 0.15 ユーロ （税抜き）が請求されます。プランと同じく、時間単位で按分されます。料金の対象は 使用量ではなくサイズです。行を削除すると空き容量は増えますが、料金は変わりません。 storage show を実行すると、現在の請求対象が表示されます。
• 支払い。 プランに含まれる容量を超えて拡張する場合や、自動拡張を有効にする場合は、 支払い方法またはアカウント残高が必要です。
• 自動拡張。 これはオプトイン方式で、現在のサイズを上回る上限が必要です。 storage autoscale 42 --on --limit=100 のように指定します。使用率が 80％に 達すると、上限を超えない範囲で、5 GB の追加または使用率 70％になるサイズのうち 大きい方まで拡張します。拡張は都度元に戻せず、手動での拡張と同様に請求されます。 拡張のたびに通知されます。自動拡張に失敗すると、次の試行まで 1 日待機します。 API は省略された値を「変更しない」と解釈するため、一度設定した上限は解除できません。 新しい数値を設定するか、--off で拡張を無効にしてください。
• プランの変更。 より多くのストレージが含まれるプランにアップグレードすると、 ストレージ容量は無料でそのプランの容量まで増えます。ダウングレードしても ストレージ容量は維持され、縮小後のプランを超える GB が請求されます。
• ブランチ。 ブランチは、そのブランチである間、プラン料金に加えて、プランに 含まれる容量を超えてブランチ自身が書き込んだ分が請求されます。昇格後は、 全容量が請求対象になります。これはブランチ作成時のソースのサイズ（拡張済みの場合は そのサイズ以上）です。
• レガシーデータベース。 拡張可能なストレージが導入される前に作成された データベースは、まだ拡張できません。まもなく移行される予定で、ストレージ料金は 請求されません。

1.7.0 での変更点。 storage resize は、/api/instances/{id}/storage/grow を 使用してストレージを拡張するようになり、現在のサイズより大きくないサイズを拒否します。 storage autoscale は引き続き --min と --up-only を受け付けますが、これらは 無視されます。MCP ツール resize_storage では、confirm_name が必須になりました。

MCP サーバー

zektor mcp は、標準入出力経由で Model Context Protocol を使用するため、 エディターやエージェントからインスタンスを直接一覧表示、作成、スケーリングできます。 すでにログインに使用したトークンを使うため、追加の設定は不要です。

MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "zektor": { "command": "npx", "args": ["-y", "zektor", "mcp"] }
  }
}

Claude Code では、claude mcp add zektor -- npx -y zektor mcp を実行しても同じ設定ができます。

ツール

ツール
create_trial_database	トークンが設定されていない場合のみ：1 時間利用できる無料データベース。ユーザーに渡すための利用申請リンクが付属します
whoami、list_instances、get_instance	読み取り専用
get_action	読み取り専用；create_instance、scale_instance、resize_storage によって開始されたバックグラウンド処理の結果を、返された actionId で確認します
list_plans、list_regions	読み取り専用；名前を推測せず、作成前にこれらを呼び出してください
get_connection	読み取り専用；キャッシュの場合、有効なパスワードを返します
get_storage	読み取り専用、PostgreSQL；サイズ、使用量、プランを超過した分の課金額を確認します
create_instance	有料です
scale_instance	請求額が変わります；スケールダウンするとインスタンスのメモリが不足する場合があり、ストレージは維持されるため、小さいプランの上限を超える GB 分が課金されます
resize_storage	PostgreSQL；ストレージを拡張します。元に戻すことはできません；プランの上限を超える GB 分が課金されます
set_autoscale	PostgreSQL；上限を設定して、自動拡張をオンまたはオフにします
delete_instance	デフォルトでは無効です — 詳細は以下をご覧ください

ガードレール

CLI には、誤った対象を削除しないための保護機能として、ターミナルで インスタンス名を入力させるプロンプトがあります。MCP サーバーには ターミナルがなく、呼び出し元はモデルであるため、そのガードは 取り除くのではなく、別の形に置き換えています。

• ZEKTOR_MCP_ALLOW_DESTRUCTIVE=1 が設定されていない限り、 delete_instance は登録されません。 デフォルトではツール自体が一覧に表示されないため、 誤解やプロンプトへの命令注入があっても、最悪の場合に起こるのは出費であり、データの損失ではありません。
• scale_instance、resize_storage、delete_instance には confirm_name 引数が必要です。 この引数は、インスタンスの実際の名前と一致しなければなりません。インスタンスを 実際に検索して初めて設定できるため、名前を入力させるプロンプトと同じ特性を備えています。
• すべてのツールには、プロトコルの readOnlyHint／destructiveHint アノテーションが付いているため、ツールの実行前に確認を求めるクライアントは、 適切なツールについて確認します。

get_connection については、個別に注意が必要です。キャッシュの場合、 有効なパスワードを含む接続文字列を返すため、そのパスワードが モデルのコンテキストに入ります。これがこのツールの目的です。 エージェントが新しいキャッシュにアプリを接続する方法ですが、 会話をログに記録する場所でサーバーを有効にする前に、知っておく価値があります。

診断

サーバーは起動時に、API URL、トークンの検出場所、削除が有効かどうかを stderr に書き込みます。MCP クライアントはこれをサーバーログとして収集します。 誤った API を参照しているサーバーは、ログを読むまでは、単に動作していないように見えます。

出力

stdout にはデータだけが出力されます。 進行状況、警告、エラーは stderr に出力されるため、パイプの内容はクリーンに保たれます。

zektor whoami --json | jq -r .email

失敗時はゼロ以外の終了コードで終了するため、zektor … && next-command は、 シェルが検知できなかったエラーを無視して処理を続けるのではなく、停止します。

設定

変数	用途
ZEKTOR_TOKEN	アクセストークン。設定ファイルより優先されます。
ZEKTOR_API_URL	API のベース URL。デフォルトは https://api.zektor.io です。
XDG_CONFIG_HOME	設定されている場合に使用されます。設定ファイルは $XDG_CONFIG_HOME/zektor/ の下に置かれます。
ZEKTOR_MCP_ALLOW_DESTRUCTIVE	1 に設定すると、MCP サーバーに delete_instance が登録されます。設定されていない場合、このツールは存在しません。

ロードマップ

次に予定している項目を、おおよその利用頻度順に示します。

• バックアップ — 一覧表示、作成、特定時点への復元
• ロール — Postgres の認証情報を作成およびローテーションします。これにより、手順を表示するのではなく、Postgres で connect を動作させられるようになります
• ログ — インスタンスのログを追跡します。現在、人々がブラウザーを開く唯一の用途です

予定していないもの：管理者コマンド。管理者コンソールは意図的にブラウザー専用です。

開発

npm install
npm run gen:api     # regenerate types/api.d.ts from the API's OpenAPI document
npm run build
node dist/index.js whoami

ZEKTOR_API_URL=http://localhost:5098 を指定してすべてをローカル API に接続します。MCP サーバーも同様です。ZEKTOR_API_URL=http://localhost:5098 node dist/index.js mcp を実行すると、本番環境ではなく開発用バックエンドが提供されます。

npm run gen:api を実行すると、API の OpenAPI 型定義一式が types/ に書き出されます。このディレクトリは git の追跡対象外です。型定義には管理者向けのエンドポイントも含め、すべてのエンドポイントが記述されていますが、これをインポートするコードはありません。これは src/api.ts に手書きされたインターフェースを実際の仕様と照合するためのツールであり、ビルド入力ではありません。ローカル API を指定するには、ZEKTOR_API_URL=http://localhost:5098 npm run gen:api を実行します。