Skip to content

Commit 5bdfa62

Browse files
committed
Update documentation
1 parent 7d1c3e8 commit 5bdfa62

File tree

2 files changed

+74
-6
lines changed

2 files changed

+74
-6
lines changed
Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
-- Example:
22
-- This migration is applied after migrations/000024_site_config.up.sql
3+
-- and inserts a value into site_configs that must not cause issues in
4+
-- future migrations.
35

4-
-- noop
5-
/*
6-
7-
INSERT INTO users (id, username, ...) VALUES ('583fb393-3cc8-4a38-accf-7182074f981f', 'user-that-could-break-in-the-future', ...);
8-
9-
*/
6+
INSERT INTO site_configs(key, value) VALUES ('mytest', 'example');

docs/CONTRIBUTING.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,77 @@ Use the following `make` commands and scripts in development:
7373
- `make install` installs binaries to `$GOPATH/bin`
7474
- `make test`
7575

76+
### Adding database migrations and fixtures
77+
78+
#### Database migrations
79+
80+
Database migrations are managed with [`migrate`](https://github.com/golang-migrate/migrate).
81+
82+
To add new migrations, use the following command:
83+
84+
```console
85+
$ ./coderd/database/migrations/create_fixture.sh my name
86+
/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
87+
/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
88+
Run "make gen" to generate models.
89+
```
90+
91+
Then write queries into the generated `.up.sql` and `.down.sql` files and commit
92+
them into the repository. The down script should make a best-effort to retain as
93+
much data as possible.
94+
95+
#### Database fixtures (for testing migrations)
96+
97+
There are two types of fixtures that are used to test that migrations don't
98+
break existing Coder deployments:
99+
100+
- Partial fixtures [`migrations/testdata/fixtures`](./coderd/database/migrations/testdata/fixtures)
101+
- Full database dumps [`migrations/testdata/full_dumps`](./coderd/database/migrations/testdata/full_dumps)
102+
103+
Both types behave like database migrations (they also [`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors Coder migrations such that when migration
104+
number `000022` is applied, fixture `000022` is applied afterwards.
105+
106+
Partial fixtures are used to conveniently add data to newly created tables so
107+
that we can ensure that this data is migrated without issue.
108+
109+
Full database dumps are for testing the migration of fully-fledged Coder
110+
deployments. These are usually done for a specific version of Coder and are
111+
often fixed in time. A full database dump may be necessary when testing the
112+
migration of multiple features or complex configurations.
113+
114+
To add a new partial fixture, run the following command:
115+
116+
```console
117+
$ ./coderd/database/migrations/create_fixture.sh my fixture
118+
/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
119+
```
120+
121+
Then add some queries to insert data and commit the file to the repo. See
122+
[`000024_example.up.sql`](./coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
123+
for an example.
124+
125+
To create a full dump, run a fully fledged Coder deployment and use it to
126+
generate data in the database. Then shut down the deployment and take a snapshot
127+
of the database.
128+
129+
```console
130+
$ mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
131+
$ pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
132+
```
133+
134+
Make sure sensitive data in the dump is desensitized, for instance names,
135+
emails, OAuth tokens and other secrets. Then commit the dump to the project.
136+
137+
To find out what the latest migration for a version of Coder is, use the
138+
following command:
139+
140+
```console
141+
$ git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
142+
```
143+
144+
This helps in naming the dump (e.g. `000069` above).
145+
146+
76147
## Styling
77148

78149
### Documentation

0 commit comments

Comments
 (0)