From 1b8ffbfc44c30485df028728bb0c17b53419ccb8 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 28 Jan 2024 15:55:14 -0500 Subject: Add version cmd to docs --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 94cf3f4..41355ee 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Bolt is a command-line tool designed to simplify and streamline your database mi - [`bolt up`](#bolt-up) - [`bolt down`](#bolt-down) - [`bolt status`](#bolt-status) + - [`bolt version`](#bolt-version) - [Script Execution Options](#script-execution-options) - [Explanation](#explanation) - [How Are Migration Scripts Executed?](#how-are-migration-scripts-executed) @@ -339,6 +340,14 @@ status: List the database migrations and their statuses ``` +#### `bolt version` + +```bash +$ bolt help version +version: + Show the current version of Bolt +``` + ### Script Execution Options Bolt provides a way for you to customize how your migration scripts are executed if you need something different than the default behavior. -- cgit v1.2.3 From 345e28bd44ba6a38bf7ee9bfe2066f333bbbe894 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 28 Jan 2024 16:29:00 -0500 Subject: Update to checkmate v0.2.0 --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 41355ee..002ac97 100644 --- a/README.md +++ b/README.md @@ -287,6 +287,7 @@ driver = All configuration file settings have corresponding environment variables. - `BOLT_MIGRATIONS_DIR_PATH` +- `BOLT_MIGRATIONS_VERSION_STYLE` - `BOLT_DB_CONN_HOST` - `BOLT_DB_CONN_PORT` - `BOLT_DB_CONN_USER` -- cgit v1.2.3 From d45be1a75e6c55a7b1037f14c9e163be9a1ce214 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 2 Mar 2024 10:32:42 -0500 Subject: Update docs and changelog --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 002ac97..39b818a 100644 --- a/README.md +++ b/README.md @@ -261,6 +261,12 @@ or in any parent directory. # the current working directory. You may also use an absolute # path. directory_path = "migrations" +# The migration versioning style you prefer. Supported options +# are "timestamp" and "sequential". Defaults to "timestamp". +# +# Note: It is not supported to change migration version styles +# once one is picked and migrations have been applied. +version_style = "timestamp" # Connection parameters for the database Bolt will be # applying migrations to. All connection parameters are -- cgit v1.2.3 From 3f17785d4b9a4e0403797388ef9e07ceae10b087 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 2 Mar 2024 10:49:51 -0500 Subject: Add better docs on version styles --- README.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index a885180..34cc666 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,15 @@ Bolt is a command-line tool designed to simplify and streamline your database mi - [`bolt status`](#bolt-status) - [`bolt version`](#bolt-version) - [Script Execution Options](#script-execution-options) + - [Version Styles](#version-styles) - [Explanation](#explanation) - [How Are Migration Scripts Executed?](#how-are-migration-scripts-executed) - [How Does Bolt Know What Migrations Have Been Applied?](#how-does-bolt-know-what-migrations-have-been-applied) - [How Are Migrations Applied?](#how-are-migrations-applied) - [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) ## Installation @@ -245,7 +249,7 @@ At the moment, only PostgreSQL is supported. You're welcome to contribute suppor ### Configuration -There are two ways to configure Bolt: via a `bolt.toml` file or via environment variables. If you use both methods, the environment variables will take precedence. +There are two ways to configure Bolt: via a `bolt.toml` file or via environment variables. If you use both methods, the environment variables will always take precedence. #### Configuration File @@ -361,6 +365,12 @@ You can do this by adding a comment to the top of your migration script. The com - `no-transaction`: Execute the migration script without a transaction. By default, every migration script will be attempted to be executed within a transaction, however, some SQL commands cannot be executed within a transaction so you'll need to opt out of that behavior in those cases. +### Version Styles + +The following version styles are supported: +- Timestamp +- Sequential + ## Explanation ### How Are Migration Scripts Executed? @@ -378,3 +388,21 @@ When you run `bolt up`, Bolt will look at your local migration scripts and compa ### How Are Migrations Reverted? When you run `bolt down`, Bolt will look at the `bolt_migrations` table and compare the versions to the versions of your local migration scripts. Any versions that are in the table but not in your local migration scripts will be reverted in order, starting with the newest migration. Reverting a migration entails executing the `downgrade.sql` script in a transaction and removing the migration's version from the `bolt_migrations` table. + +### What are Migration Version Styles? + +Whenever you create a migration, it'll be prefixed with a "version". This is what is used by Bolt to keep track of what order to apply or revert migrations. Version styles are different supported options for what this prefix will be. + +Bolt supports two different options for this: +- Sequential versions +- Timestamp versions + +Sequential versions are incrementing integers. When you create a migration, it'll be prefixed with a number like "001", "002", and so on. Timestamp versions + +### Why can't I change between version styles? + +The main reason that switching back and forth between "sequential" and "timestamp" versions is not supported is because Bolt will no longer know how to properly sort your migrations in the right order (and therefore, apply or revert them in the right order). If you've been using sequential migrations, such as "001" and "002", and then move over to timestamp migrations, such as "20200101000000", Bolt won't know how to order these. Furthermore, because the "version" is parsed and sorted according to the version style that is configured, that parsing will fail if a mix of version styles are used. + +### How is the migration message used by Bolt? + +All migrations are created on the local filesystem in the format `_`. Bolt uses the `` part of the name for keeping track of the migrations and how they should be applied or reverted. The `` part is purely informational so you know what that migration is for. Bolt does not use or store it anywhere. You may alter this message whenever you'd like as long as the format is kept consistent (`_` after the ``). However, the version should not be directly manipulated. -- cgit v1.2.3 From 20c23062aae34ced8b2497c1b1486ce86dc897fd Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 2 Mar 2024 10:51:11 -0500 Subject: tweak wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 34cc666..6491f0e 100644 --- a/README.md +++ b/README.md @@ -267,7 +267,7 @@ directory_path = "migrations" # are "timestamp" and "sequential". Defaults to "timestamp". # # Note: It is not supported to change migration version styles -# once one is picked and migrations have been applied. +# i.e. you can't have a mix of sequential and timestamp migrations. version_style = "timestamp" # Connection parameters for the database Bolt will be -- cgit v1.2.3 From eddbda03dc7901c048d8f8e533348c0a9004de81 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 2 Mar 2024 10:52:14 -0500 Subject: fix migration version style explanation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6491f0e..906da38 100644 --- a/README.md +++ b/README.md @@ -397,7 +397,7 @@ Bolt supports two different options for this: - Sequential versions - Timestamp versions -Sequential versions are incrementing integers. When you create a migration, it'll be prefixed with a number like "001", "002", and so on. Timestamp versions +Sequential versions are incrementing integers. When you create a migration, it'll be prefixed with a number like "001", "002", and so on. Timestamp versions use the current time on migration creation as the prefix. ### Why can't I change between version styles? -- cgit v1.2.3 From d7f75f46e0c6cfdab67dfe505b0f35a4a21a588e Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 2 Mar 2024 10:53:13 -0500 Subject: improve wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 906da38..beda0f3 100644 --- a/README.md +++ b/README.md @@ -401,7 +401,7 @@ Sequential versions are incrementing integers. When you create a migration, it'l ### Why can't I change between version styles? -The main reason that switching back and forth between "sequential" and "timestamp" versions is not supported is because Bolt will no longer know how to properly sort your migrations in the right order (and therefore, apply or revert them in the right order). If you've been using sequential migrations, such as "001" and "002", and then move over to timestamp migrations, such as "20200101000000", Bolt won't know how to order these. Furthermore, because the "version" is parsed and sorted according to the version style that is configured, that parsing will fail if a mix of version styles are used. +The main reason that switching back and forth between "sequential" and "timestamp" versions is not supported is because Bolt will no longer know how to properly sort your migrations in the right order (and therefore, apply or revert them in the right order). If you've been using sequential migrations, such as "001" and "002", and then move over to timestamp migrations, such as "20200101000000", Bolt won't know how to order these correctly when both exist. Furthermore, because the "version" is parsed and sorted according to the version style that is configured, the parsing will fail if a mix of version styles are used. ### How is the migration message used by Bolt? -- cgit v1.2.3