database syncer

Dockers/database-syncer/README.md

@@ -0,0 +1,72 @@
+# database-syncer
+
+PostgreSQL sync van **source → destination** op een **CRON**-schema.
+
+De source-database wordt **nooit** aangepast: alleen `pg_dump` (reads/SELECT), met
+`default_transaction_read_only=on` op de source-connectie.
+
+## Environment variables
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `SOURCE_DB_URL` | PostgreSQL URL van de bron (alleen gelezen) |
+| `DEST_DB_URL` | PostgreSQL URL van de bestemming (wordt overschreven) |
+| `CRON` | 5-veld cron-expressie (bijv. `0 3 * * *`) of macro (`@hourly`, `@daily`, ...) |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TZ` | `Europe/Brussels` | Tijdzone |
+| `ON_STARTUP` | `true` | Direct syncen bij opstart (`true`/`false`) |
+
+URL-formaat: `postgresql://user:password@host:5432/dbname`
+
+## Gedrag
+
+1. Dump van source via `pg_dump` (custom format, read-only).
+2. Restore naar destination via `pg_restore --clean --if-exists` (bestaande objecten op dest worden vervangen).
+3. Herhaalt volgens `CRON`.
+
+**Let op:** de destination wordt bij elke sync opgeschoond (DROP + recreate van objecten). Gebruik hiervoor een dedicated shadow/replica-database, niet productie met unieke data.
+
+## Source read-only garantie
+
+- Enkel `pg_dump` praat met de source (geen `psql` writes, geen restore).
+- `PGOPTIONS=-c default_transaction_read_only=on` op de source-connectie.
+- Aanbevolen: geef de source-credentials een **read-only** PostgreSQL-rol.
+
+## Voorbeeld
+
+```bash
+docker run -d \
+  -e SOURCE_DB_URL='postgresql://ro:secret@source:5432/prod' \
+  -e DEST_DB_URL='postgresql://rw:secret@dest:5432/shadow' \
+  -e 'CRON=0 3 * * *' \
+  -e TZ=Europe/Brussels \
+  --name database-syncer \
+  bramkel/database-syncer:latest
+```
+
+## Compose
+
+```yaml
+  database-syncer:
+    image: bramkel/database-syncer:latest
+    container_name: database-syncer
+    restart: unless-stopped
+    environment:
+      - TZ=Europe/Brussels
+      - SOURCE_DB_URL=postgresql://ro:secret@source:5432/prod
+      - DEST_DB_URL=postgresql://rw:secret@dest:5432/shadow
+      - 'CRON=0 3 * * *'
+      - ON_STARTUP=true
+```
+
+## Build
+
+```bash
+docker build -t bramkel/database-syncer:latest .
+```