Skip to content

Commit 5cbaa73

Browse files
andrew-farriesandrew-farries
authored
Add documentation for the pgroll latest url command (#928)
Add documentation for the `pgroll latest url` command added in #927. * Split the documentation for the `pgroll latest` command into one page per subcomand * Add a documentation page for the new `pgroll latest url` command. Part of #900
1 parent a90b587 commit 5cbaa73

File tree

5 files changed

+189
-70
lines changed

5 files changed

+189
-70
lines changed

‎docs/cli/latest-migration.mdx

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Latest Migration
3+
description: Prints the latest migration name in either the target database or a local directory of migration files.
4+
---
5+
6+
## Command
7+
8+
The `pgroll latest migration` command prints the latest migration name.
9+
10+
## Usage
11+
12+
```
13+
pgroll latest migration [flags]
14+
```
15+
16+
## Flags
17+
18+
- `--local, -l` - retrieve the latest migration from a local migration directory
19+
20+
## Examples
21+
22+
### Database
23+
24+
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
25+
26+
```
27+
$ pgroll latest migration
28+
```
29+
30+
will print the latest migration name in the target database:
31+
32+
```
33+
55_add_primary_key_constraint_to_table
34+
```
35+
36+
### Local
37+
38+
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
39+
40+
```
41+
$ pgroll latest migration --local examples/
42+
```
43+
44+
will print the latest migration name in the directory:
45+
46+
```
47+
55_add_primary_key_constraint_to_table
48+
```
49+
50+
The exact outputs will vary as the `examples/` directory is updated.

‎docs/cli/latest-schema.mdx

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Latest Schema
3+
description: Prints the latest version schema name in either the target database or a local directory of migration files.
4+
---
5+
6+
## Command
7+
8+
The `pgroll latest schema` command prints the latest version schema name.
9+
10+
## Usage
11+
12+
```
13+
pgroll latest schema [flags]
14+
```
15+
16+
## Flags
17+
18+
- `--local, -l` - retrieve the latest version from a local migration directory
19+
20+
## Examples
21+
22+
### Database
23+
24+
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
25+
26+
```
27+
$ pgroll latest schema
28+
```
29+
30+
will print the latest schema version in the target database:
31+
32+
```
33+
public_55_add_primary_key_constraint_to_table
34+
```
35+
36+
### Local
37+
38+
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
39+
40+
```
41+
$ pgroll latest schema --local examples/
42+
```
43+
44+
will print the latest schema version in the directory:
45+
46+
```
47+
public_55_add_primary_key_constraint_to_table
48+
```
49+
50+
The exact outputs will vary as the `examples/` directory is updated.

‎docs/cli/latest-url.mdx

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Latest URL
3+
description: Prints a database connection URL for the latest schema version in either the target database or a local directory of migration files.
4+
---
5+
6+
## Command
7+
8+
The `pgroll latest url` command prints a database connection URL for the latest schema version. Use this to construct connection strings for applications that need to connect to the latest version of the database schema.
9+
10+
## Usage
11+
12+
```
13+
pgroll latest url [connection-string] [flags]
14+
```
15+
16+
## Arguments
17+
18+
- `connection-string` - Optional database connection string. If not provided, uses the connection string from the global `--postgres-url` flag or `PGROLL_PG_URL` environment variable.
19+
20+
## Flags
21+
22+
- `--local, -l` - retrieve the latest schema version from a local migration directory rather than the target database.
23+
24+
## Examples
25+
26+
### Use the global pgroll connection string as the base
27+
28+
With no arguments, the command uses the global `--postgres-url` flag (or the `PGROLL_PG_URL` environment variable) as the connection string on which to set the `search_path`.
29+
30+
```
31+
$ export PGROLL_PG_URL=postgresql://user:pass@example.com:5432/mydb
32+
$ pgroll latest url
33+
```
34+
35+
Output:
36+
```
37+
postgresql://user:pass@example.com:5432/mydb?options=-c%20search_path%3Dpublic_00n_some_migration
38+
```
39+
40+
### Use an arbitrary connection string as the base
41+
42+
With an argument, the command uses the provided connection string as the base and sets its `search_path` to the latest schema version found on the target database (set by the `--postgres-url` flag or `PGROLL_PG_URL` environment variable).
43+
44+
```
45+
$ export PGROLL_PG_URL=postgresql://user:pass@example.com:5432/mydb
46+
$ pgroll latest url postgresql://someotheruser:someotherpass@example.com:5432/mydb
47+
```
48+
49+
Output:
50+
```
51+
postgresql://someotheruser:someotherpass@example.com:5432/mydb?options=-c%20search_path%3Dpublic_00n_some_migration
52+
```
53+
54+
### Take the latest schema version from a local migrations directory
55+
56+
By setting the `--local` flag, the command retrieves the latest schema version from a local migrations directory instead of the target database.
57+
58+
```
59+
$ pgroll latest url --local migrations/ postgresql://me:pass@example.com:5432/mydb
60+
```
61+
62+
Output:
63+
```
64+
postgresql://me:pass@example.com:5432/mydb?options=-c%20search_path%3Dpublic_with_version_schema
65+
```

‎docs/cli/latest.mdx

Lines changed: 6 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,14 @@
11
---
22
title: Latest
3-
description: Prints the latest schema version or migration name in either the target database or a local directory of migration files.
3+
description: Prints information about the latest migration in either the target database or a local directory of migration files.
44
---
55

66
## Command
77

8-
The `pgroll latest` command has two subcommands:
8+
The `pgroll latest` command has three subcommands:
99

10-
- `pgroll latest schema` - prints the latest version schema name
11-
- `pgroll latest migration` - prints the latest migration name
10+
- [`pgroll latest schema`](./latest-schema) - prints the latest version schema name
11+
- [`pgroll latest migration`](./latest-migration) - prints the latest migration name
12+
- [`pgroll latest url`](./latest-url) - prints a database connection URL for the latest schema version
1213

13-
Both subcommands support the `--local` flag to retrieve the latest version from a local directory of migration files instead of the target database.
14-
15-
### Schema Command
16-
17-
#### Database
18-
19-
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
20-
21-
```
22-
$ pgroll latest schema
23-
```
24-
25-
will print the latest schema version in the target database:
26-
27-
```
28-
public_55_add_primary_key_constraint_to_table
29-
```
30-
31-
#### Local
32-
33-
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
34-
35-
```
36-
$ pgroll latest schema --local examples/
37-
```
38-
39-
will print the latest schema version in the directory:
40-
41-
```
42-
public_55_add_primary_key_constraint_to_table
43-
```
44-
45-
The exact outputs will vary as the `examples/` directory is updated.
46-
47-
### Migration Command
48-
49-
#### Database
50-
51-
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
52-
53-
```
54-
$ pgroll latest migration
55-
```
56-
57-
will print the latest migration name in the target database:
58-
59-
```
60-
55_add_primary_key_constraint_to_table
61-
```
62-
63-
#### Local
64-
65-
Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
66-
67-
```
68-
$ pgroll latest migration --local examples/
69-
```
70-
71-
will print the latest migration name in the directory:
72-
73-
```
74-
55_add_primary_key_constraint_to_table
75-
```
76-
77-
The exact outputs will vary as the `examples/` directory is updated.
14+
All subcommands support the `--local` flag to retrieve information from a local directory of migration files instead of the target database.

‎docs/config.json

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,24 @@
9797
{
9898
"title": "Latest",
9999
"href": "/cli/latest",
100-
"file": "docs/cli/latest.mdx"
100+
"file": "docs/cli/latest.mdx",
101+
"items": [
102+
{
103+
"title": "Latest Schema",
104+
"href": "/cli/latest-schema",
105+
"file": "docs/cli/latest-schema.mdx"
106+
},
107+
{
108+
"title": "Latest Migration",
109+
"href": "/cli/latest-migration",
110+
"file": "docs/cli/latest-migration.mdx"
111+
},
112+
{
113+
"title": "Latest URL",
114+
"href": "/cli/latest-url",
115+
"file": "docs/cli/latest-url.mdx"
116+
}
117+
]
101118
},
102119
{
103120
"title": "Pull",

0 commit comments

Comments
 (0)