Skip to main content

Inspect an external schema data source (ORM schema)

How to inspect an external_schema data source (ORM schema) in atlas.hcl to confirm it loaded correctly?

Answer​

When defining an external_schema data source in atlas.hcl, it serves as a schema source that can be used as the desired state. To confirm Atlas can load it correctly, verify that the ORM-generated schema is properly interpreted by running atlas schema inspect against it.

To verify that Atlas can read and load the ORM-generated schema correctly, run atlas schema inspect against the src of your environment.

info

By default, inspect uses the url defined in the environment block. To load the schema from the external source instead, override it with --url env://src.

Example Configuration​

Consider the following atlas.hcl configuration:

atlas.hcl
data "external_schema" "gorm" {
  program = [
    "go", "run",
    "ariga.io/atlas-provider-gorm", "load",
    "--path", "./path/to/models",
    "--dialect", "postgres",
  ]
}

env "gorm" {
  src = data.external_schema.gorm.url
  dev = "docker://postgres/15/dev?search_path=public"
}

Basic Inspection​

To verify that the ORM schema loads correctly, run:

atlas schema inspect --env gorm --url env://src

This command tells Atlas to read the schema from the external_schema data source and outputs it in HCL format, allowing you to verify that the ORM-generated schema was loaded as expected.

Interactive Visualization​

To visualize the schema interactively, add the -w flag:

atlas schema inspect --env gorm --url env://src -w

This opens a browser window with an ERD (Entity Relationship Diagram) of the schema loaded from your ORM, providing a visual confirmation that the schema structure is correct.

SQL Format Output​

To get an SQL representation of the schema instead of HCL, use the --format flag:

atlas schema inspect --env gorm --url env://src --format '{{ sql . }}'

This is particularly useful when you want to see the actual SQL DDL statements that represent your ORM schema.

Common Use Cases​

This inspection technique is especially valuable when:

  • Setting up a new external_schema data source for the first time
  • Debugging issues with ORM schema generation
  • Validating that schema changes from your ORM are reflected correctly
  • Ensuring your ORM schema (like GORM, Django ORM, etc.) is generating the expected schema structure

Troubleshooting​

If the inspection fails, check:

  1. Program accessibility: Ensure the ORM provider program specified in the external_schema is available and executable
  2. Path correctness: Verify that paths in the program arguments are correct relative to the working directory
  3. Dependencies: Make sure all required dependencies for your ORM provider are installed