database

用途

该技能用于在 Railway 平台项目中添加官方数据库服务。用户提出「add a database」「add Postgres」「add Redis」「add mysql」「add mongodb」等需求，或需要为应用添加数据库、连接数据库、接入数据库时，可触发本技能。它针对的是数据库类模板；非数据库模板应参考 templates 技能。

主要能力

支持四种数据库，对应模板代码：

• PostgreSQL — 模板代码 postgres
• Redis — 模板代码 redis
• MySQL — 模板代码 mysql
• MongoDB — 模板代码 mongodb

这些是已维护的模板，预配置了存储卷、网络和连接变量。创建数据库模板会生成：数据库镜像对应的服务、用于数据持久化的存储卷、连接字符串所需的环境变量，以及（在适用情况下）用于外部访问的 TCP 代理。

使用方式

1. 先检查已有数据库

在创建之前，始终先检查是否已存在数据库。执行 railway status --json，然后查询环境配置，检查每个服务的 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

2. 获取项目上下文

执行 railway status --json，提取项目 ID（id）与环境 ID（environments.edges[0].node.id）。工作区 ID 不在 status 输出中，需通过 API 查询获取：

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

3. 添加数据库

第一步，获取模板：

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

返回模板的 id 和 serializedConfig。

第二步，部署模板：

bash <<'SCRIPT'
scripts/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 是模板查询返回的原始对象，而非字符串。

4. 连接数据库

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

后端服务（服务端）使用私有内部 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 → 数据库。

通过 environment 技能添加变量引用示例：

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

适用场景

用户要求添加数据库、为应用添加数据库、询问如何连接数据库、要求「add postgres and connect to my server」或「wire up the database」时适用。典型工作流包括：添加 Postgres 并连接服务器、仅添加 Postgres、将服务器连接到 Redis 等。连接服务时使用 environment 技能添加变量引用，查看数据库服务使用 service 技能，查看日志使用 deployment 技能。

错误处理

• Template not found：模板代码无效，应使用 postgres、redis、mysql、mongodb。
• Permission denied：用户缺少访问权限，需要 DEVELOPER 或更高角色。
• Project not found：项目 ID 无效，运行 railway status --json 获取正确 ID。

限制

前端应用无法直接访问 Railway 私有网络；直接从前端访问数据库不受推荐，且需要启用 TCP 代理。创建数据库需要 DEVELOPER 或更高角色权限。关于收费、价格、性能或效果等具体信息，暂未提供。