Skip to content

Add documentation for the pgroll latest url command #928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 30, 2025

Conversation

andrew-farries
Copy link
Collaborator

@andrew-farries andrew-farries commented Jun 23, 2025

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

@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 11:42 Inactive
@andrew-farries andrew-farries force-pushed the update-docs-for-latest-command branch from a97e606 to 6b5c628 Compare June 23, 2025 11:53
@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 11:53 Inactive
@andrew-farries andrew-farries force-pushed the update-docs-for-latest-command branch from 6b5c628 to fd24f13 Compare June 23, 2025 12:04
@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 12:04 Inactive
@andrew-farries andrew-farries force-pushed the update-docs-for-latest-command branch from fd24f13 to a68d8c1 Compare June 23, 2025 12:06
@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 12:06 Inactive
@andrew-farries andrew-farries force-pushed the update-docs-for-latest-command branch from a68d8c1 to 1c10463 Compare June 23, 2025 12:09
@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 12:09 Inactive
@andrew-farries andrew-farries force-pushed the update-docs-for-latest-command branch from 1c10463 to cd9dace Compare June 23, 2025 12:12
@github-actions github-actions bot temporarily deployed to Docs Preview June 23, 2025 12:12 Inactive
@andrew-farries andrew-farries marked this pull request as ready for review June 23, 2025 14:54
@andrew-farries andrew-farries requested review from divyenduz and kvch June 23, 2025 14:55
Copy link
Contributor

@divyenduz divyenduz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM ✅

andrew-farries added a commit that referenced this pull request Jun 30, 2025
Add a `pgroll latest url` command to the CLI. The command returns a
Postgres connection string with the `search_path` option set to the
latest version schema name. This can be used to set the connection
string for an application to work with the latest schema version.

By default, with no arguments, `pgroll latest url` will use the
connection string set via the global `--postgres-url` (or
`PGROLL_PG_URL` env var). If an argument is given to `pgroll latest
url`, the command will use that as the base connection string instead.

The resulting connection string sets the `search_path` by setting the
`options` parameter in the URL query string:

```
options=-c search_path='public_01_some_migration'
```

As described in the Postgres [libpq
documentation](https://www.postgresql.org/docs/current/libpq-connect.html).

## Examples

With no connection string argument, use the connection string used by
`pgroll` itself:

```bash
$ export PGROLL_PG_URL=postgres://postgres:postgres@localhost:5432?sslmode=disable
$ pgroll latest url

postgres://postgres:postgres@localhost:5432?options=-c%20search_path%3Dpublic_05_some_migration&sslmode=disable
```

Take the connection string as a command line argument:

```bash
$ pgroll latest url postgres://me:mypass@example.com:5432

postgres://me:mypass@example.com:5432?options=-c%20search_path%3Dpublic_05_some_migration
```

Like `pgroll latest migration` and `pgroll latest schema`, `pgroll
latest url` takes a `--local/-l` flag to take the latest version schema
name from a directory of migration files rather than the target
database. This allows for a connection string to be constructed offline,
without having to lookup the latest version schema name in the target
database.

```bash
$ pgroll latest url --local migrations/ postgres://me:mypass@localhost:5432

postgres://me:mypass@localhost:5432?options=-c%20search_path%3Dpublic_05_some_migration
```

The resulting connection string can be used directly as an argument to
tools like `psql` that accept a connection string on the command line:

```bash
psql $(pgroll . latest url)
```

Documentation for the new command is added in
#928

Closes #900
@andrew-farries andrew-farries merged commit 5cbaa73 into main Jun 30, 2025
30 checks passed
@andrew-farries andrew-farries deleted the update-docs-for-latest-command branch June 30, 2025 06:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants