Databases on Tawa

The Short Version

Declare databases in catalog-info.yaml. The builder provisions connection strings and injects them as environment variables. Your code reads from process.env. Identical across all environments.

spec:
  databases:
    - type: mongodb   # → MONGODB_URI
    - type: redis     # → REDIS_URL
    - type: neo4j     # → NEO4J_URI

Supported Types

Type	Env Variable	Notes
`mongodb`	`MONGODB_URI`	Recommended for most services
`redis`	`REDIS_URL`	Use for caching and queues
`neo4j`	`NEO4J_URI`	Use for graph data

Only these three types. postgres, mysql, sqlite will fail at tawa preflight.

Connecting

// MongoDB
import mongoose from 'mongoose'
const uri = process.env.MONGODB_URI
if (!uri) throw new Error('MONGODB_URI not configured')
await mongoose.connect(uri)

// Redis
import Redis from 'ioredis'
const url = process.env.REDIS_URL
if (!url) throw new Error('REDIS_URL not configured')
const redis = new Redis(url)

// Neo4j
import neo4j from 'neo4j-driver'
const uri = process.env.NEO4J_URI
if (!uri) throw new Error('NEO4J_URI not configured')
const driver = neo4j.driver(uri)

Database Naming

MongoDB databases are named {service}-{environment} by default:

Service	Env	Database
my-api	sandbox	my-api-sandbox
my-api	prod	my-api-prod

Override with a custom name:

spec:
  databases:
    - type: mongodb
      name: shared-data   # uses "shared-data" instead of "{service}-{env}"

Local Development

# .env.local
MONGODB_URI=mongodb://localhost:27017/my-api-dev
REDIS_URL=redis://localhost:6379/0
NEO4J_URI=bolt://localhost:7687

Or use tawa config pull to get the sandbox connection strings:

tawa config pull  # writes to .env.local

Vault (Dynamic Credentials)

MongoDB credentials are rotated automatically via HashiCorp Vault. The Vault Agent sidecar handles credential injection — your code reads MONGODB_URI as always, but the underlying credentials rotate without a redeploy.

Redis and Neo4j Vault rotation is pending (Phase 2c/2d).

Shared Databases (catalog 0.5.0+)

Services can share databases. The owning service declares sharedWith, the consumer declares consumesDatabase:

# Owning service (analytics-api):
spec:
  databases:
    - type: mongodb
      sharedWith: [reporting-service]

# Consuming service (reporting-service):
spec:
  consumesDatabase:
    - from: analytics-api
      type: mongodb   # → MONGODB_URI_ANALYTICS_API env var

What NOT to Do

# ❌ WRONG: unsupported types
spec:
  databases:
    - type: postgres   # fails at preflight
    - type: mysql      # fails at preflight

# ❌ WRONG: hardcoding connection strings
MONGODB_URI=mongodb://prod-host:27017/mydb  # in tawa config — let builder provision it

# ✅ CORRECT: declare in catalog, let builder provision
spec:
  databases:
    - type: mongodb

Last updated: February 28, 2026