Atlas supports loading the desired state of your database schema directly from code, enabling trueSchema 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 asatlas schema andatlas migrate.

ORMs and Frameworks

Click here for guides on using various ORMs with Atlas

Loading an External Schema​

In order to load an external schema, you need first to create anatlas.hclconfig file, if you don'talready have one and declare a new data source of typeexternal_schema thatcan be used later as the desired state. Let's explain this with an example.

Given the followingatlas.hcl file:

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 runningatlas with the--env orm command:

1. Theexternal_schema.orm data source is loaded, by running the commandnpm run generate-schema andcapturing its output as the desired state of the schema.
2. The program output should be defined as a list of SQL DDL statements separated by semicolon (;) or acustom delimiter. More info about the format can be found intheSQL schema page. For example:

   CREATETABLE users(idintPRIMARYKEY, nametextNOTNULL);
   
   CREATETABLE posts(idintPRIMARYKEY, contenttextNOTNULL, author_idintNOTNULLREFERENCES users(id));
   
3. After the schema is loaded, Atlas utilizes thedev-database to parse and validate theSQL definition and converts them into its internal graph representation.
4. The loaded schema can be used by the various Atlas commands. For example:

   # Generating a new migration.
   atlas migratediff--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 theirDatabase 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 toextend their ORMs with features not supported natively, such as triggers, row-level security, or functions. The supported ORMs are:

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 thehbm2ddl option, and Microsoft EF supplies a helper method calledGenerateCreateScriptthat lets users craft a small script to produce DDLs from their EF models. In a similar way, TypeORM users can usethecreateSchemaBuilder().log() API, and so on.

A fully working implementation can be found in theatlas-provider-gormrepository, which is an external loader for theGORM ORM.