aboutsummaryrefslogtreecommitdiffstats
path: root/docs/tutorial.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-10 23:11:16 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-10-10 23:11:16 -0400
commitc500a84b35338ac0f429133a0b07ced8d457976f (patch)
tree54d526e4c07c0171f8e6f41933b607a8ab09127c /docs/tutorial.md
parentAdd note on contributing guide to README (diff)
downloadcli-c500a84b35338ac0f429133a0b07ced8d457976f.zip
Refactor docs to use mkdocs and sourcehut pages
Diffstat (limited to '')
-rw-r--r--docs/tutorial.md192
1 files changed, 192 insertions, 0 deletions
diff --git a/docs/tutorial.md b/docs/tutorial.md
new file mode 100644
index 0000000..73ebbf0
--- /dev/null
+++ b/docs/tutorial.md
@@ -0,0 +1,192 @@
+# 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.
+
+## Prerequisites
+
+Before starting this tutorial, make sure you have:
+
+- Bolt installed (see [Installation](installation.md))
+- Docker installed (for running the database container)
+
+## Creating your first migration
+
+Run the following command to create your first migration:
+
+```bash
+bolt new -m "my first migration"
+```
+
+Output:
+```
+Created migration 20240316145038 - my first migration.
+```
+
+Upon completion, a migrations directory will be created with the following structure:
+
+```bash
+migrations
+└── 20240316145038_my_first_migration.sql
+
+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 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`
+
+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,
+ email VARCHAR(255) NOT NULL,
+ created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+-- migrate:down
+DROP TABLE users;
+```
+
+## Starting up a Database Container
+
+We'll use Docker to run a PostgreSQL database container for this tutorial:
+
+1. Install Docker
+
+If you don't have docker installed, view the installation instructions [here](https://docs.docker.com/get-docker/).
+
+2. Startup the PostgreSQL container
+
+```bash
+docker run --name bolt-postgres \
+ -e POSTGRES_USER=bolt_user \
+ -e POSTGRES_PASSWORD=bolt_password \
+ -e POSTGRES_DB=bolt_tutorial_db \
+ -p 5432:5432 \
+ --detach postgres:16.1-alpine3.19
+```
+
+## 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.
+
+1. Create a `bolt.toml` file:
+
+```bash
+touch bolt.toml
+```
+
+2. Add the following contents to the file:
+
+```toml
+[database]
+dsn = "postgresql://bolt_user:bolt_password@localhost:5432/bolt_tutorial_db?sslmode=disable"
+driver = "postgresql"
+```
+
+## Applying your migration
+
+Apply your migration, which will execute the upgrade script:
+
+```bash
+bolt up
+```
+
+Output:
+```
+Applying migration 20240316145038_my_first_migration..
+Successfully applied migration 20240316145038_my_first_migration in 3.217875ms!
+```
+
+## Checking Migration Status
+
+To view the status of your migration:
+
+```bash
+bolt status
+```
+
+Output:
+```
+Version Message Applied
+20240316145038 my_first_migration X
+```
+
+This command displays the migration's version, name, and whether the migration was applied or not.
+
+## Verifying the Migration
+
+Connect to the database container to confirm the users table was created:
+
+```bash
+docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
+```
+
+```psql
+bolt_tutorial_db=# \dt
+ List of relations
+ Schema | Name | Type | Owner
+--------+-----------------+-------+-----------
+ public | bolt_migrations | table | bolt_user
+ public | users | table | bolt_user
+(2 rows)
+```
+
+We can see that our `users` table was created successfully. We also see another table that we didn't explicitly create called `bolt_migrations`. This table is used by Bolt to keep track of which migrations have been applied to your database. You should not modify this table manually.
+
+## Downgrading Your Migration
+
+To revert your migration:
+
+```bash
+bolt down
+```
+
+Output:
+```
+Reverting migration 20240316145038_my_first_migration..
+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:
+
+```bash
+docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
+```
+
+```psql
+bolt_tutorial_db=# \dt
+ List of relations
+ Schema | Name | Type | Owner
+--------+-----------------+-------+-----------
+ public | bolt_migrations | table | bolt_user
+(1 row)
+```
+
+## Next Steps
+
+Congratulations! You've learned the core features of Bolt.
+
+To learn more:
+
+- Check out [How-To Guides](how-to.md) for specific tasks
+- Browse the [Reference](reference.md) for detailed command and configuration documentation
+- Read the [Explanation](explanation.md) section to understand how Bolt works internally