Database
Add official Railway database services. These are maintained templates with pre-configured volumes, networking, and connection variables.
For non-database templates, see the 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.
railway status --json
Then query environment config and check source.image for each service:
query environmentConfig($environmentId: String!) {
environment(id: $environmentId) {
config(decryptVariables: false)
}
}
The config.services object contains each service's configuration. Check source.image for:
ghcr.io/railway/postgres* or postgres:* → Postgresghcr.io/railway/redis* or redis:* → Redisghcr.io/railway/mysql* or mysql:* → MySQLghcr.io/railway/mongo* or mongo:* → MongoDB
Available Databases
| Database |
Template Code |
| PostgreSQL |
postgres |
| Redis |
redis |
| MySQL |
mysql |
| MongoDB |
mongodb |
Prerequisites
Get project context:
railway status --json
Extract:
id - project IDenvironments.edges[0].node.id - environment ID
Get workspace ID (not in status output):
bash <<'SCRIPT'
scripts/railway-api.sh \
'query getWorkspace($projectId: String!) {
project(id: $projectId) { workspaceId }
}' \
'{"projectId": "PROJECT_ID"}'
SCRIPT
Adding a Database
Step 1: Fetch Template
bash <<'SCRIPT'
scripts/railway-api.sh \
'query template($code: String!) {
template(code: $code) {
id
name
serializedConfig
}
}' \
'{"code": "postgres"}'
SCRIPT
This returns the template's id and serializedConfig needed for deployment.
Step 2: Deploy Template
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
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:
| Database |
Variable Reference |
| PostgreSQL |
${{Postgres.DATABASE_URL}} |
| Redis |
${{Redis.REDIS_URL}} |
| MySQL |
${{MySQL.MYSQL_URL}} |
| MongoDB |
${{MongoDB.MONGO_URL}} |
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
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
Then Connect From Another Service
Use environment skill to add the variable reference:
{
"services": {
"<backend-service-id>": {
"variables": {
"DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
}
}
}
}
Response
Successful deployment returns:
{
"data": {
"templateDeployV2": {
"projectId": "e63baedb-e308-49e9-8c06-c25336f861c7",
"workflowId": "deployTemplate/project/e63baedb-e308-49e9-8c06-c25336f861c7/xxx"
}
}
}
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
| Error |
Cause |
Solution |
| Template not found |
Invalid template code |
Use: postgres, redis, mysql, mongodb |
| Permission denied |
User lacks access |
Need DEVELOPER role or higher |
| Project not found |
Invalid project ID |
Run railway status --json for correct ID |
Example Workflows
"add postgres and connect to the server"
- Check existing DBs via env config query
- If postgres exists: Skip to step 5
- If not exists: Deploy postgres template (fetch template → deploy)
- Wait for deployment to complete
- Identify target service (ask if multiple, or use linked service)
- Use
environment skill to stage: DATABASE_URL: { "value": "${{Postgres.DATABASE_URL}}" }
- Apply changes
"add postgres"
- Check existing DBs via env config query
- If exists: "Postgres already exists in this project"
- If not exists: Deploy postgres template
- Inform user: "Postgres created. Connect a service with:
DATABASE_URL=${{Postgres.DATABASE_URL}}"
"connect the server to redis"
- Check existing DBs via env config query
- If redis exists: Wire up REDIS_URL via environment skill → apply
- If no redis: Ask "No Redis found. Create one?"
- Deploy redis template
- Wire REDIS_URL → apply
Composability
- Connect services: Use
environment skill to add variable references
- View database service: Use
service skill
- Check logs: Use
deployment skill
