diff options
Diffstat (limited to 'docs/tutorial.md')
| -rw-r--r-- | docs/tutorial.md | 192 |
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 |