aboutsummaryrefslogtreecommitdiffstats
path: root/docs/tutorial.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-18 10:43:39 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-11-26 11:46:57 -0500
commite5658d1f61415054029b66cd2f703f1f40138460 (patch)
treec609e209f4cebc62dd985d1b773558f47eb73bf6 /docs/tutorial.md
parentAdd is-branch main check for docs deployment (diff)
downloadcli-e5658d1f61415054029b66cd2f703f1f40138460.zip
Add support for migration dependencies
Diffstat (limited to '')
-rw-r--r--docs/tutorial.md67
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.