aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: 12f4e7715f5bb792e3d3b56b25d58c274b8414a1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
# Bolt

[![GoDoc](https://godoc.org/git.sr.ht/~eugenetriguba/bolt?status.svg)](https://godoc.org/git.sr.ht/~eugenetriguba/bolt)
[![Go Report Card](https://goreportcard.com/badge/git.sr.ht/~eugenetriguba/bolt)](https://goreportcard.com/report/git.sr.ht/~eugenetriguba/bolt)
![Version](https://img.shields.io/badge/version-0.13.1-blue)
[![Build Status](https://builds.sr.ht/~eugenetriguba/bolt/commits/main.svg)](https://builds.sr.ht/~eugenetriguba/bolt/commits/main?)

Bolt is a command-line tool for database migrations.

## Why Bolt?

Bolt aims to be a simple and reliable tool that can work anywhere you need to
run database migrations.

- Schema migrations are written in plain SQL.
- Migrations can be versioned sequentially or by creation timestamp.
- All migrations run in transactions by default.
- Supports up and down migrations and jumping to any particular schema version.
- Supports PostgreSQL, MySQL, SQL Server, and SQLite3.

## What It Looks Like

Migrations are separated by "up" and "down" comments to delineate what runs when
you apply the migration and what runs when you revert it. Additionally,
migrations have dependencies which are what determine the execution order.

```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;
```

```bash
$ bolt status
Version           Message               Applied
20240316145038    create_users_table    X
20240317120000    create_posts_table    X
20240318093000    add_email_index
```

## Installation

### From Source

Clone the repository:

```
git clone https://git.sr.ht/~eugenetriguba/bolt
```

Build the binary:

```
cd bolt
make
```

Install the binary and man pages:

```
sudo make install
```

### Homebrew

If you're on macOS (or Linux and use Homebrew), you can install Bolt from the tap:

```bash
brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt
brew install bolt
```

## Documentation

After installation, documentation is available via man pages.

### Commands

| Page | Description |
|------|-------------|
| bolt(1) | Main command overview |
| bolt-new(1) | Create a new migration |
| bolt-up(1) | Apply migrations |
| bolt-down(1) | Revert migrations |
| bolt-status(1) | List migration statuses |
| bolt-version(1) | Print version |
| bolt-help(1) | Show manual pages |

### File Formats

| Page | Description |
|------|-------------|
| bolt.toml(5) | Configuration file and environment variables |
| bolt-migration(5) | Migration script format |

### Concepts

| Page | Description |
|------|-------------|
| bolt-tutorial(7) | Getting started tutorial |
| bolt-databases(7) | Database drivers and DSN formats |
| bolt-dependencies(7) | Migration dependency system |
| bolt-execution(7) | How migrations are executed |

## License

MIT License. See [LICENSE](./LICENSE) for details.