From 45c5889799b8295c0b33d60110a7f42dbcac36cc Mon Sep 17 00:00:00 2001 From: Rotem Tamir Date: Tue, 20 Jun 2023 14:59:24 +0300 Subject: [PATCH] readme: documenting usage (#3) --- README.md | 146 +++++++++++++++++- {internal/gormschema => gormschema}/gorm.go | 2 +- loader.tmpl | 4 +- .../recordriver => recordriver}/driver.go | 0 .../driver_test.go | 0 5 files changed, 148 insertions(+), 4 deletions(-) rename {internal/gormschema => gormschema}/gorm.go (96%) rename {internal/recordriver => recordriver}/driver.go (100%) rename {internal/recordriver => recordriver}/driver_test.go (100%) diff --git a/README.md b/README.md index c70c2c8..d97bff4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,146 @@ # atlas-provider-gorm -GORM Provider for https://atlasgo.io + +Load [GORM](https://gorm.io/) schemas into an [Atlas](https://atlasgo.io) project. + +### Use-cases +1. **Declarative migrations** - use a Terraform-like `atlas schema apply --env gorm` to apply your GORM schema to the database. +2. **Automatic migration planning** - use `atlas migrate diff --env gorm` to automatically plan a migration from + the current database version to the GORM schema. + +### Installation + +Install Atlas from macOS or Linux by running: +```bash +curl -sSf https://atlasgo.sh | sh +``` +See [atlasgo.io](https://atlasgo.io/getting-started#installation) for more installation options. + +#### Standalone + +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: + +```hcl +data "external_schema" "gorm" { + program = [ + "go", + "run", + "-mod=mod", + "ariga.io/atlas-provider-gorm", + "--path", "./path/to/models", + "--dialect", "mysql", // | postgres | sqlite + ] +} + +env "gorm" { + src = data.external_schema.gorm.url + dev = "docker://mysql/8/dev" + migration { + dir = "file://migrations" + } + format { + migrate { + diff = "{{ sql . \" \" }}" + } + } +} +``` + +#### As Go File + +If you want to use the provider as a Go file, you can use the provider as follows: + +Create a new program named `loader/main.go` with the following contents: + +```go +package main + +import ( + "io" + "os" + + "ariga.io/atlas-provider-gorm/gormschema" + _ "ariga.io/atlas-provider-gorm/recordriver" + "github.com///path/to/models" +) + +func main() { + stmts, err := gormschema.New("mysql", &models.User{}, &models.Pet{}).Load() + if err != nil { + fmt.Fprintf(os.Stderr, "failed to load gorm schema: %v\n", err) + os.Exit(1) + } + io.WriteString(os.Stdout, stmts) +} +``` + +In your project directory, create a new file named `atlas.hcl` with the following contents: + +```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 . \" \" }}" + } + } +} +``` + +### Usage + +Once you have the provider installed, you can use it to apply your GORM schema to the database: + +#### Apply + +You can use the `atlas schema apply` command to plan and apply a migration of your database to +your current GORM schema. This works by inspecting the target database and comparing it to the +GORM schema and creating a migration plan. Atlas will prompt you to confirm the migration plan +before applying it to the database. + +```bash +atlas schema apply --env gorm -u "mysql://root:password@localhost:3306/mydb" +``` +Where the `-u` flag accepts the [URL](https://atlasgo.io/concepts/url) to the +target database. + +#### Diff + +Atlas supports a [version migration](https://atlasgo.io/concepts/declarative-vs-versioned#versioned-migrations) +workflow, where each change to the database is versioned and recorded in a migration file. You can use the +`atlas migrate diff` command to automatically generate a migration file that will migrate the database +from its latest revision to the current GORM schema. + +```bash +atlas migrate diff --env gorm +``` + +### Supported Databases + +The provider supports the following databases: +* MySQL +* PostgreSQL +* SQLite + +### Issues + +Please report any issues or feature requests in the [ariga/atlas](https://github.com/ariga/atlas/issues) repository. + +### License + +This project is licensed under the [Apache License 2.0](LICENSE). \ No newline at end of file diff --git a/internal/gormschema/gorm.go b/gormschema/gorm.go similarity index 96% rename from internal/gormschema/gorm.go rename to gormschema/gorm.go index 75668d7..07d7767 100644 --- a/internal/gormschema/gorm.go +++ b/gormschema/gorm.go @@ -5,7 +5,7 @@ import ( "database/sql/driver" "fmt" - "ariga.io/atlas-provider-gorm/internal/recordriver" + "ariga.io/atlas-provider-gorm/recordriver" "gorm.io/driver/mysql" "gorm.io/driver/postgres" "gorm.io/driver/sqlite" diff --git a/loader.tmpl b/loader.tmpl index 7350198..51c01e1 100644 --- a/loader.tmpl +++ b/loader.tmpl @@ -8,8 +8,8 @@ import ( {{- range .Imports }} "{{ . }}" {{- end}} - "ariga.io/atlas-provider-gorm/internal/gormschema" - _ "ariga.io/atlas-provider-gorm/internal/recordriver" + "ariga.io/atlas-provider-gorm/gormschema" + _ "ariga.io/atlas-provider-gorm/recordriver" ) func main() { diff --git a/internal/recordriver/driver.go b/recordriver/driver.go similarity index 100% rename from internal/recordriver/driver.go rename to recordriver/driver.go diff --git a/internal/recordriver/driver_test.go b/recordriver/driver_test.go similarity index 100% rename from internal/recordriver/driver_test.go rename to recordriver/driver_test.go