Skip to main content

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​

  1. Install Atlas from macOS or Linux by running:
curl -sSf https://atlasgo.sh | sh

See atlasgo.io for more installation options.

  1. 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.

  1. Create a new program named loader/main.go with the following contents:
main.go
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)
}
info

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.

  1. In your project directory, create a new file named atlas.hcl with the following contents:
atlas.hcl
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 :

user.go
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.