diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-18 10:43:39 -0400 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-11-26 11:46:57 -0500 |
| commit | e5658d1f61415054029b66cd2f703f1f40138460 (patch) | |
| tree | c609e209f4cebc62dd985d1b773558f47eb73bf6 /docs/tutorial.md | |
| parent | Add is-branch main check for docs deployment (diff) | |
| download | cli-e5658d1f61415054029b66cd2f703f1f40138460.zip | |
Add support for migration dependencies
Diffstat (limited to 'docs/tutorial.md')
| -rw-r--r-- | docs/tutorial.md | 67 |
1 files changed, 60 insertions, 7 deletions
diff --git a/docs/tutorial.md b/docs/tutorial.md index d163f23..147a6f6 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,6 +1,8 @@ # Tutorial -In this tutorial, we'll guide you through the basics of using Bolt by running through how you can create a migration, apply it, revert it, and see the status of your migrations. +In this tutorial, we'll guide you through the basics of using Bolt by running +through how you can create a migration, apply it, revert it, and see the +status of your migrations. ## Prerequisites @@ -22,7 +24,8 @@ Output: Created migration 20240316145038 - my first migration. ``` -Upon completion, a migrations directory will be created with the following structure: +Upon completion, a migrations directory will be created with the following +structure: ```bash migrations @@ -31,11 +34,14 @@ migrations 1 directory, 1 file ``` -Bolt automatically creates the migrations directory and your migration scripts inside it. +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 file contains a comment for the upgrade script portion with `-- migrate:up` and a comment for the downgrade script with `-- migrate:down`. +Bolt utilizes plain SQL for migration scripts. Each migration file contains a +comment for the upgrade script portion with `-- migrate:up` and a comment for +the downgrade script with `-- migrate:down`. 1. Open up `20240316145038_my_first_migration.sql` @@ -86,7 +92,8 @@ docker run \ ## Configuring Bolt -Bolt can be configured with a `bolt.toml` file or environment variables. For simplicity, we'll use a `bolt.toml` file in this tutorial. +Bolt can be configured with a `bolt.toml` file and environment variables. For +simplicity, we'll use a `bolt.toml` file in this tutorial. 1. Create a `bolt.toml` file: @@ -130,7 +137,8 @@ Version Message Applied 20240316145038 my_first_migration X ``` -This command displays the migration's version, name, and whether the migration was applied or not. +This command displays the migration's version, name, and whether the migration +was applied or not. ## Verifying the Migration @@ -171,7 +179,8 @@ Successfully reverted migration 20240316145038_my_first_migration in 6.283667ms! ## Verifying Migration Reversion -Reconnect to the database container and check that the users table has been removed: +Reconnect to the database container and check that the users table has been +removed: ```bash docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db @@ -186,6 +195,50 @@ bolt_tutorial_db=# \dt (1 row) ``` +## Creating a migration with dependencies + +Let's create another migration that depends on the first one: + +```bash +bolt new -m "create posts table" +``` + +Open the new migration file. You'll see that Bolt automatically added +a dependency on the previous migration: + +```sql +-- depends: 20240316145038 +-- migrate:up + +-- migrate:down +``` + +Add the migration SQL: + +```sql +-- depends: 20240316145038 +-- migrate:up +CREATE TABLE posts ( + id SERIAL PRIMARY KEY, + user_id INTEGER NOT NULL REFERENCES users(id), + title VARCHAR(255) NOT NULL, + content TEXT NOT NULL, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +-- migrate:down +DROP TABLE posts; +``` + +Apply the new migration: + +```bash +bolt up +``` + +The dependency ensures that the `users` table exists before creating the +`posts` table with its foreign key reference. + ## Next Steps Congratulations! You've learned the core features of Bolt. |