Skip to content

docs: update usage docs #934

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.

Sign up for GitHub

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
vjeeva merged 1 commit into from
May 4, 2026
Merged

docs: update usage docs #934

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 54 additions & 9 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ $ belt [OPTIONS] COMMAND [ARGS]...
* `dst-dsn`: Print a dsn to stdout that you can use to...
* `check-pkeys`: Print out lists of tables with and without...
* `check-connectivity`: Returns exit code 0 if pgbelt can connect...
* `revoke-logins`: Discovers all users in the db who can log...
* `restore-logins`: Grant permission to log in for any user...
* `revoke-logins`: Discovers all users who can log in and...
* `restore-logins`: Discovers all roles that currently have...
* `precheck`: Report whether your source database meets...
* `reset`: Reset an in-progress migration before...
* `dump-schema`: Dumps and sanitizes the schema from the...
Expand All @@ -40,6 +40,7 @@ $ belt [OPTIONS] COMMAND [ARGS]...
* `analyze`: Run ANALYZE in the destination database.
* `validate-data`: Compares data in the source and target...
* `sync`: Sync and validate all data that is not...
* `diff-sequences`: Compare source and destination sequence...
* `teardown-back-replication`: Stops pglogical replication from the...
* `teardown-forward-replication`: Stops pglogical replication from the...
* `teardown`: Removes all pglogical configuration from...
Expand Down Expand Up @@ -188,10 +189,8 @@ $ belt check-connectivity [OPTIONS] DC [DB]

## `belt revoke-logins`

Discovers all users in the db who can log in, saves them in the config file,
then revokes their permission to log in. Use this command to ensure that all
writes to the source database have been stopped before syncing sequence values
and tables without primary keys.
Discovers all users who can log in and revokes their permission.
Stateless — queries pg_roles each time rather than caching a user list.

Always excludes built-in service accounts (pglogical, rdsadmin, monitoring, etc.).
Use --exclude-user to exclude additional specific usernames.
Expand Down Expand Up @@ -225,10 +224,11 @@ $ belt revoke-logins [OPTIONS] DC [DB]

## `belt restore-logins`

Grant permission to log in for any user present in the config file. The user
must already have a password. This will not generate or modify existing
passwords for users.
Discovers all roles that currently have NOLOGIN and re-enables login for
them, excluding built-in service accounts and any roles specified via
--exclude-user / --exclude-pattern.

This is stateless — it does not rely on a previously saved user list.
Intended to be used after revoke-logins in case a rollback is required.


Expand All @@ -250,6 +250,8 @@ $ belt restore-logins [OPTIONS] DC [DB]
**Options**:

* `--json`: Output structured JSON instead of human-readable tables.
* `-e, --exclude-user TEXT`: Additional usernames to exclude from restoration (can be repeated).
* `-p, --exclude-pattern TEXT`: SQL LIKE patterns to exclude usernames (e.g. '%%myapp%%'). Can be repeated.
* `--help`: Show this message and exit.

## `belt precheck`
Expand Down Expand Up @@ -299,6 +301,12 @@ This command:
Note: sequence values are intentionally left unchanged. They only need to be
synchronized after cutover by running sync-sequences.

WARNING: --force skips the safety check that prevents resetting when the
destination is the same size or larger than the source. This is intended for
post-migration resets where SRC and DST are identical. Using --force on a
live migration where DST is genuinely the primary copy will result in
irreversible data loss.


Requires both src and dst to be not null in the config file.

Expand All @@ -318,6 +326,7 @@ $ belt reset [OPTIONS] DC [DB]
**Options**:

* `--json`: Output structured JSON instead of human-readable tables.
* `--force`: Skip the dataset-size failsafe that normally prevents reset when DST >= SRC. Use ONLY after a completed migration when you are certain the destination database should be wiped and all its up-to-date data discarded.
* `--help`: Show this message and exit.

## `belt dump-schema`
Expand Down Expand Up @@ -778,6 +787,42 @@ $ belt sync [OPTIONS] DC [DB]
* `--no-schema / --no-no-schema`: [default: no-no-schema]
* `--help`: Show this message and exit.

## `belt diff-sequences`

Compare source and destination sequence last_value for each targeted sequence.

Uses the **root** database user on both source and destination (same as
``diff-schemas``), not the pglogical user.

Destination values are highlighted green when they are greater than or equal to
source, and red otherwise.

Requires both src and dst to be not null in the config file.

If the db name is not given, runs for every database in the datacenter (same
pattern as ``diff-schemas``).


Requires both src and dst to be not null in the config file.

If the db name is not given run on all dbs in the dc.

**Usage**:

```console
$ belt diff-sequences [OPTIONS] DC [DB]
```

**Arguments**:

* `DC`: [required]
* `[DB]`

**Options**:

* `--json`: Output structured JSON instead of human-readable tables.
* `--help`: Show this message and exit.

## `belt teardown-back-replication`

Stops pglogical replication from the destination database to the source.
Expand Down
Loading