PostgreSQL: Schema Testing with Template Databases

atlas schema test can now run every test group on a fresh copy of the dev database using PostgreSQL template databases, making cycle setup near-constant no matter how large the schema is. Test runs become 8x-10x faster end to end, and up to dozens of times faster for larger schemas. Opt in with template = true on a docker or dev block.

Usage

For a Docker-based dev database, which gives you a disposable server per run, set template = true on the docker block:

docker "postgres" "dev" {  image    = "postgres:18"  template = true}
env "test" {  src = "file://schema.sql"  dev = docker.postgres.dev.url}

Any objects defined in the baseline field are present in every copy:

docker "postgres" "dev" {  image    = "postgres:18"  template = true  baseline = <<SQL    CREATE ROLE app_owner;    CREATE FUNCTION aurora_global_db_instance_status() ...;  SQL}

For a user-managed dev database, for example a PostgreSQL service container in CI or a standing dev server, set it on the dev block:

dev "postgres" "main" {  url      = "postgres://user:pass@dev-server:5432/dev"  template = true}

Then run the command as usual, no other changes needed:

$ atlas schema test --env test

Notes and limitations

• PostgreSQL only. This feature is not supported on CockroachDB, YugabyteDB, or Aurora DSQL.
• The dev connection must be database-scoped. template cannot be combined with the docker block's schema attribute or a search_path-scoped URL.
• This behavior only kicks in when a command runs more than one test cycle. Single-group runs behave as normal.
• For dev blocks, the database must be dedicated to Atlas (the standing dev-database requirement). Other sessions on them are terminated when the run starts, and the run requires privileges to create databases and manage roles.

Getting Started

Template databases are part of Atlas Pro, like schema test itself:

$ atlas login

Then, set template = true on your dev database block and run atlas schema test. See the schema testing docs for the full testing framework.