Skip to content

Commit 88edd61

Browse files
Update documentation
* Tidy up the `latest` command documentation to clarify the difference between the schema version and migration name outputs. * Add a section to the operations documentation explaining the difference between migration names and version schema names.
1 parent b042dd3 commit 88edd61

File tree

2 files changed

+41
-4
lines changed

2 files changed

+41
-4
lines changed

docs/cli/latest.mdx

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ description: Prints the latest schema version or migration name in either the ta
77

88
The `pgroll latest` command has two subcommands:
99

10-
- `pgroll latest schema` - prints the latest schema version (migration name prefixed with schema name)
11-
- `pgroll latest migration` - prints the latest migration name (without schema prefix)
10+
- `pgroll latest schema` - prints the latest version schema name
11+
- `pgroll latest migration` - prints the latest migration name
1212

1313
Both subcommands support the `--local` flag to retrieve the latest version from a local directory of migration files instead of the target database.
1414

@@ -42,6 +42,8 @@ will print the latest schema version in the directory:
4242
public_55_add_primary_key_constraint_to_table
4343
```
4444

45+
The exact outputs will vary as the `examples/` directory is updated.
46+
4547
### Migration Command
4648

4749
#### Database
@@ -72,4 +74,4 @@ will print the latest migration name in the directory:
7274
55_add_primary_key_constraint_to_table
7375
```
7476

75-
The exact output will vary as the `examples/` directory is updated.
77+
The exact outputs will vary as the `examples/` directory is updated.

docs/operations/README.md

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,39 @@ JSON migration:
1818
}
1919
```
2020

21-
The `version_schema` field is optional and specifies the name of the schema that will be created for the migration. If not specified, the name of the migration file (minus any `.yaml` or `.json` suffix) will be used as the schema name.
21+
The `version_schema` field is optional.
22+
23+
## Migration names vs version schema names
24+
25+
When a `pgroll` migration is run a version schema for the migration is created. The name of the version schema defaults to the name of the migration file (minus any `.yaml`, or .`json` suffix). For example, this migration:
26+
27+
```yaml
28+
operations:
29+
- create_table:
30+
name: items
31+
columns:
32+
- name: id
33+
type: serial
34+
pk: true
35+
- name: name
36+
type: varchar(255)
37+
```
38+
39+
will create a version schema called `01_create_table`, assuming the migration filename is `01_create_table.yaml`.
40+
41+
The name of the version schema that a migration will create when run can be overridden using the `version_schema` field:
42+
43+
```yaml
44+
version_schema: my_version_schema
45+
operations:
46+
- create_table:
47+
name: items
48+
columns:
49+
- name: id
50+
type: serial
51+
pk: true
52+
- name: name
53+
type: varchar(255)
54+
```
55+
56+
This migration will create a version schema called `my_version_schema` regardless of the migration filename.

0 commit comments

Comments
 (0)