Railway Database

Add official Railway database services. These are maintained templates with pre-configured volumes, networking, and connection variables.

For non-database templates, see the railway-templates skill.

When to Use

• User asks to “add a database”, “add Postgres”, “add Redis”, etc.
• User needs a database for their application
• User asks about connecting to a database
• User says “add postgres and connect to my server”
• User says “wire up the database”

Decision Flow

ALWAYS check for existing databases FIRST before creating.

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

Check for Existing Databases

Before creating a database, check if one already exists.

For full environment config structure, see environment-config.md.

1railway status --json

Then query environment config and check source.image for each service:

1query environmentConfig($environmentId: String!) {
2  environment(id: $environmentId) {
3    config(decryptVariables: false)
4  }
5}

The config.services object contains each service’s configuration. Check source.image for:

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

Available Databases

Prerequisites

Get project context:

1railway status --json

Extract:

• id - project ID
• environments.edges[0].node.id - environment ID

Get workspace ID (not in status output):

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

Adding a Database

Step 1: Fetch Template

 1bash <<'SCRIPT'
 2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
 3  'query template($code: String!) {
 4    template(code: $code) {
 5      id
 6      name
 7      serializedConfig
 8    }
 9  }' \
10  '{"code": "postgres"}'
11SCRIPT

This returns the template’s id and serializedConfig needed for deployment.

Step 2: Deploy Template

 1bash <<'SCRIPT'
 2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
 3  'mutation deployTemplate($input: TemplateDeployV2Input!) {
 4    templateDeployV2(input: $input) {
 5      projectId
 6      workflowId
 7    }
 8  }' \
 9  '{
10    "input": {
11      "templateId": "TEMPLATE_ID",
12      "serializedConfig": SERIALIZED_CONFIG,
13      "projectId": "PROJECT_ID",
14      "environmentId": "ENVIRONMENT_ID",
15      "workspaceId": "WORKSPACE_ID"
16    }
17  }'
18SCRIPT

Important: serializedConfig is the exact object from the template query, not a string.

Connecting to the Database

After deployment, other services connect using reference variables.

For complete variable reference syntax and wiring patterns, see variables.md.

Backend Services (Server-side)

Use the private/internal URL for server-to-server communication:

Frontend Applications

Important: Frontends run in the user’s browser and cannot access Railway’s private network. They must use public URLs or go through a backend API.

For direct database access from frontend (not recommended):

• Use the public URL variables (e.g., ${{MongoDB.MONGO_PUBLIC_URL}})
• Requires TCP proxy to be enabled

Better pattern: Frontend → Backend API → Database

Example: Add PostgreSQL

 1bash <<'SCRIPT'
 2# 1. Get context
 3railway status --json
 4# Extract project.id and environment.id
 5
 6# 2. Get workspace ID
 7${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
 8  'query { project(id: "proj-id") { workspaceId } }' '{}'
 9
10# 3. Fetch Postgres template
11${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
12  'query { template(code: "postgres") { id serializedConfig } }' '{}'
13
14# 4. Deploy template
15${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
16  'mutation deploy($input: TemplateDeployV2Input!) {
17    templateDeployV2(input: $input) { projectId workflowId }
18  }' \
19  '{"input": {"templateId": "...", "serializedConfig": {...}, "projectId": "...", "environmentId": "...", "workspaceId": "..."}}'
20SCRIPT

Then Connect From Another Service

Use railway-environment skill to add the variable reference:

1{
2  "services": {
3    "<backend-service-id>": {
4      "variables": {
5        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
6      }
7    }
8  }
9}

Response

Successful deployment returns:

1{
2  "data": {
3    "templateDeployV2": {
4      "projectId": "e63baedb-e308-49e9-8c06-c25336f861c7",
5      "workflowId": "deployTemplate/project/e63baedb-e308-49e9-8c06-c25336f861c7/xxx"
6    }
7  }
8}

What Gets Created

Each database template creates:

• A service with the database image
• A volume for data persistence
• Environment variables for connection strings
• TCP proxy for external access (where applicable)

Error Handling

Example Workflows

“add postgres and connect to the server”

1. Check existing DBs via env config query
2. If postgres exists: Skip to step 5
3. If not exists: Deploy postgres template (fetch template → deploy)
4. Wait for deployment to complete
5. Identify target service (ask if multiple, or use linked service)
6. Use railway-environment skill to stage: DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }
7. Apply changes

“add postgres”

1. Check existing DBs via env config query
2. If exists: “Postgres already exists in this project”
3. If not exists: Deploy postgres template
4. Inform user: “Postgres created. Connect a service with: DATABASE_URL=${{Postgres.DATABASE_URL}}”

“connect the server to redis”

1. Check existing DBs via env config query
2. If redis exists: Wire up REDIS_URL via environment skill → apply
3. If no redis: Ask “No Redis found. Create one?”
   • Deploy redis template
   • Wire REDIS_URL → apply

Composability

• Connect services: Use railway-environment skill to add variable references
• View database service: Use railway-service skill
• Check logs: Use railway-deployment skill