Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

FEATURE (tooling): Start the test fixtures and the WAL backup rig with just run, so local development has every database it uses

Rostislav Duginacda94a1d34f
diff --git a/AGENTS.md b/AGENTS.md
index 40ea301e..cea6d17d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,7 +32,7 @@ Work happens on a Fedora host; any other host distro is on its own. Tool version
| Command | Purpose |
|---|---|
-| `just run` | Start the app locally: dev database, backend and frontend |
+| `just run` | Start the app locally: dev database, test fixtures, WAL backup source with its load generator, backend and frontend |
| `just test` | Run the full backend suite |
| `just test-filesystem` | Run the Docker filesystem suite, mostly left to CI |
| `just pull-testcontainers` | Pull the database images the backend tests use |
diff --git a/backend/README.md b/backend/README.md
index fa0c34e4..b164cd35 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -6,7 +6,7 @@
Commands run from the repository root, with the tools from `mise.toml` installed.
-To run the backend together with the frontend and the dev database:
+To run the backend together with the frontend, the dev database, the test fixtures and the WAL backup source:
> just run
diff --git a/openspec/specs/local-development-workflow/spec.md b/openspec/specs/local-development-workflow/spec.md
index dd5054b7..0aaa1c91 100644
--- a/openspec/specs/local-development-workflow/spec.md
+++ b/openspec/specs/local-development-workflow/spec.md
@@ -7,13 +7,13 @@ Defines the commands a developer or an agent uses on a local Fedora host to run
### Requirement: One command starts the local app
-The repository SHALL provide `just run` at its root. It SHALL start the development database, the backend and the frontend development server, and SHALL show them in one terminal window that lists every process separately, with each process's output available on its own. It SHALL work in a fresh worktree that has a `.env` file but has never generated the backend's API documentation or installed frontend dependencies. When a backend from an earlier run still holds the backend port, the command SHALL stop that process before starting the new backend, so that requests reach the code just started.
+The repository SHALL provide `just run` at its root. It SHALL start the development database, the shared backend test fixtures, the live WAL backup source with its load generator, the backend and the frontend development server, and SHALL show the database, the load generator, the backend and the frontend in one terminal window that lists every process separately, with each process's output available on its own. It SHALL work in a fresh worktree that has a `.env` file but has never generated the backend's API documentation or installed frontend dependencies. When a backend from an earlier run still holds the backend port, the command SHALL stop that process before starting the new backend, so that requests reach the code just started.
#### Scenario: Developer starts the app
- **WHEN** a developer runs `just run` on a Fedora host with a `.env` file
-- **THEN** the development database, the backend and the frontend start
-- **AND** the window lists each of them as a separate process with its own output
+- **THEN** the development database, the shared test fixtures, the WAL backup source, its load generator, the backend and the frontend start
+- **AND** the window lists the database, the load generator, the backend and the frontend as separate processes with their own output
#### Scenario: Fresh worktree
@@ -28,13 +28,13 @@ The repository SHALL provide `just run` at its root. It SHALL start the developm
### Requirement: Interrupting the local app stops what it started
-When a developer interrupts `just run` with Ctrl+C, the backend and the frontend development server SHALL exit and the development database container SHALL stop. The database container SHALL be stopped rather than removed, so its data survives into the next run. Containers the command did not start, including the shared backend test fixtures, SHALL keep running.
+When a developer interrupts `just run` with Ctrl+C, the backend and the frontend development server SHALL exit, and the development database, the WAL backup source and its load generator SHALL stop. These containers SHALL be stopped rather than removed, so the database's data survives into the next run. The shared backend test fixtures SHALL keep running, because the backend suite and other worktrees use them.
#### Scenario: Developer presses Ctrl+C
- **WHEN** a developer presses Ctrl+C in the `just run` window
- **THEN** no backend or frontend process from that run remains
-- **AND** the development database container is stopped
+- **AND** the development database, the WAL backup source and its load generator are stopped
#### Scenario: Data survives a restart
@@ -43,8 +43,8 @@ When a developer interrupts `just run` with Ctrl+C, the backend and the frontend
#### Scenario: Test fixtures are running
-- **WHEN** the shared backend test fixtures are running and a developer interrupts `just run`
-- **THEN** the test fixtures are still running afterwards
+- **WHEN** a developer interrupts `just run`
+- **THEN** the shared test fixtures it started are still running afterwards
### Requirement: One command runs the full backend suite
diff --git a/process-compose.yaml b/process-compose.yaml
index 26690bd5..a6297667 100644
--- a/process-compose.yaml
+++ b/process-compose.yaml
@@ -16,3 +16,6 @@ processes:
db:
command: docker compose -f docker-compose.yml logs --follow --no-log-prefix backend-db
+
+ wal-loader:
+ command: docker compose -f docker-compose.yml logs --follow --no-log-prefix wal-backup-loader
diff --git a/scripts/dev.sh b/scripts/dev.sh
index 6a287779..8fb08061 100755
--- a/scripts/dev.sh
+++ b/scripts/dev.sh
@@ -5,11 +5,13 @@ root=$(cd "$(dirname "$0")/.." && pwd)
source "$root/scripts/fedora.sh"
readonly backend_port=4005
+readonly test_fixtures=(test-logical-postgres-16 test-physical-postgres-17 test-physical-postgres-18)
+readonly own_services=(backend-db wal-backup-postgres-18 wal-backup-loader)
-# `stop`, not `down`: the compose file also holds the test fixtures other worktrees share, and the
-# dev database keeps its data in an anonymous volume that `down` would drop.
-stop_database() {
- docker compose -f "$root/docker-compose.yml" stop backend-db
+# `stop`, not `down`: the dev database keeps its data in an anonymous volume that `down` would drop.
+# The test fixtures stay up, because the backend suite and other worktrees share them.
+stop_services() {
+ docker compose -f "$root/docker-compose.yml" stop "${own_services[@]}"
}
# A stale backend keeps holding the port and answers with the previously built code; a new one that
@@ -35,8 +37,8 @@ free_backend_port() {
apply_libedit_shim
-trap stop_database EXIT
-docker compose -f "$root/docker-compose.yml" up -d backend-db
+trap stop_services EXIT
+docker compose -f "$root/docker-compose.yml" up -d "${own_services[@]}" "${test_fixtures[@]}"
timeout 60 bash -c 'until docker exec backend-db pg_isready -U postgres >/dev/null; do sleep 2; done'
(cd "$root/backend" && swag init -d . -g cmd/main.go -o swagger --quiet)