railway-database

Railway データベース

公式の Railway データベースサービスを追加します。これらはメンテナンスされたテンプレートで、ボリューム、ネットワーキング、接続用変数が事前に設定されています。

データベース以外のテンプレートについては、railway-templates スキルを参照してください。

使用するタイミング

• ユーザーが「データベースを追加」「Postgres を追加」「Redis を追加」などと依頼したとき
• ユーザーがアプリケーション用のデータベースを必要としているとき
• ユーザーがデータベースへの接続について尋ねたとき
• ユーザーが「Postgres を追加してサーバーに接続して」と言ったとき
• ユーザーが「データベースを接続して」と言ったとき

判断フロー

作成する前に、必ず既存のデータベースを最初に確認してください。

User mentions database
        │
  Check existing DBs first
  (query env config for source.image)
        │
   ┌────┴────┐
 Exists    Doesn't exist
    │           │
    │      Create database
    │      (CLI or API)
    │           │
    │      Wait for deployment
    │           │
    └─────┬─────┘
          │
    User wants to
    connect service?
          │
    ┌─────┴─────┐
   Yes         No
    │           │
Wire vars    Done +
via env     suggest wiring
skill

既存のデータベースを確認する

データベースを作成する前に、すでに存在するかどうかを確認します。

環境設定の完全な構造については、environment-config.md を参照してください。

railway status --json

次に、環境設定をクエリし、各サービスの source.image を確認します:

query environmentConfig($environmentId: String!) {
  environment(id: $environmentId) {
    config(decryptVariables: false)
  }
}

config.services オブジェクトには、各サービスの設定が含まれています。次の source.image を確認してください:

• ghcr.io/railway/postgres* または postgres:* → Postgres
• ghcr.io/railway/redis* または redis:* → Redis
• ghcr.io/railway/mysql* または mysql:* → MySQL
• ghcr.io/railway/mongo* または mongo:* → MongoDB

利用可能なデータベース

データベース	テンプレートコード
PostgreSQL	postgres
Redis	redis
MySQL	mysql
MongoDB	mongodb

前提条件

プロジェクトのコンテキストを取得します:

railway status --json

次の値を抽出します:

• id - プロジェクト ID
• environments.edges[0].node.id - 環境 ID

ワークスペース ID を取得します(status の出力には含まれません):

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query getWorkspace($projectId: String!) {
    project(id: $projectId) { workspaceId }
  }' \
  '{"projectId": "PROJECT_ID"}'
SCRIPT

データベースの追加

ステップ 1: テンプレートを取得する

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query template($code: String!) {
    template(code: $code) {
      id
      name
      serializedConfig
    }
  }' \
  '{"code": "postgres"}'
SCRIPT

これにより、デプロイに必要なテンプレートの id と serializedConfig が返されます。

ステップ 2: テンプレートをデプロイする

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation deployTemplate($input: TemplateDeployV2Input!) {
    templateDeployV2(input: $input) {
      projectId
      workflowId
    }
  }' \
  '{
    "input": {
      "templateId": "TEMPLATE_ID",
      "serializedConfig": SERIALIZED_CONFIG,
      "projectId": "PROJECT_ID",
      "environmentId": "ENVIRONMENT_ID",
      "workspaceId": "WORKSPACE_ID"
    }
  }'
SCRIPT

重要: serializedConfig は、文字列ではなく、テンプレートクエリから得られた正確なオブジェクトです。

データベースへの接続

デプロイ後、他のサービスは参照変数を使用して接続します。

変数参照の完全な構文と接続パターンについては、variables.md を参照してください。

バックエンドサービス(サーバー側)

サーバー間通信にはプライベート/内部 URL を使用します:

データベース	変数参照
PostgreSQL	${{Postgres.DATABASE_URL}}
Redis	${{Redis.REDIS_URL}}
MySQL	${{MySQL.MYSQL_URL}}
MongoDB	${{MongoDB.MONGO_URL}}

フロントエンドアプリケーション

重要: フロントエンドはユーザーのブラウザで実行されるため、Railway のプライベートネットワークにアクセスできません。パブリック URL を使用するか、バックエンド API を経由する必要があります。

フロントエンドから直接データベースにアクセスする場合(推奨されません):

• パブリック URL 変数を使用します(例: ${{MongoDB.MONGO_PUBLIC_URL}})
• TCP プロキシが有効になっている必要があります

より良いパターン: フロントエンド → バックエンド API → データベース

例: PostgreSQL を追加する

bash <<'SCRIPT'
# 1. Get context
railway status --json
# Extract project.id and environment.id

# 2. Get workspace ID
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query { project(id: "proj-id") { workspaceId } }' '{}'

# 3. Fetch Postgres template
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query { template(code: "postgres") { id serializedConfig } }' '{}'

# 4. Deploy template
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation deploy($input: TemplateDeployV2Input!) {
    templateDeployV2(input: $input) { projectId workflowId }
  }' \
  '{"input": {"templateId": "...", "serializedConfig": {...}, "projectId": "...", "environmentId": "...", "workspaceId": "..."}}'
SCRIPT

別のサービスから接続する

railway-environment スキルを使用して、変数参照を追加します:

{
  "services": {
    "<backend-service-id>": {
      "variables": {
        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
      }
    }
  }
}

レスポンス

デプロイが成功すると、次が返されます:

{
  "data": {
    "templateDeployV2": {
      "projectId": "e63baedb-e308-49e9-8c06-c25336f861c7",
      "workflowId": "deployTemplate/project/e63baedb-e308-49e9-8c06-c25336f861c7/xxx"
    }
  }
}

作成されるもの

各データベーステンプレートは、次のものを作成します:

• データベースイメージを使用したサービス
• データ永続化用のボリューム
• 接続文字列用の環境変数
• 外部からのアクセス用の TCP プロキシ(該当する場合)

エラー処理

エラー	原因	解決策
テンプレートが見つからない	無効なテンプレートコード	postgres、redis、mysql、mongodb のいずれかを使用
権限がない	ユーザーにアクセス権がない	DEVELOPER ロール以上が必要
プロジェクトが見つからない	無効なプロジェクト ID	railway status --json を実行して正しい ID を確認

ワークフローの例

「postgres を追加してサーバーに接続して」

1. 環境設定のクエリで既存の DB を確認する
2. postgres が存在する場合: ステップ 5 にスキップする
3. 存在しない場合: postgres テンプレートをデプロイする(テンプレートを取得 → デプロイ)
4. デプロイが完了するまで待つ
5. 対象のサービスを特定する(複数ある場合は確認するか、リンクされたサービスを使用する)
6. railway-environment スキルを使用して変更をステージングする: DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }
7. 変更を適用する

"add postgres"

1. 環境設定のクエリで既存の DB を確認する
2. 存在する場合: 「Postgres already exists in this project」
3. 存在しない場合: Postgres テンプレートをデプロイする
4. ユーザーに通知する: 「Postgres created. Connect a service with: DATABASE_URL=${{Postgres.DATABASE_URL}}」

"connect the server to redis"

1. 環境設定のクエリで既存の DB を確認する
2. redis が存在する場合: environment スキルで REDIS_URL を接続 → 適用
3. redis が存在しない場合: 「No Redis found. Create one?」と確認する
   • redis テンプレートをデプロイする
   • REDIS_URL を接続 → 適用

Composability

• サービスの接続: railway-environment スキルを使用して変数参照を追加する
• データベースサービスの表示: railway-service スキルを使用する
• ログの確認: railway-deployment スキルを使用する