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

1. Install Atlas from macOS or Linux by running:

curl -sSf https://atlasgo.sh | sh

See atlasgo.io for more installation options.

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

1. 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 . \"  \" }}"
    }
  }
}

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

3. 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 :

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