railway-database

用途

Railway Database 用于在 Railway 项目中添加官方维护的数据库服务模板。这些模板已预先配置好数据卷、网络和连接变量。该技能主要面向需要为应用添加数据库、连接数据库或配置数据库连接字符串的用户。

主要能力

支持添加四种官方数据库：PostgreSQL（模板代码 postgres）、Redis（redis）、MySQL（mysql）、MongoDB（mongodb）。
在创建数据库前检查项目中是否已存在数据库，避免重复创建。
通过 Railway API 获取模板并部署，部署成功后返回 projectId 和 workflowId。
每个数据库模板会创建：包含数据库镜像的服务、用于数据持久化的数据卷、连接字符串环境变量，以及（在适用时）用于外部访问的 TCP 代理。
支持将数据库连接变量接入其他服务，后端服务使用私有/内部 URL，前端应用需使用公共 URL 或通过后端 API 访问。

使用方式

前置条件

获取项目上下文：

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

检查已有数据库

在创建数据库前，先检查是否已存在。查询环境配置并检查每个服务的 source.image：

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

识别规则：

ghcr.io/railway/postgres* 或 postgres:* → Postgres
ghcr.io/railway/redis* 或 redis:* → Redis
ghcr.io/railway/mysql* 或 mysql:* → MySQL
ghcr.io/railway/mongo* 或 mongo:* → MongoDB

添加数据库

第一步：获取模板

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。

第二步：部署模板

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 是模板查询返回的精确对象，不是字符串。

连接数据库

部署后，其他服务通过引用变量连接。

后端服务（服务端）使用私有/内部 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. 获取上下文
railway status --json
# 提取 project.id 和 environment.id

# 2. 获取工作区 ID
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query { project(id: "proj-id") { workspaceId } }' '{}'

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

# 4. 部署模板
${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"
    }
  }
}

适用场景

用户要求“添加数据库”“添加 Postgres”“添加 Redis”等。
用户需要为应用添加数据库。
用户询问如何连接数据库。
用户说“添加 postgres 并连接到我的服务器”。
用户说“接好数据库”。

限制与错误处理

错误	原因	解决方案
Template not found	模板代码无效	使用：postgres、redis、mysql、mongodb
Permission denied	用户缺少权限	需要 DEVELOPER 角色或更高
Project not found	项目 ID 无效	运行 railway status --json 获取正确 ID

可组合性

连接服务：使用 railway-environment 技能添加变量引用。
查看数据库服务：使用 railway-service 技能。
查看日志：使用 railway-deployment 技能。

非数据库模板请参见 railway-templates 技能。