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.
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:
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:
- Program accessibility: Ensure the ORM provider program specified in the
external_schema
is available and executable - Path correctness: Verify that paths in the program arguments are correct relative to the working directory
- Dependencies: Make sure all required dependencies for your ORM provider are installed