readme: documenting usage (#3)

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/<yourorg>/<yourrepo>/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).

internal/gormschema/gorm.go → 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"

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() {