From 449f74ded67b49fb3066d6d107fa6de9dba0093c Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 12 Feb 2026 19:14:17 -0500 Subject: Replace HTML docs with man pages that ship with bolt --- docs/tutorial.md | 250 ------------------------------------------------------- 1 file changed, 250 deletions(-) delete mode 100644 docs/tutorial.md (limited to 'docs/tutorial.md') diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index 147a6f6..0000000 --- a/docs/tutorial.md +++ /dev/null @@ -1,250 +0,0 @@ -# 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 \ - --env POSTGRES_USER=bolt_user \ - --env POSTGRES_PASSWORD=bolt_password \ - --env POSTGRES_DB=bolt_tutorial_db \ - --publish 5432:5432 \ - --detach \ - postgres:latest -``` - -## Configuring Bolt - -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: - -```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. Generally, 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) -``` - -## 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. - -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 -- cgit v1.2.3