From 911faf41fc8f5044e6e50295c8dac9b822bf1bea Mon Sep 17 00:00:00 2001 From: Alexis Viscogliosi Date: Mon, 4 Nov 2024 10:29:48 +0100 Subject: [PATCH] fix: doc --- .../03-running-your-first-migration.md | 2 - .../02-quick-start/04-create-go-migration.md | 65 +++++++++++++++++++ .../02-quick-start/05-create-sql-migration.md | 20 ++++++ ....md => 06-working-with-existing-schema.md} | 0 ...md => 07-working-with-not-supported-db.md} | 0 docs/docs/03-cli/03-create.md | 42 ++++++++++-- docs/docs/index.md | 2 +- 7 files changed, 124 insertions(+), 7 deletions(-) create mode 100644 docs/docs/02-quick-start/04-create-go-migration.md create mode 100644 docs/docs/02-quick-start/05-create-sql-migration.md rename docs/docs/02-quick-start/{04-working-with-old-schema.md => 06-working-with-existing-schema.md} (100%) rename docs/docs/02-quick-start/{05-working-with-not-supported-db.md => 07-working-with-not-supported-db.md} (100%) diff --git a/docs/docs/02-quick-start/03-running-your-first-migration.md b/docs/docs/02-quick-start/03-running-your-first-migration.md index db6953a..047f0dd 100644 --- a/docs/docs/02-quick-start/03-running-your-first-migration.md +++ b/docs/docs/02-quick-start/03-running-your-first-migration.md @@ -10,8 +10,6 @@ Amigo is driver agnostic and works with the `database/sql` package. `pgx` provide a support for the `database/sql` package and is a good choice for postgres, but you can use any driver that support the `database/sql` package. - - When you have installed the driver on you project, run the migration, execute the following command: ```sh diff --git a/docs/docs/02-quick-start/04-create-go-migration.md b/docs/docs/02-quick-start/04-create-go-migration.md new file mode 100644 index 0000000..c46b9fe --- /dev/null +++ b/docs/docs/02-quick-start/04-create-go-migration.md @@ -0,0 +1,65 @@ +# Go migration +Now you can create your own migration, to do that you can run the following command: + +```sh +amigo create create_users_table +``` + +This command will create a new migration file `{DATE}_create_users_table.go` in the `migrations` folder. + +This migration is in go, you have two kinds of migration files: +- classic: they are up and down migrations as they implement [DetailedMigration](https://github.com/alexisvisco/amigo/blob/main/pkg/schema/migrator.go#L40) interface +- change: they are up migrations as they implement [ChangeMigration](https://github.com/alexisvisco/amigo/blob/main/pkg/schema/migrator.go#L48) interface + +(more information on the cli [here](../03-cli/03-create.md)) + + +### Example of a `change` migration file: + +```go +package migrations + +import ( + "github.com/alexisvisco/amigo/pkg/schema/pg" +) + +type Migration20240524090434CreateUserTable struct {} + +func (m Migration20240524090434CreateUserTable) Change(s *pg.Schema) { + s.CreateTable("users", func(def *pg.PostgresTableDef) { + def.Serial("id") + def.String("name") + def.String("email") + def.Timestamps() + def.Index([]string{"name"}) + }) +} +``` + +### Example of a `classic` migration file: + +```go +package migrations + +import ( + "github.com/alexisvisco/amigo/pkg/schema/pg" +) + +type Migration20240524090434CreateUserTable struct {} + +func (m Migration20240524090434CreateUserTable) Up(s *pg.Schema) { + s.CreateTable("users", func(def *pg.PostgresTableDef) { + def.Serial("id") + def.String("name") + def.String("email") + def.Timestamps() + def.Index([]string{"name"}) + }) +} + +func (m Migration20240524090434CreateUserTable) Down(s *pg.Schema) { + s.DropTable("users") +} +``` + + diff --git a/docs/docs/02-quick-start/05-create-sql-migration.md b/docs/docs/02-quick-start/05-create-sql-migration.md new file mode 100644 index 0000000..f28c3fc --- /dev/null +++ b/docs/docs/02-quick-start/05-create-sql-migration.md @@ -0,0 +1,20 @@ +# SQL Migration + +If you have a custom SQL to execute like materialized view, procedures and you want autocompletion and IDE support from +SQL, you can use the `--type sql` flag. + +```sh +amigo create my_migration --type sql +``` + +### Example of a `sql` migration file: + +```sql +-- todo: write up migrations here +-- migrate:down +-- todo: write down migrations here +``` + +It act as a classic migration, you can write your SQL in the `-- todo: write up migrations here` section. + +All code below the `-- migrate:down` comment will be used to rollback the migration. \ No newline at end of file diff --git a/docs/docs/02-quick-start/04-working-with-old-schema.md b/docs/docs/02-quick-start/06-working-with-existing-schema.md similarity index 100% rename from docs/docs/02-quick-start/04-working-with-old-schema.md rename to docs/docs/02-quick-start/06-working-with-existing-schema.md diff --git a/docs/docs/02-quick-start/05-working-with-not-supported-db.md b/docs/docs/02-quick-start/07-working-with-not-supported-db.md similarity index 100% rename from docs/docs/02-quick-start/05-working-with-not-supported-db.md rename to docs/docs/02-quick-start/07-working-with-not-supported-db.md diff --git a/docs/docs/03-cli/03-create.md b/docs/docs/03-cli/03-create.md index bba9bef..0f9d5e1 100644 --- a/docs/docs/03-cli/03-create.md +++ b/docs/docs/03-cli/03-create.md @@ -2,10 +2,11 @@ Create will add a new migration file to the migrations folder. -There is two kinds of migrations files: +There are 3 kinds of migrations files: - classic: they have an Up, Down, Date and Name function. - change: they have a Change, Date and Name function. +- sql: they are raw sql files. To create a new migration file, run the following command: @@ -52,14 +53,44 @@ func (m Migration20240502155033SchemaVersion) Date() time.Time { - `--pg-dump-path` to specify the path to the `pg_dump` command. - `--type` to specify the type of migration to create, possible values are [classic, change, sql] (default is `change`) -## Difference between classic and change migration +## Up and Down migration (type `classic`) + +By specifying the `--type classic` flag, you will create a classic migration file. + +In the classic migration, you have to implement the Up and Down function. The Up function is used to apply the migration, and the Down function is used to rollback the migration. + +```go +package migrations + +import ( + "github.com/alexisvisco/mig/pkg/schema/pg" + "github.com/alexisvisco/mig/pkg/schema" + "time" +) + +type Migration20240502155033SchemaVersion struct {} + +func (m Migration20240502155033SchemaVersion) Up(s *pg.Schema) { + s.CreateTable("public.mig_schema_versions", func(s *pg.PostgresTableDef) { + s.String("id") + }, schema.TableOptions{ IfNotExists: true }) +} + +func (m Migration20240502155033SchemaVersion) Down(s *pg.Schema) { + s.DropTable("public.mig_schema_versions") +} +``` In the classic migration, you have to implement the Up and Down function. The Up function is used to apply the migration, and the Down function is used to rollback the migration. +## Auto reversible by API migrations (type `change`) + +They are the default ones when you create a new migration file. + While in the change migration, you have to implement the Change function. The Change function is used to apply the migration. The rollback is done by applying the inverse of the Change function. -The inverse of the Change function is automatically generated by all mig methods. +The inverse of the Change function is automatically generated by almost all mig methods. For example, if you have this method in the Change function: ```go @@ -90,6 +121,9 @@ func (m Migration20240502155033SchemaVersion) Change(s *pg.Schema) { If you run this migration and then rollback it, mig will not know how to rollback the `INSERT INTO` statement. So it will execute it, the problem that the table will be dropped and the `INSERT INTO` statement will fail. + +#### Custom reversible method in a change migration + To avoid this problem, you need to use the `Reversible` method. @@ -111,7 +145,7 @@ func (m Migration20240502155033SchemaVersion) Change(s *pg.Schema) { } ``` -### Raw sql migrations +### Raw sql migrations (type `sql`) You can also create a raw SQL migration by using the `--type sql` flag. diff --git a/docs/docs/index.md b/docs/docs/index.md index 77a0844..259a25c 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -20,7 +20,7 @@ General documentation: [https://amigo.alexisvis.co](https://amigo.alexisvis.co) ## Why another migration library? -First thing, I don't have anything against SQL migrations file library. I appreciate them but somethimes with SQL files you are limited to do complex migrations that imply your models and business logic. +First thing, I don't have anything against SQL migrations file library (I support them). I appreciate them but sometimes with SQL files you are limited to do complex migrations that imply your models and business logic. I just like the way activerecord (rails) migration system and I think it's powerful to combine migration and code.