Skip to main content

Verify Atlas and Export Your Schema

After successfully connecting to your database using Atlas, our next step will be to verify that Atlas is able to inspect your database schema and that it correctly normalizes it such that if re-applied to the database no diff will be detected.

Step 1: Export your database URL as an env var​

To make the examples in this section brief, start by setting a local environment variable containing the URL you determined for your database:

export DB_URL="<url>"

Step 2: Export Database to Code​

Use the Atlas schema inspect (or schema export) command to connect to your database and export its schema as code.

Atlas supports two output formats:

  • HCL: A declarative syntax similar to Terraform. Supports IDE features like jump-to-definition and auto-completion. Resources can be defined in any order across files.
  • SQL: Standard DDL statements (CREATE TABLE, etc.). Atlas automatically generates import directives to resolve dependencies between objects.
atlas schema inspect --url "$DB_URL" > schema.hcl

For the full reference, see Export Database Schema to Code.

Step 3: Determine your Dev Database URL​

info

Notice that when we discuss a Dev Database in the Atlas documentation, we DO NOT refer to the local database you use for development, but to a different concept explained below.

To operate correctly, Atlas utilizes a Dev Database to normalize and verify schemas and migrations. Essentially, a dev-database is an empty database of the same type and version that you use in production. When Atlas runs, it may run some operations against this database, and is responsible for cleaning up after and leaving the database in an empty state.

While you may provide your own dev database to use, most Atlas users prefer our built-in docker:// driver which will spin up a local, ephemeral Docker container and dispose of it after for you.

As we mentioned in the previous section, Atlas operates differently depending on the connection scope. Be sure to use the same scope for your dev-database as your target database to avoid miscalculations.

Select your database below to get the corresponding Docker Dev Database URL:

# When working on a single database schema, use the auth-created
# "public" schema as the search path.
--dev-url "docker://postgres/15/dev?search_path=public"

# When working on multiple database schemas.
--dev-url "docker://postgres/15/dev"

The docker driver also supports the postgis and pgvector images in its URL format:

--dev-url "docker://postgis/latest/dev"
--dev-url "docker://pgvector/pg17/dev"

To work with a custom Docker image, use one of the following formats:

# When working on a single database schema.
docker+postgres://org/image/dev?search_path=public
docker+postgres://ghcr.io/namespace/image:tag/dev?search_path=public
# For local/official images, leave host empty or use "_".
docker+postgres://_/local/dev?search_path=public
docker+postgres://_/official:latest/dev?search_path=public

# When working on multiple database schemas.
docker+postgres://org/image/dev
# Default database is "postgres".
docker+postgres://org/image:tag

For more details, see the Dev Database guide.

Step 4: Verify Zero Diff​

Next, use Atlas's schema apply --dry-run command to check that Atlas sees no difference between your exported schema and the actual database:

atlas schema apply \
  --url "$DB_URL" \
  --to file://schema.hcl \
  --dev-url <dev_db_url> \
  --dry-run

Be sure to replace <dev_db_url> with the Dev Database URL you determined in step 3.

If everything works correctly, Atlas should print out a message similar to:

Schemas are synced, no changes to be made.
Need help?

If you encounter any issues during this step, reach out via your shared Slack Connect channel (commercial PoC) or use the Community Support channels.