Schema as Code: ORMs and External Tools
Atlas supports loading the desired state of your database schema directly from code, enabling true Schema as Code workflows.
Whether your schema is generated by popular ORMs or external tools, regardless of programming language, Atlas can seamlessly integrate with it.
Once loaded, the schema can be used by the various workflows and commands such as atlas schema
and atlas migrate
.
Loading an External Schema
In order to load an external schema, you need first to create an atlas.hcl
config file, if you don't
already have one and declare a new data source of type external_schema
that
can be used later as the desired state. Let's explain this with an example.
Given the following atlas.hcl
file:
- MySQL
- MariaDB
- PostgreSQL
- SQLite
data "external_schema" "orm" {
# The first argument is the command to run,
# and the rest are optional arguments.
program = [
"npm",
"run",
"generate-schema"
]
}
env "orm" {
src = data.external_schema.orm.url
dev = "docker://mysql/8/dev"
}
data "external_schema" "orm" {
# The first argument is the command to run,
# and the rest are optional arguments.
program = [
"npm",
"run",
"generate-schema"
]
}
env "orm" {
src = data.external_schema.orm.url
dev = "docker:/maria/latest/dev"
}
data "external_schema" "orm" {
# The first argument is the command to run,
# and the rest are optional arguments.
program = [
"npm",
"run",
"generate-schema"
]
}
env "orm" {
src = data.external_schema.orm.url
dev = "docker://postgres/15/dev?search_path=public"
}
data "external_schema" "orm" {
# The first argument is the command to run,
# and the rest are optional arguments.
program = [
"npm",
"run",
"generate-schema"
]
}
env "orm" {
src = data.external_schema.orm.url
dev = "sqlite://dev?mode=memory"
}
Let's explain what is happening when running atlas
with the --env orm
command:
- The
external_schema.orm
data source is loaded, by running the commandnpm run generate-schema
and capturing its output as the desired state of the schema. - The program output should be defined as a list of SQL DDL statements separated by semicolon (
;
) or a custom delimiter. More info about the format can be found in the SQL schema page. For example:CREATE TABLE users (id int PRIMARY KEY, name text NOT NULL);
CREATE TABLE posts (id int PRIMARY KEY, content text NOT NULL, author_id int NOT NULL REFERENCES users(id)); - After the schema is loaded, Atlas utilizes the dev-database to parse and validate the SQL definition and converts them into its internal graph representation.
- The loaded schema can be used by the various Atlas commands. For example:
# Generating a new migration.
atlas migrate diff --env orm
# Applying the schema to the database.
atlas schema apply --env orm
Supported ORMs
Atlas supports loading the desired schema from popular ORMs in various languages. By connecting their ORM to Atlas, developers can manage their Database as Code, allowing them to define and edit the schema using familiar ORM syntax. Atlas automatically plans schema migrations for them, eliminating the need to write them manually and enabling them to extend their ORMs with features not supported natively, such as triggers, row-level security, or functions. The supported ORMs are:
Language | ORMs | Supported Databases |
---|---|---|
Python | SQLAlchemy, Django | MySQL MariaDB PostgreSQL SQLite SQL Server |
Go | GORM | MySQL MariaDB PostgreSQL SQLite SQL Server |
Go | Ent, Beego | MySQL MariaDB PostgreSQL SQLite |
Java | Hibernate | MySQL MariaDB PostgreSQL SQLite |
JavaScript TypeScript | Sequelize, TypeORM, Prisma, Drizzle | MySQL MariaDB PostgreSQL SQLite SQL Server |
PHP | Doctrine | MySQL MariaDB PostgreSQL SQLite SQL Server |
C# | Entity Framework Core | MySQL MariaDB PostgreSQL SQLite SQL Server |
If you are using an ORM that is not listed here and would like to see it supported, let us know!
Write an external loader
Most ORMs offer a way to generate a series of DDL statements from model definitions. For example, Java Hibernate enables
"schema exporting" using the hbm2ddl
option, and Microsoft EF supplies a helper method called GenerateCreateScript
that lets users craft a small script to produce DDLs from their EF models. In a similar way, TypeORM users can use
the createSchemaBuilder().log()
API, and so on.
A fully working implementation can be found in the atlas-provider-gorm
repository, which is an external loader for the GORM ORM.