Standalone Mode
This document describes how to set up the provider to load your GORM schema into Atlas in Standalone Mode.
Standalone Mode is for the common case, where all of your GORM models exist in a single package and either embed gorm.Model
or contain gorm
struct tags.
Using these heuristics, the provider can automatically detect your models and load them into Atlas.
For more advanced use cases, where you need more control specifying which structs to consider as models, see Go Program Mode.
Installation
- Install Atlas from macOS or Linux by running:
curl -sSf https://atlasgo.sh | sh
See atlasgo.io for more installation options.
- Install the provider by running:
go get -u ariga.io/atlas-provider-gorm
Setup
If all of your GORM models exist in a single package, and either embed gorm.Model
or contain gorm
struct
tags, you can use the provider directly to load your GORM schema into Atlas.
- In your project directory, create a new file named
atlas.hcl
with the following contents:
data "external_schema" "gorm" {
program = [
"go",
"run",
"-mod=mod",
"ariga.io/atlas-provider-gorm",
"load",
"--path", "./path/to/models",
"--dialect", "mysql", // | postgres | sqlite | sqlserver
]
}
env "gorm" {
src = data.external_schema.gorm.url
dev = "docker://mysql/8/dev"
migration {
dir = "file://migrations"
}
format {
migrate {
diff = "{{ sql . \" \" }}"
}
}
}
- To prevent the Go Modules system from dropping this dependency from our
go.mod
file, let's follow the official recommendation for tracking dependencies of tools and add a file named tools.go with the following contents:
//go:build tools
package main
import _ "ariga.io/atlas-provider-gorm/gormschema"
Alternatively, you can simply add a blank import to the models.go file we created above.
- Finally, to tidy things up, run:
go mod tidy
Verify Setup
Next, let's verify Atlas is able to read our desired schema, by running the
schema inspect
command, to inspect our desired schema (GORM models).
atlas schema inspect --env gorm --url "env://src"
Notice that this command uses env://src
as the target URL for inspection, meaning "the schema represented by the
src
attribute of the local
environment block."
Given we have a simple GORM model user
:
type User struct {
gorm.Model
Name string
Age int
}
We should get the following output after running the inspect
command above:
table "users" {
schema = schema.dev
column "id" {
null = false
type = bigint
unsigned = true
auto_increment = true
}
column "created_at" {
null = true
type = datetime(3)
}
column "updated_at" {
null = true
type = datetime(3)
}
column "deleted_at" {
null = true
type = datetime(3)
}
column "name" {
null = true
type = longtext
}
column "age" {
null = true
type = bigint
}
primary_key {
columns = [column.id]
}
index "idx_users_deleted_at" {
columns = [column.deleted_at]
}
}
schema "dev" {
charset = "utf8mb4"
collate = "utf8mb4_0900_ai_ci"
}
Next Steps
Now that your project is set up, start by choosing between the two workflows offered by Atlas for generating and planning migrations. Select the one you prefer that works best for you:
Declarative Migrations: Set up a Terraform-like workflow where each migration is calculated as the diff between your desired state and the current state of the database.
Versioned Migrations: Set up a migration directory for your project, creating a version-controlled source of truth of your database schema.