Database Provisioning

About

How databases are declared in catalog-info.yaml and automatically provisioned by the builder. Covers all three supported types (mongodb, redis, neo4j), naming conventions, connection string formats, environment variable mapping, code examples for each driver, and local development setup.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# Database Provisioning

## What this skill covers
How databases are declared, provisioned, and connected on the Tawa platform.

## How It Works

1. Declare databases in `catalog-info.yaml` under `spec.databases`
2. On deploy, the builder generates connection strings and creates K8s secrets
3. Environment variables are injected into your pod automatically
4. Your app reads from `process.env` — identical code across all environments

## Supported Types

| Type | Env Variable | Connection Format |
|------|-------------|-------------------|
| `mongodb` | `MONGODB_URI` | `mongodb://{host}:27017/{service}-{env}` |
| `redis` | `REDIS_URL` | `redis://{host}:6379/0` |
| `neo4j` | `NEO4J_URI` | `bolt://{host}:7687` |

Only these three types are supported. Using `postgres`, `mysql`, or any other type will fail during `tawa preflight`.

## YAML Configuration

```yaml
spec:
  databases:
    - type: mongodb          # Creates MONGODB_URI
    - type: redis            # Creates REDIS_URL
    - type: neo4j            # Creates NEO4J_URI
```

### Custom MongoDB Name

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

## Database Naming

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

| Service | Environment | Database Name |
|---------|-------------|---------------|
| my-api | sandbox | my-api-sandbox |
| my-api | prod | my-api-prod |
| my-api | uat | my-api-uat |

## Connecting from Your App

### MongoDB (Mongoose)
```typescript
import mongoose from 'mongoose'

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

### Redis (ioredis)
```typescript
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
```typescript
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)
```

## Local Development

Set env vars in `.env` for local dev:
```
MONGODB_URI=mongodb://localhost:27017/my-api-dev
REDIS_URL=redis://localhost:6379/0
NEO4J_URI=bolt://localhost:7687
```

## Key Facts
- The platform creates the connection string, not the database itself
- MongoDB auto-creates databases on first write
- Redis and Neo4j are shared instances — use key prefixes in Redis
- Each environment gets its own K8s secret with different connection strings
- Redeploying does NOT touch your data — databases are persistent
- Adding a database to an existing service: just add it to catalog-info.yaml and redeploy

Install

Copy the skill content and save it to:

~/.claude/rules/database-provisioning.md

Details

Format

Rule

Category

provision

Version

1.0.0

Tokens

~900

Updated

2026-02-13