Go Program Mode
This document describes how to set up the provider to load your GORM schema into Atlas in Go Program Mode. Go Program Mode is for more advanced scenarios where you need more control specifying which structs to consider as models.
Using this mode, you can load your GORM schema into Atlas by writing a Go program that imports your GORM models and uses the provider as a library to generate the schema.
If all of your GORM models are in a single package, and either embed gorm.Model
or contain gorm
struct tags,
consider using the Standalone Mode instead.
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 your GORM models are spread across multiple packages, or do not embed gorm.Model
or contain gorm
struct tags,
you can use the provider as a library in your Go program to load your GORM schema into Atlas.
- Create a new program named
loader/main.go
with the following contents:
package main
import (
"fmt"
"io"
"os"
"ariga.io/atlas-provider-gorm/gormschema"
"github.com/<yourorg>/<yourrepo>/path/to/models"
)
func main() {
stmts, err := gormschema.New("mysql").Load(&models.User{})
if err != nil {
fmt.Fprintf(os.Stderr, "failed to load gorm schema: %v\n", err)
os.Exit(1)
}
io.WriteString(os.Stdout, stmts)
}
Be sure to replace github.com/<yourorg>/<yourrepo>/path/to/models
with the import path to your GORM models.
In addition, replace the model types (e.g models.User
) with the types of your GORM models.
- In your project directory, create a new file named
atlas.hcl
with the following contents:
data "external_schema" "gorm" {
program = [
"go",
"run",
"-mod=mod",
"./loader",
]
}
env "gorm" {
src = data.external_schema.gorm.url
dev = "docker://mysql/8/dev"
migration {
dir = "file://migrations"
}
format {
migrate {
diff = "{{ sql . \" \" }}"
}
}
}
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.