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（不在状态输出中）：

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. 通过环境配置查询检查现有数据库
2. 如果 postgres 已存在：跳到步骤 5
3. 如果不存在：部署 postgres 模板（获取模板 → 部署）
4. 等待部署完成
5. 确定目标服务（如果有多个则询问，或使用已链接的服务）
6. 使用 railway-environment 技能暂存：DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }
7. 应用更改

"add postgres"

1. 通过环境配置查询检查现有数据库
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. 通过环境配置查询检查现有数据库
2. 如果 redis 存在：通过 environment skill 连接 REDIS_URL → 应用
3. 如果没有 redis：询问 "No Redis found. Create one?"
   • 部署 redis 模板
   • 连接 REDIS_URL → 应用

可组合性

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