aboutsummaryrefslogtreecommitdiffstats
path: root/docs/tutorial.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tutorial.md')
-rw-r--r--docs/tutorial.md250
1 files changed, 0 insertions, 250 deletions
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