# pg-ephemeral - Ephemeral PostgreSQL for Testing
> **Status**: Pre-1.0 - exists to serve [mbj/mrs](https://github.com/mbj/mrs) monorepo, expect breaking changes without notice.
Spin up throwaway PostgreSQL containers for development and testing. Supports Docker and
Podman with automatic backend detection.
## Quick Start
```sh
# Launch psql against an ephemeral database (default command)
pg-ephemeral
# Run a command with PG* environment variables set
pg-ephemeral run-env -- pytest
# Run an interactive shell on the container
pg-ephemeral container-shell
```
Without a config file pg-ephemeral creates a single `main` instance using the latest
supported PostgreSQL image on the auto-detected container backend.
## Configuration
Place a `database.toml` in the working directory (or pass `--config-file <path>`).
File paths in the config are resolved relative to the config file's location, not the
process working directory. This means tests can be run from any subdirectory without
changing the paths in `database.toml`.
```toml
image = "17.1"
[instances.main.seeds.a-schema]
type = "sql-file"
path = "schema.sql"
[instances.main.seeds.b-data]
type = "script"
script = "psql -c \"INSERT INTO users (name) VALUES ('alice'), ('bob')\""
[instances.main.seeds.c-indexes]
type = "sql-file"
path = "indexes.sql"
[instances.main.seeds.d-dynamic]
type = "command"
command = "sh"
arguments = ["-c", "psql -c \"INSERT INTO users (name) VALUES ('dynamic-$RANDOM')\""]
cache = { type = "none" }
```
### Top-level fields
| `image` | PostgreSQL version / image tag (e.g. `"17.1"`) |
| `backend` | `"docker"`, `"podman"`, or omit for auto-detection |
| `ssl_config` | SSL configuration with `hostname` field |
| `wait_available_timeout` | How long to wait for PostgreSQL to accept connections (e.g. `"30s"`) |
### Seed types
Seeds run in declaration order inside the container. Each seed has a `type`:
| `sql-file` | `path`, optional `git_revision` | Apply a SQL file. With `git_revision`, reads the file from that git commit. `path` is resolved relative to the config file's directory. |
| `script` | `script` | Run a shell script with `sh -e -c`. |
| `command` | `command`, `arguments`, `cache` | Run an arbitrary command. If `command` is a relative path (contains `/`), it is resolved relative to the config file's directory; bare names like `psql` are looked up via `PATH`. |
### Multiple instances
Define multiple named instances under `[instances.<name>]`. Top-level fields serve as
defaults for all instances. Use `--instance <name>` on the CLI to target a specific one.
## Seed Caching
pg-ephemeral caches seed results as container images so repeated runs skip already-applied
seeds. Each seed's cache key is a SHA-256 chain of:
- pg-ephemeral version
- base image
- SSL configuration
- all preceding seeds' content
When the cache key matches an existing image the seed is a **hit** and the container boots
from that image directly. Seeds are cached in order; an uncacheable seed (e.g.
`cache = { type = "none" }`) breaks the chain and all subsequent seeds run without caching.
### Cache commands
```sh
# Show cache status for all seeds
pg-ephemeral cache status
# JSON output with full details (references, etc.)
pg-ephemeral cache status --json
# Pre-populate the cache without running an interactive session
pg-ephemeral cache populate
# Remove cached images
pg-ephemeral cache reset
# Force-remove cached images (even if referenced by stopped containers)
pg-ephemeral cache reset --force
```
### Command cache strategies
For `command` type seeds, the `cache` field controls how the cache key is computed:
| `{ type = "command-hash" }` | Hash the command and arguments (default). |
| `{ type = "key-command", command = "...", arguments = [...] }` | Run a separate command whose stdout is hashed as the cache key. |
| `{ type = "key-script", script = "..." }` | Run a script whose stdout is hashed as the cache key. |
| `{ type = "none" }` | Disable caching. Breaks the cache chain for this and all subsequent seeds. |
## Rust Library
pg-ephemeral can be used as a Rust library for integration tests or any code that needs
a throwaway PostgreSQL instance.
### Basic usage
```rust,no_run
async fn example() {
let backend = ociman::backend::resolve::auto().await.unwrap();
let definition = pg_ephemeral::Definition::new(
backend,
pg_ephemeral::Image::default(),
"test".parse().unwrap(),
)
.apply_file(
"schema".parse().unwrap(),
"schema.sql".into(),
)
.unwrap()
.apply_script(
"seed-data".parse().unwrap(),
r#"psql -c "INSERT INTO users (name) VALUES ('alice')""#,
)
.unwrap();
definition
.with_container(async |container| {
container
.with_connection(async |conn| {
let row: (i64,) = sqlx::query_as("SELECT count(*) FROM users")
.fetch_one(&mut *conn)
.await
.unwrap();
assert_eq!(row.0, 1);
})
.await;
})
.await
.unwrap();
}
```
`with_container` handles the full lifecycle: populate the seed cache, boot a container
(from the latest cache hit if available), apply any remaining uncached seeds, run the
closure, and stop the container.
### Seed types
Seeds are added to a `Definition` via builder methods:
```rust,no_run
# async fn example() {
# let backend = ociman::backend::resolve::auto().await.unwrap();
let definition = pg_ephemeral::Definition::new(
backend,
pg_ephemeral::Image::default(),
"test".parse().unwrap(),
)
// Apply a SQL file from disk
.apply_file("schema".parse().unwrap(), "schema.sql".into())
.unwrap()
// Apply a SQL file from a specific git revision
.apply_file_from_git_revision(
"baseline".parse().unwrap(),
"schema.sql".into(),
"abc1234",
)
.unwrap()
// Run an inline shell script
.apply_script(
"seed-data".parse().unwrap(),
r#"psql -c "INSERT INTO users (name) VALUES ('alice')""#,
)
.unwrap()
// Run an arbitrary command with explicit cache strategy
.apply_command(
"migrations".parse().unwrap(),
pg_ephemeral::Command::new("migrate", ["up"]),
pg_ephemeral::CommandCacheConfig::CommandHash,
)
.unwrap();
# }
```
### Configuration
The `Definition` builder supports additional options:
```rust,no_run
# async fn example() {
# let backend = ociman::backend::resolve::auto().await.unwrap();
let definition = pg_ephemeral::Definition::new(
backend,
"17.1".parse().unwrap(),
"test".parse().unwrap(),
)
// Extend the timeout for slow CI environments
.wait_available_timeout(std::time::Duration::from_secs(30))
// Enable cross-container access (for testing from other containers)
.cross_container_access(true)
// Enable SSL with a generated certificate
.ssl_config(pg_ephemeral::definition::SslConfig::Generated {
hostname: "localhost".parse().unwrap(),
});
# }
```
### Accessing connection details
Inside `with_container`, the `Container` provides several ways to connect:
```rust,no_run
# async fn example() {
# let backend = ociman::backend::resolve::auto().await.unwrap();
# let definition = pg_ephemeral::Definition::new(
# backend, pg_ephemeral::Image::default(), "test".parse().unwrap(),
# );
definition
.with_container(async |container| {
// Direct sqlx connection
container
.with_connection(async |conn| {
sqlx::query("SELECT 1").execute(&mut *conn).await.unwrap();
})
.await;
// Get pg_client::Config for custom connection setup
let _config = container.client_config();
// Get libpq-style environment variables (PGHOST, PGPORT, etc.)
let _env = container.pg_env();
// Get DATABASE_URL string
let _url = container.database_url();
})
.await
.unwrap();
# }
```
## Language Integrations
### Ruby
The `pg-ephemeral` Ruby gem bundles the binary and provides a native API:
```ruby
# Yields a PG::Connection to an ephemeral database
PgEphemeral.with_connection do |conn|
conn.exec("SELECT 1")
end
# Or get the server URL for manual connection management
PgEphemeral.with_server do |server|
puts server.url # => "postgres://postgres:...@127.0.0.1:54321/postgres"
end
```
The gem is available for `x86_64-linux`, `aarch64-linux`, and `arm64-darwin`.
See [integrations/ruby](integrations/ruby/) for details.
### Other Languages
Any language can integrate via `run-env` or the integration server protocol:
**Environment variables** — run a command with `PG*` and `DATABASE_URL` set:
```sh
pg-ephemeral run-env -- python manage.py test
pg-ephemeral run-env -- npx prisma migrate deploy
```
**Integration server** — for programmatic control over the container lifecycle:
```sh
pg-ephemeral integration-server --result-fd 3 --control-fd 4
```
Boots a container, writes a JSON line with connection details to the result pipe FD,
then waits for EOF on the control pipe FD before shutting down. The parent process
creates the pipes and passes the inherited file descriptors. Close the control pipe
write end to stop the server.
## CLI Reference
```
pg-ephemeral [OPTIONS] [COMMAND]
Commands:
psql Run interactive psql on the host (default)
run-env Run a command with PG* and DATABASE_URL environment variables
container-psql Run interactive psql inside the container
container-shell Run interactive shell inside the container
container-schema-dump Dump schema from the container
cache Cache management (status, populate, reset)
integration-server Run integration server (pipe-based control protocol)
list List defined instances
platform Platform support checks
Options:
--config-file <PATH> Config file path (default: database.toml)
--no-config-file Use defaults, ignore any config file
--backend <BACKEND> Override backend (docker, podman)
--image <IMAGE> Override PostgreSQL image
--ssl-hostname <HOST> Enable SSL with the specified hostname
--instance <NAME> Target instance (default: main)
```
## Requirements
- Docker Engine 20.10+ / Docker Desktop 4.34+, or Podman 5.3+
- PostgreSQL client tools (`psql`) for host-side commands
## Release Build Configuration
Release builds use `split-debuginfo = "packed"` to separate debug information from the binary:
- **Linux**: Debug info stored in `.dwp` file alongside the binary
- **macOS**: Debug info stored in `.dSYM` bundle alongside the binary
This provides smaller binaries while preserving full backtraces with file paths and line numbers.