df938fa · reshape · git.iko.soy

git.iko.soy/reshape

Update docs and error messages with new CLI commands

commitdf938fa4d453bd3334b9a0e96154ff10c34f060b authorfabianlindfors <fabian@flapplabs.se> dateFri 22 Apr 2022, 10:45 (4 years ago) parent88fca45

2 files changed+33−29

compare with main

unifiedsplit

README.md+24−22 src/lib.rs+9−7

README.md+24−22

@@ -35,10 +35,10 @@ Designed for Postgres 12 and later.

3535 - [Remove enum](#remove-enum)

3636 - [Custom](#custom)

3737- [Commands and options](#commands-and-options)

38− - [`reshape migrate`](#reshape-migrate)

39− - [`reshape complete`](#reshape-complete)

40− - [`reshape abort`](#reshape-abort)

41− - [`reshape generate-schema-query`](#reshape-generate-schema-query)

38+ - [`reshape migration start`](#reshape-migration-start)

39+ - [`reshape migration complete`](#reshape-migration-complete)

40+ - [`reshape migration abort`](#reshape-migration-abort)

41+ - [`reshape schema-query`](#reshape-schema-query)

4242 - [Connection options](#connection-options)

4343- [License](#license)

4444

@@ -47,11 +47,11 @@ Designed for Postgres 12 and later.

4747

4848Reshape works by creating views that encapsulate the underlying tables, which your application will interact with. During a migration, Reshape will automatically create a new set of views and set up triggers to translate inserts and updates between the old and new schema. This means that every deployment is a three-phase process:

4949

50−1. **Start migration** (`reshape migrate`): Sets up views and triggers to ensure both the new and old schema are usable at the same time.

50+1. **Start migration** (`reshape migration start`): Sets up views and triggers to ensure both the new and old schema are usable at the same time.

51512. **Roll out application**: Your application can be gradually rolled out without downtime. The existing deployment will continue using the old schema whilst the new deployment uses the new schema.

52−3. **Complete migration** (`reshape complete`): Removes the old schema and any intermediate data and triggers.

52+3. **Complete migration** (`reshape migration complete`): Removes the old schema and any intermediate data and triggers.

5353

54−If the application deployment fails, you should run `reshape abort` which will roll back any changes made by `reshape migrate` without losing data.

54+If the application deployment fails, you should run `reshape migration abort` which will roll back any changes made by `reshape migration start` without losing data.

5555

5656## Getting started

5757

@@ -74,7 +74,7 @@ cargo install reshape

7474Reshape is available as a Docker image on [Docker Hub](https://hub.docker.com/repository/docker/fabianlindfors/reshape).

7575

7676```shell

77−docker run -v $(pwd):/usr/share/app fabianlindfors/reshape reshape migrate

77+docker run -v $(pwd):/usr/share/app fabianlindfors/reshape reshape migration start

7878```

7979

8080### Creating your first migration

@@ -103,9 +103,9 @@ This is the equivalent of running `CREATE TABLE users (id INTEGER GENERATED ALWA

103103

104104### Preparing your application

105105

106−Reshape relies on your application using a specific schema. When establishing the connection to Postgres in your application, you need to run a query to select the most recent schema. This query can be generated using: `reshape generate-schema-query`.

106+Reshape relies on your application using a specific schema. When establishing the connection to Postgres in your application, you need to run a query to select the most recent schema. This query can be generated using: `reshape schema-query`.

107107

108−To pass it along to your application, you can for example use an environment variable in your run script: `RESHAPE_SCHEMA_QUERY=$(reshape generate-schema-query)`. Then in your application:

108+To pass it along to your application, you can for example use an environment variable in your run script: `RESHAPE_SCHEMA_QUERY=$(reshape schema-query)`. Then in your application:

109109

110110```python

111111# Example for Python

@@ -120,16 +120,16 @@ If your application is written in Rust, you might prefer the [Rust helper librar

120120To create your new `users` table, run:

121121

122122```bash

123−reshape migrate --complete

123+reshape migration start --complete

124124```

125125

126−We use the `--complete` flag to automatically complete the migration. During a production deployment, you should first run `reshape migrate` followed by `reshape complete` once your application has been fully rolled out.

126+We use the `--complete` flag to automatically complete the migration. During a production deployment, you should first run `reshape migration start` followed by `reshape migration complete` once your application has been fully rolled out.

127127

128128If nothing else is specified, Reshape will try to connect to a Postgres database running on `localhost` using `postgres` as both username and password. See [Connection options](#connection-options) for details on how to change the connection settings.

129129

130130### Using during development

131131

132−When adding new migrations during development, we recommend running `reshape migrate` but skipping `reshape complete`. This way, the new migrations can be iterated on by updating the migration file and running `reshape abort` followed by `reshape migrate`.

132+When adding new migrations during development, we recommend running `reshape migration start` but skipping `reshape migration complete`. This way, the new migrations can be iterated on by updating the migration file and running `reshape migration abort` followed by `reshape migration start`.

133133

134134## Writing migrations

135135

@@ -538,9 +538,9 @@ The `custom` action lets you create a migration which runs custom SQL. It should

538538

539539There are three optional settings available which all accept SQL queries. All queries need to be idempotent, for example by using `IF NOT EXISTS` wherever available.

540540

541−- `start`: run when a migration is started using `reshape migrate`

542−- `complete`: run when a migration is completed using `reshape complete`

543−- `abort`: run when a migration is aborted using `reshape abort`

541+- `start`: run when a migration is started using `reshape migration start`

542+- `complete`: run when a migration is completed using `reshape migration complete`

543+- `abort`: run when a migration is aborted using `reshape migration abort`

544544

545545*Example: enable PostGIS and pg_stat_statements extensions*

546546

@@ -561,9 +561,9 @@ abort = """

561561

562562## Commands and options

563563

564−### `reshape migrate`

564+### `reshape migration start`

565565

566−Starts a new migration, applying all migrations under `migrations/` that haven't yet been applied. After the command has completed, both the old and new schema will be usable at the same time. When you have rolled out the new version of your application which uses the new schema, you should run `reshape complete`.

566+Starts a new migration, applying all migrations under `migrations/` that haven't yet been applied. After the command has completed, both the old and new schema will be usable at the same time. When you have rolled out the new version of your application which uses the new schema, you should run `reshape migration complete`.

567567

568568#### Options

569569

@@ -574,15 +574,15 @@ Starts a new migration, applying all migrations under `migrations/` that haven't

574574| `--complete`, `-c` | `false` | Automatically complete migration after applying it. |

575575| `--dirs` | `migrations/` | Directories to search for migration files. Multiple directories can be specified using `--dirs dir1 dir2 dir3`. |

576576

577−### `reshape complete`

577+### `reshape migration complete`

578578

579−Completes migrations previously started with `reshape complete`.

579+Completes migrations previously started with `reshape migration complete`.

580580

581581#### Options

582582

583583See [Connection options](#connection-options)

584584

585−### `reshape abort`

585+### `reshape migration abort`

586586

587587Aborts any migrations which haven't yet been completed.

588588

@@ -590,10 +590,12 @@ Aborts any migrations which haven't yet been completed.

590590

591591See [Connection options](#connection-options)

592592

593−### `reshape generate-schema-query`

593+### `reshape schema-query`

594594

595595Generates the SQL query you need to run in your application before using the database. This command does not require a database connection. Instead it will generate the query based on the latest migration in the `migrations/` directory (or the directories specified by `--dirs`).

596596

597+If your application is written in Rust, we recommend using the [Rust helper library](https://github.com/fabianlindfors/reshape-helper/) instead.

598+

597599The query should look something like `SET search_path TO migration_1_initial_migration`.

598600

599601#### Options

src/lib.rs+9−7

@@ -147,13 +147,15 @@ fn migrate(

147147) -> anyhow::Result<()> {

148148 // Make sure no migration is in progress

149149 if let State::InProgress { .. } = &state {

150− println!("Migration already in progress, please complete using 'reshape complete'");

150+ println!(

151+ "Migration already in progress, please complete using 'reshape migration complete'"

152+ );

151153 return Ok(());

152154 }

153155

154156 if let State::Completing { .. } = &state {

155157 println!(

156− "Migration already in progress and has started completion, please finish using 'reshape complete'"

158+ "Migration already in progress and has started completion, please finish using 'reshape migration complete'"

157159 );

158160 return Ok(());

159161 }

@@ -176,7 +178,7 @@ fn migrate(

176178 {

177179 if existing_migrations != &remaining_migrations {

178180 return Err(anyhow!(

179− "a previous migration seems to have failed without cleaning up. Please run `reshape abort` and then run migrate again."

181+ "a previous migration seems to have failed without cleaning up. Please run `reshape migration abort` and then run migrate again."

180182 ));

181183 }

182184 }

@@ -232,7 +234,7 @@ fn migrate(

232234 // Set to the Aborting state. This is to ensure that the failed

233235 // migration is fully aborted and nothing is left dangling.

234236 // If the abort is interrupted for any reason, the user can try again

235− // by running `reshape abort`.

237+ // by running `reshape migration abort`.

236238 state.aborting(

237239 remaining_migrations.clone(),

238240 last_migration_index + 1,

@@ -259,7 +261,7 @@ fn migrate(

259261 schema_query_for_migration(&target_migration)

260262 );

261263 println!(

262− " - Run 'reshape complete' once your application has been updated and the previous schema is no longer in use"

264+ " - Run 'reshape migration complete' once your application has been updated and the previous schema is no longer in use"

263265 );

264266 Ok(())

265267}

@@ -281,7 +283,7 @@ fn complete(db: &mut DbConn, state: &mut State) -> anyhow::Result<()> {

281283 current_action_index

282284 } => (migrations, current_migration_index, current_action_index),

283285 State::Aborting { .. } => {

284− return Err(anyhow!("migration been aborted and can't be completed. Please finish using `reshape abort`."))

286+ return Err(anyhow!("migration been aborted and can't be completed. Please finish using `reshape migration abort`."))

285287 }

286288 State::Applying { .. } => {

287289 return Err(anyhow!("a previous migration unexpectedly failed. Please run `reshape migrate` to try applying the migration again."))

@@ -409,7 +411,7 @@ fn abort(db: &mut DbConn, state: &mut State) -> anyhow::Result<()> {

409411 last_action_index,

410412 } => (migrations, last_migration_index, last_action_index),

411413 State::Completing { .. } => {

412− return Err(anyhow!("Migration completion has already been started. Please run `reshape complete` again to finish it."));

414+ return Err(anyhow!("migration completion has already been started. Please run `reshape migration complete` again to finish it."));

413415 }

414416 State::Idle => {

415417 println!("No migration is in progress");