# 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