From 65ded7c0133ae011a30546fb4fd1e00fc3179874 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 16 Mar 2024 15:06:30 -0400 Subject: Update migration file format --- CHANGELOG.md | 10 ++ README.md | 72 +++++----- internal/bolttest/mock_migration_fs_repo.go | 17 ++- internal/configloader/configloader.go | 2 +- internal/configloader/configloader_test.go | 2 +- internal/models/migration.go | 13 +- internal/models/migration_test.go | 32 ++++- internal/repositories/migration_db_repo.go | 2 +- internal/repositories/migration_fs_repo.go | 73 +++++----- internal/repositories/migration_fs_repo_test.go | 41 +++--- internal/services/migration.go | 34 ++--- internal/services/migration_test.go | 37 +++-- internal/sqlparse/sqlparse.go | 78 ++++++++--- internal/sqlparse/sqlparse_test.go | 175 +++++++++++++++++++++--- 14 files changed, 403 insertions(+), 185 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b131cf..38eb98a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased + +### Changed + +- Migrations are now a single file with an upgrade and downgrade script delineated by a `-- migrate:up` or `--migrate:down` comment instead of the prior approach where the migration was a directory with a `upgrade.sql` and `downgrade.sql` file within it. + +- Default version style is now timestamp. + +- `bolt_migrations` `version` column is now a `VARCHAR(255)` instead of `CHARACTER(14)`. + ## [0.7.0] - 2024-03-14 ### Changed diff --git a/README.md b/README.md index b40b1fc..9fca409 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ Features: - [How Are Migrations Reverted?](#how-are-migrations-reverted) - [What are Migration Version Styles?](#what-are-migration-version-styles) - [Why can't I change between version styles?](#why-cant-i-change-between-version-styles) - - [How is the migration message used by Bolt?](#how-is-the-migration-message-used-by-bolt) + - [How is the migration message used?](#how-is-the-migration-message-used) ## Installation @@ -83,30 +83,38 @@ Run the following command to create your first migration: ```bash $ bolt new -m "my first migration" +Created migration 20240316145038 - my first migration. ``` Upon completion, a migrations directory will be created with the following structure: ```bash -migrations/ -└── 001_my_first_migration - ├── downgrade.sql - └── upgrade.sql +migrations +└── 20240316145038_my_first_migration.sql -1 directories, 2 files +1 directory, 1 file ``` Bolt automatically creates the migrations directory and your migration scripts inside it. ### Writing your migration scripts -Bolt utilizes plain SQL for migration scripts. Each migration directory contains `upgrade.sql` for applying migrations and `downgrade.sql` for reverting them. +Bolt utilizes plain SQL for migration scripts. Each migration directory contains a comment for the upgrade script portion with `-- migrate:up` and a comment for the downgrade script with `-- migrate:down`. -1. Write the Upgrade Script +1. Open up `20240316145038_my_first_migration.sql` -Edit `upgrade.sql` with the following SQL command to create a new table: +You'll see the following template in the file for your migration: ```sql +-- migrate:up + +-- migrate:down +``` + +2. Write your migration script + +```sql +-- migrate:up CREATE TABLE users ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, @@ -114,13 +122,7 @@ CREATE TABLE users ( created_at TIMESTAMP NOT NULL DEFAULT NOW(), updated_at TIMESTAMP NOT NULL DEFAULT NOW() ); -``` - -2. Write the Downgrade Script - -Edit `downgrade.sql` with the following SQL command to remove the table: - -```sql +-- migrate:down DROP TABLE users; ``` @@ -166,8 +168,8 @@ Apply your migration, which will execute the `upgrade.sql` script: ```bash $ bolt up -Applying migration 001_my_first_migration.. -Successfully applied migration 001_my_first_migration! +Applying migration 20240316145038_my_first_migration.. +Successfully applied migration 20240316145038_my_first_migration! ``` ### Checking Migration Status @@ -177,7 +179,7 @@ To view the status of your migration: ```bash $ bolt status Version Message Applied -001 my_first_migration X +20240316145038 my_first_migration X ``` This command displays the migration's version, name, and whether the migration was applied or not. @@ -208,8 +210,8 @@ To revert your migration: ```bash $ bolt down -Reverting migration 001_my_first_migration.. -Successfully reverted migration 001_my_first_migration! +Reverting migration 20240316145038_my_first_migration.. +Successfully reverted migration 20240316145038_my_first_migration! ``` ### Verifying Migration Reversion @@ -231,16 +233,18 @@ bolt_tutorial_db=# \dt ### Next Steps -Congrats! You've learned the core features of Bolt. If you want learn more, see the [Reference](#reference) or [Explanation](#explanation) section. +Congrats! You've learned the core features of Bolt. If you want learn more, see the [How-to](#how-to), [Reference](#reference), or [Explanation](#explanation) section. ## How-to ### How to execute a migration script without a transaction -In your `upgrade.sql` or `downgrade.sql`, add the following line as the first line of your script: +In your migration script, add a `transaction:false` option: ```sql --- bolt: no-transaction +-- migrate:up transaction:false + +-- migrate:down transaction:false ``` ## Reference @@ -269,11 +273,11 @@ or in any parent directory. # path. directory_path = "migrations" # The migration versioning style you prefer. Supported options -# are "timestamp" and "sequential". Defaults to "sequential". +# are "timestamp" and "sequential". Defaults to "timestamp". # # Note: It is not supported to change migration version styles # i.e. you can't have a mix of sequential and timestamp migrations. -version_style = "sequential" +version_style = "timestamp" # Connection parameters for the database Bolt will be # applying migrations to. All connection parameters are @@ -366,9 +370,9 @@ version: Bolt provides a way for you to customize how your migration scripts are executed if you need something different than the default behavior. -You can do this by adding a comment to the top of your migration script. The comment must be in the following format: `-- bolt: