database

数据库

添加 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'
scripts/railway-api.sh \
  'query getWorkspace($projectId: String!) {
    project(id: $projectId) { workspaceId }
  }' \
  '{"projectId": "PROJECT_ID"}'
SCRIPT

添加数据库

第 1 步：获取模板

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

这会返回部署所需的模板 id 和 serializedConfig。

第 2 步：部署模板

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

连接数据库

部署后，其他服务可使用引用变量进行连接。

有关完整的变量引用语法和接入模式，请参阅 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
scripts/railway-api.sh \
  'query { project(id: "proj-id") { workspaceId } }' '{}'

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

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

然后从其他服务连接

使用 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. 使用 environment 技能暂存：DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }
7. 应用更改

“add postgres”

1. 通过环境配置查询检查现有数据库
2. 如果存在：“此项目中已存在 Postgres”
3. 如果不存在：部署 postgres 模板
4. 告知用户：“Postgres 已创建。使用以下配置连接服务：DATABASE_URL=${{Postgres.DATABASE_URL}}”

“connect the server to redis”

1. 通过环境配置查询检查现有数据库
2. 如果存在 redis：通过 environment 技能配置 REDIS_URL → 应用更改
3. 如果不存在 redis：询问：“未找到 Redis。要创建一个吗？”
   • 部署 redis 模板
   • 配置 REDIS_URL → 应用更改

组合使用

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