Database role
Maps a request to SQL creation and revocation statements.
Chapter contract
Prerequisites:
Chapter 7 complete, PostgreSQL healthy, and the learner token available.
User-visible outcome:
orders-api can query PostgreSQL with a unique leased principal and prove revocation on a new connection.
Learning objectives
- Request credentials without printing them.
- Run a real query and retain only safe lease metadata.
- Handle pool replacement, renewal failure, and revocation.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
Dynamic user
A unique principal generated for one lease.
Pool rotation
Build a replacement pool before draining old connections.
Root rotation
Change the privileged credential Vault uses to manage principals.
Commands and configuration
source learn-vault/.runtime/learner.env
cd learn-vault/labs/dynamic-db
./request-and-query.sh
jq '{lease_id_present:(.lease_id|length>0),lease_duration,renewable}' ../../.runtime/db-lease.json
./revoke.shSecret-safety stop
Stop: Do not pass generated passwords as command arguments. The lab injects them transiently inside the database container and never echoes them.
Failure drill
| Symptom | Fresh credentials work, then the application gets password failures. |
|---|---|
| Likely causes | Lease expired, renewal failed, clock margin too small, or pool retained revoked principals. |
| Inspect safely | Check lease age, renew result, pool generation, SQLSTATE class, and Vault health. |
| Do not print | Generated username, password, DSN, SQL environment, or lease response. |
Break it / fix it
Break it: Revoke the dynamic DB lease before opening a new connection.
Show diagnosis and fix
Fix it: Acquire a new lease, validate a replacement pool, then drain the old generation.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Request a lease, run SELECT current_database(), revoke it, then prove a new connection fails.
cd learn-vault/labs/dynamic-db
./request-and-query.sh
jq -e '.lease_duration>0 and (.lease_id|length>0)' ../../.runtime/db-lease.json
./revoke.sh
./verify-revoked.sh
./cleanup.shSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- The query reports only the expected database name.
- Lease metadata is finite and renewable.
- A new connection for the revoked principal is rejected.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Revoke before deleting the response. Cleanup does both when a lease ID exists.
Project Lockbox increment
orders-api no longer owns a shared DB password; readiness tracks lease margin and pool generation.
Quick check
Why is a unique user useful?
It improves attribution and permits per-workload revocation.
Wait for expiry before replacing a pool?
No. Validate a new pool with margin, then drain the old one.
What may survive revocation briefly?
An already-established DB session.
Who reviews SQL grants?
The database owner; Vault policy cannot define database privilege.
Gotchas
- The plugin account is itself a rotation responsibility.
- Connection max lifetime should be shorter than credential usability.
- Revocation SQL must tolerate retry and partial cleanup.
Recap and next
Dynamic DB credentials reduce sharing, but applications must rotate pools before the lease clock wins.