diff options
Diffstat (limited to 'man/bolt-tutorial.7')
| -rw-r--r-- | man/bolt-tutorial.7 | 101 |
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 |