aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-tutorial.7
diff options
context:
space:
mode:
Diffstat (limited to 'man/bolt-tutorial.7')
-rw-r--r--man/bolt-tutorial.7101
1 files changed, 101 insertions, 0 deletions
diff --git a/man/bolt-tutorial.7 b/man/bolt-tutorial.7
new file mode 100644
index 0000000..83933aa
--- /dev/null
+++ b/man/bolt-tutorial.7
@@ -0,0 +1,101 @@
+.Dd February 12, 2026
+.Dt BOLT-TUTORIAL 7
+.Os
+.Sh NAME
+.Nm bolt-tutorial
+.Nd getting started with bolt
+.Sh DESCRIPTION
+This tutorial guides you through the basics of using
+.Xr bolt 1
+to manage database migrations.
+.Sh PREREQUISITES
+Before starting, ensure you have:
+.Bl -bullet -offset Ds -compact
+.It
+Bolt installed
+.It
+A database available (PostgreSQL, MySQL, SQL Server, or SQLite)
+.El
+.Sh CREATING YOUR FIRST MIGRATION
+Create a migration with:
+.Dl $ bolt new -m \(dqcreate users table\(dq
+.Pp
+This creates a
+.Pa migrations/
+directory with a file like:
+.Dl 20240316145038_create_users_table.sql
+.Sh WRITING MIGRATION SCRIPTS
+Edit the migration file to add SQL statements:
+.Bd -literal -offset indent
+-- 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()
+);
+
+-- migrate:down
+DROP TABLE users;
+.Ed
+.Pp
+The
+.Cm -- migrate:up
+section runs when applying the migration.
+The
+.Cm -- migrate:down
+section runs when reverting it.
+.Sh CONFIGURING BOLT
+Create a
+.Pa bolt.toml
+file:
+.Bd -literal -offset indent
+[database]
+dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable"
+driver = "postgresql"
+.Ed
+.Pp
+See
+.Xr bolt.toml 5
+for all configuration options.
+.Sh APPLYING MIGRATIONS
+Apply all pending migrations:
+.Dl $ bolt up
+.Pp
+Apply up to a specific version:
+.Dl $ bolt up -v 20240316145038
+.Sh CHECKING STATUS
+View migration status:
+.Dl $ bolt status
+.Pp
+Output shows version, message, and whether each migration is applied.
+.Sh REVERTING MIGRATIONS
+Revert the most recent migration:
+.Dl $ bolt down
+.Pp
+Revert to a specific version:
+.Dl $ bolt down -v 20240316145038
+.Sh WORKING WITH DEPENDENCIES
+When you create a second migration, Bolt automatically adds a dependency
+on existing migrations:
+.Bd -literal -offset indent
+-- depends: 20240316145038
+-- migrate:up
+CREATE TABLE posts (
+ id SERIAL PRIMARY KEY,
+ user_id INTEGER NOT NULL REFERENCES users(id),
+ title VARCHAR(255) NOT NULL
+);
+
+-- migrate:down
+DROP TABLE posts;
+.Ed
+.Pp
+Dependencies ensure migrations run in the correct order. See
+.Xr bolt-dependencies 7
+for details.
+.Sh SEE ALSO
+.Xr bolt 1 ,
+.Xr bolt.toml 5 ,
+.Xr bolt-migration 5 ,
+.Xr bolt-dependencies 7