Database Backups on Tawa

About

Every MongoDB database on the platform is backed up automatically every night, and you can take an on-demand backup of your own service's database any time. Backups are stored in platform object storage (MinIO) with grandfather-father-son retention. Nothing to declare in `catalog-info.yaml` — backups are on by default.

Skill Content

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

# Database Backups on Tawa

## The Short Version

Every MongoDB database on the platform is backed up automatically every night, and you can take an on-demand backup of your own service's database any time. Backups are stored in platform object storage (MinIO) with grandfather-father-son retention. Nothing to declare in `catalog-info.yaml` — backups are on by default.

```bash
tawa db backup my-api --prod        # take a backup now
tawa db backups my-api --prod       # list backups
tawa db backup-download my-api <id> # get a temporary download link
tawa db restore my-api <id> --confirm   # restore (admin, destructive)
```

## Automatic Nightly Backups

The builder runs a platform-wide backup every night (02:00 UTC by default). For each database it runs `mongodump --archive --gzip` and uploads the archive to the `tawa-db-backups` bucket.

Each nightly run is tagged with a retention tier (grandfather-father-son):

| Day | Tier | Kept |
|-----|------|------|
| 1st of month | `monthly` | 3 |
| Sunday | `weekly` | 4 |
| Any other day | `daily` | 7 |

Older automated backups beyond the keep count are pruned automatically. **Manual backups are never auto-pruned** — you delete those yourself.

## On-Demand (Self-Service) Backups

Take a backup of your own service's database whenever you want — before a risky migration, a data fix, or a release.

```bash
tawa db backup my-api --prod
```

This dumps your service's MongoDB database, uploads it, and records it. Requires the `member` org role on the service's org.

### Listing

```bash
tawa db backups my-api --prod
```

Shows both your manual backups and the nightly automated ones for your database, newest first, with size, tier, who took it, and status.

### Downloading

```bash
tawa db backup-download my-api <backup-id> --prod
```

Returns a short-lived (15-minute) presigned URL to the gzipped archive. The archive is a standard `mongodump --archive --gzip` file — restore it anywhere with `mongorestore --archive=<file> --gzip`.

## Restore

Restore is **destructive**: it runs `mongorestore --drop`, which drops the target collections and replaces them from the backup. It is scoped to the original database only (`--nsInclude`), so no other database is ever touched.

```bash
tawa db restore my-api <backup-id> --confirm
```

Requires the `admin` org role **and** the explicit `--confirm` flag. Without `--confirm` the request is rejected.

## API Endpoints

Self-service backups are exposed by the builder, mirroring the `tawa db connect` whitelist model:

| Method | Endpoint | Role | Purpose |
|--------|----------|------|---------|
| `POST` | `/services/:name/databases/backup` | member | Take an on-demand backup |
| `GET` | `/services/:name/databases/backups` | viewer | List backups (manual + auto) |
| `GET` | `/services/:name/databases/backups/:id/download` | member | Presigned download URL |
| `POST` | `/services/:name/databases/restore` | admin | Restore (`{ "backupId": "...", "confirm": true }`) |
| `GET` | `/databases/backups` | platform admin | List all backups across orgs |

## Where Backups Live

Backups are stored in the platform MinIO object store, bucket `tawa-db-backups`, keyed:

```
{env}/{service}/{tier}/{db}-{timestamp}.archive.gz
```

> **Disaster-recovery note:** MinIO currently runs on the same server as MongoDB. An off-server replication of the backup bucket (to DigitalOcean Spaces) is the true DR layer — see the platform runbook. Same-box backups protect against accidental data loss and bad migrations, not against total host loss.

## Configuration (Platform Operators)

Controlled by builder environment variables (defaults shown):

| Var | Default | Purpose |
|-----|---------|---------|
| `BACKUP_ENABLED` | `true` | Master switch for the nightly scheduler |
| `BACKUP_BUCKET` | `tawa-db-backups` | MinIO bucket |
| `BACKUP_CRON_HOUR_UTC` | `2` | Nightly run hour (UTC) |
| `BACKUP_RETENTION_DAILY` | `7` | Daily backups kept |
| `BACKUP_RETENTION_WEEKLY` | `4` | Weekly backups kept |
| `BACKUP_RETENTION_MONTHLY` | `3` | Monthly backups kept |
| `BACKUP_DOWNLOAD_TTL_SECONDS` | `900` | Presigned download URL lifetime |
| `BACKUP_TMP_DIR` | `/tmp/iec-backup` | Scratch dir for archives |

Backups require `DB_MONGODB_ADMIN_URI` (admin Mongo access) and MinIO admin credentials in Vault KV (`secret/minio/admin`). If `DB_MONGODB_ADMIN_URI` is unset, the scheduler logs a warning and stays idle.

## What NOT to Do

```bash
# ❌ WRONG: restore without --confirm — rejected (destructive guard)
tawa db restore my-api <id>

# ❌ WRONG: assuming same-box MinIO is full disaster recovery
#    It protects against bad data, not host loss. Off-box replication is separate.

# ✅ CORRECT: snapshot before a risky migration, then restore if it goes wrong
tawa db backup my-api --prod
# ... run migration ...
tawa db restore my-api <id> --confirm   # only if needed
```

Install

Copy the skill content and save it to:

~/.claude/rules/tawa-database-backups.md

Details

Format

Rule

Category

provision

Version

1.0.83316

Tokens

~1,219

Updated

2026-06-24