Skip to content
dbward dbward dbward Docs

Quickstart: Try with Docker

Quickstart: Try with Docker

Section titled “Quickstart: Try with Docker”

See the full approval workflow: submit → approve → execute → audit.

Prerequisites: Docker, Docker Compose v2.

1. Start the stack

Section titled “1. Start the stack”
Terminal window
git clone https://github.com/dbward-dev/dbward.git && cd dbward/examples/quickstart
docker compose up -d

This starts:

  • PostgreSQL — target database
  • dbward-server — approval engine (port 13000)
  • dbward-agent — executes approved queries on PostgreSQL

Wait for healthy state (~15 seconds):

Terminal window
docker compose ps   # all should show "healthy"

2. Run a query (auto-approved)

Section titled “2. Run a query (auto-approved)”

The development environment has no approval steps — queries execute immediately:

Terminal window
docker compose run --rm alice execute "SELECT version()" -e development
 version
──────────────────────────────────────
 PostgreSQL 17.2 on x86_64-pc-linux...
(1 row)


Completed in 52ms

That’s the 30-second check. dbward is working. Alice (developer) submitted a query, the agent executed it on PostgreSQL, and the result came back.

3. Submit a query that needs approval

Section titled “3. Submit a query that needs approval”

Now target staging — this environment requires admin approval:

Terminal window
docker compose run --rm alice execute "SELECT current_timestamp" -e staging
Request e5f6g7h8-... requires approval.
  Approvers: role:admin
Run: dbward request resume e5f6g7h8-...

The request is pending — it won’t execute until an admin approves.

4. Approve (as bob)

Section titled “4. Approve (as bob)”

Copy the request ID from step 3:

Terminal window
docker compose run --rm bob request approve e5f6g7h8 --comment "LGTM"
Approved step 1/1
Request e5f6g7h8 — all steps complete.

5. Get the result (as alice)

Section titled “5. Get the result (as alice)”
Terminal window
docker compose run --rm alice request resume e5f6g7h8
 current_timestamp
──────────────────────────────────
 2026-06-08 08:15:23.456789+00
(1 row)


Completed in 38ms

The agent executed the query on PostgreSQL after approval.

6. Check the audit trail

Section titled “6. Check the audit trail”
Terminal window
docker compose run --rm bob audit --limit 4
ID         TIMESTAMP              USER        EVENT              ENV      DATABASE  OUTCOME
96af1a07   2026-06-08T08:15:23    agent       request_executed   staging  app       success
d3e4f5a6   2026-06-08T08:15:22    developer   request_dispatched staging  app       success
c646583f   2026-06-08T08:15:20    admin       request_approved   staging  app       success
8f8c35a4   2026-06-08T08:15:16    developer   request_created    staging  app       success

Every action is recorded. Verify the tamper-evident hash chain:

Terminal window
docker compose run --rm bob audit --verify
✓ Hash chain intact (6 events verified)

7. Stop

Section titled “7. Stop”
Terminal window
docker compose down -v

What just happened?

Section titled “What just happened?”
alice (developer)          bob (admin)              agent
     │                          │                      │
     ├─ execute (staging) ─────►│                      │
     │  "pending approval"      │                      │
     │                          │                      │
     │                          ├─ approve ───────────►│
     │                          │                      │
     ├─ resume ────────────────►│  dispatch ──────────►│
     │                          │                      ├─ execute on DB
     │  "current_timestamp"  ◄──│◄─────── result ──────┤
     │                          │                      │
     └──────── audit trail records everything ─────────┘

Why did staging need approval?

Section titled “Why did staging need approval?”

The server config (server.toml) defines the rules:

# Development: no approval needed
[[workflows]]
environment = "development"
steps = []


# Staging: 1 admin must approve
[[workflows]]
environment = "staging"


[[workflows.steps]]
type = "approval"


[[workflows.steps.approvers]]
role = "admin"
min = 1

Change the config, change the rules.

How does alice/bob work?

Section titled “How does alice/bob work?”

The compose file has two CLI containers with different tokens:

  • alice uses developer-token (can submit queries)
  • bob uses admin-token (can approve requests)

Both read their token from files that the server creates on first startup.

Troubleshooting

Section titled “Troubleshooting”

docker compose ps shows “unhealthy”:

Terminal window
docker compose logs server  # check for startup errors

Most common: the server needs a few more seconds. Wait and retry.

“requires approval” but you can’t approve: You’re using alice (developer). Switch to bob (admin):

Terminal window
docker compose run --rm bob request approve <ID>

Result shows “waiting for agent”: The agent needs 1-2 seconds to poll and execute. Wait a moment, then run request resume again.

See also

Section titled “See also”