Schema Sources Reference

HCL Schema

data "hcl_schema" "<name>" {
  path = "schema.hcl"
}

env "<name>" {
  schema {
    src = data.hcl_schema.<name>.url
  }
}

External Schema (ORM Integration)

The external_schema data source imports SQL schema from an ORM or external program.

# GORM (Go)
data "external_schema" "gorm" {
  program = ["go", "run", "-mod=mod", "ariga.io/atlas-provider-gorm", "load", "--path", "./models", "--dialect", "postgres"]
}

# Drizzle (TypeScript)
data "external_schema" "drizzle" {
  program = ["npx", "drizzle-kit", "export"]
}

# SQLAlchemy (Python)
data "external_schema" "sqlalchemy" {
  program = ["python", "-m", "atlas_provider_sqlalchemy", "--path", "./models", "--dialect", "postgresql"]
}

# Django (Python)
data "external_schema" "django" {
  program = ["python", "manage.py", "atlas-provider-django", "--dialect", "postgresql"]
}

# Ent (Go)
env "<name>" {
  schema {
    src = "ent://ent/schema"
  }
}

# Sequelize (Node.js)
data "external_schema" "sequelize" {
  program = ["npx", "@ariga/atlas-provider-sequelize", "load", "--path", "./models", "--dialect", "postgres"]
}

# TypeORM (TypeScript)
data "external_schema" "typeorm" {
  program = ["npx", "@ariga/atlas-provider-typeorm", "load", "--path", "./entities", "--dialect", "postgres"]
}

Wire into an environment:

env "<name>" {
  schema {
    src = data.external_schema.<orm>.url
  }
}

Composite Schema (Pro)

Combine multiple schema sources into one:

data "composite_schema" "app" {
  schema "users" {
    url = data.external_schema.auth_service.url
  }
  schema "graph" {
    url = "ent://ent/schema"
  }
  schema "shared" {
    url = "file://schema/shared.hcl"
  }
}

Dev-Database Dialects

The dev URL format depends on whether your project uses schema-scoped or database-scoped migrations. Getting this wrong causes errors like ModifySchema is not allowed or silently drops database-level objects (extensions, event triggers) from migrations.

Schema-scoped (single schema — most common): include the database name and schema scope so Atlas creates objects in the correct schema. Use this when all tables live in one schema (e.g., public).

Dialect	Dev URL (schema-scoped)
MySQL	docker://mysql/8/dev
MariaDB	docker://maria/latest/dev
PostgreSQL	docker://postgres/17/dev?search_path=public
SQLite	sqlite://dev?mode=memory
SQL Server	docker://sqlserver/2022-latest/dev?mode=schema
ClickHouse	docker://clickhouse/23.11/dev

Database-scoped (multiple schemas or database-level objects): omit the schema scope so Atlas can manage multiple schemas and detect database-level objects like extensions and event triggers.

Dialect	Dev URL (database-scoped)
MySQL	docker://mysql/8
MariaDB	docker://maria/latest
PostgreSQL	docker://postgres/17/dev
SQL Server	docker://sqlserver/2022-latest/dev?mode=database
ClickHouse	docker://clickhouse/23.11

PostgreSQL with extensions — use PostGIS or pgvector images when the schema uses those extensions:

docker://postgis/latest/dev?search_path=public
docker://pgvector/pg17/dev?search_path=public

How to choose: Check the project's atlas.hcl or target database URL. If it includes search_path=public (Postgres) or a specific database name (MySQL), use schema-scoped. If the project manages multiple schemas, extensions, or event triggers, use database-scoped.

See https://atlasgo.io/concepts/dev-database for additional drivers and options.