Coding agents are often evaluated in a clean repository with mocked services. Production work is rarely that polite. A useful agent has to inspect schemas, reproduce query behavior, run migrations and recover when a tool call stops halfway through.
The difficult part is not giving an agent database credentials. It is designing an environment where a mistake is bounded and a retry is meaningful.
The real requirement
The requirement is realistic state with cheap recovery. Realistic state means the database behaves like the system under investigation: the same engine, extensions, constraints and meaningful data distributions. Cheap recovery means no individual run owns an irreplaceable environment.
Those two properties pull in opposite directions. A shared development database is realistic but unsafe. A blank local database is isolated but may hide the exact plan or migration behavior that matters.
An environment contract
Treat the environment as a resource with an explicit contract rather than an address in an environment variable.
| Property | Question the platform must answer |
|---|---|
| Identity | Which run and repository revision owns it? |
| Provenance | Which schema and snapshot created it? |
| Capability | Can the run migrate, write, truncate or only read? |
| Lifetime | What event destroys or refreshes it? |
| Evidence | Where do query plans, logs and migration results go? |
That contract belongs in machine-readable state. A worker should be able to resume after compaction or process failure without reconstructing ownership from a chat transcript.
type DatabaseLease = {
runId: string
revision: string
databaseUrlSecretRef: string
snapshotId: string
capabilities: Array<'read' | 'write' | 'migrate'>
expiresAt: string
}The URL is deliberately represented by a secret reference. Checkpoints should preserve identity and authority, not copy credentials into durable logs.
Make state disposable
Disposability changes how the agent can work. It can run a migration, compare plans before and after an index, or test a destructive cleanup because the platform owns a known reset path.
The reset path must be deterministic:
- Pin the repository revision and schema inputs.
- Restore the same sanitized snapshot.
- Apply the same ordered migrations.
- Record the resulting schema fingerprint.
- Expose credentials only to the run-scoped worker.
If any step is implicit, a retry may produce a different environment while appearing successful. That is worse than a visible failure.
Measure the recovery path
Teams naturally measure provisioning latency. Recovery deserves the same attention. Track the time from a failed step to a verified, equivalent environment and the percentage of runs that can resume from their last durable checkpoint.
Useful operational signals include:
- clone and restore duration by snapshot size;
- migration duration and failure stage;
- environment leaks after run termination;
- schema fingerprint mismatches;
- successful resume rate after worker interruption.
The larger lesson is that agent reliability is an infrastructure property. Better prompts help a model choose safer actions, but only isolation, provenance and recovery keep one imperfect action from becoming an incident.