Hello, I’m DocuDroid!
Submitting feedback
Thank you for rating our AI Search!
We would be grateful if you could share your thoughts so we can improve our AI Search for you and other readers.
GitHub

Overview of the ggcheckmigrate syntax

Pavel Semyonov

The ggcheckmigrate utility checks a Greengage DB 6 cluster for potential issues that could prevent a successful migration to Greengage DB 7. It reports the issues that need to be addressed before migration.

Synopsis

ggcheckmigrate [ { -d | --source-database } <string> ]
               [ { -h | --source-host } <string> ]
               [ { -p | --source-port } <int> ]
               [ { -u | --source-user } <string> ]
               [ { -H | --target-host } <string> ]
               [ { -P | --target-port } <int> ]
               [ { -U | --target-user } <string> ]
               [ [ { -N | --exclude-schema } <schema> ] [...] ]
               [ { --quiet | --debug | --verbose } ]

ggcheckmigrate -? | --help

ggcheckmigrate -v | --version

Description

ggcheckmigrate connects to a source Greengage DB 6 cluster and, optionally, a target Greengage DB 7 cluster. Both clusters can be local or remote.

The utility checks the source cluster for potential migration issues. For the complete list of checks, see the Checks section below.

When the target cluster is specified, it is used for a single check — the availability of the required libraries used by the source cluster.

By default, ggcheckmigrate checks all connectable databases in the source cluster. Use the --source-database option to check a single database instead. When enumerating databases, the utility requires the postgres or template1 database to be connectable.

Checks

The checks that ggcheckmigrate performs identify potential incompatibilities that should be investigated and resolved before migration. They do not replace testing the backup and restore procedure or validating the migrated applications.

ggcheckmigrate checks for the following potential migration issues:

  • Multi-column LIST partitioning.

  • Functions that use plpython2.

  • Views that use removed operators.

  • Views that use removed functions.

  • Views that use removed types.

  • Usage of removed data types abstime, reltime, tinterval, and unknown.

  • Storage parameters of partitioned append-optimized tables.

  • Return types of functions defined with EXECUTE ON.

  • Presence of all partitioning columns in unique indexes on partitioned tables.

  • Presence of START EXCLUSIVE or END INCLUSIVE range partition bounds for float, text, and numeric types.

  • Statement-level triggers.

  • Required libraries that are used by the source cluster but are unavailable on the target cluster (only when the target cluster is specified).

For more information about these issues and possible solutions, see SQL incompatibilities between Greengage DB 6 and 7.

Authentication

To connect to the source and target clusters, ggcheckmigrate uses their superuser accounts specified by the --source-user and --target-user options.

The passwords can be specified in the PostgreSQL password file (~/.pgpass) or provided using another supported authentication method. For example, ~/.pgpass can look as follows:

source.example.com:5432:*:source_admin:source_password
target.example.com:5432:postgres:target_admin:target_password

The PGPASSWORD environment variable can also be used to supply a password. For example, if the same password is used for both clusters:

$ PGPASSWORD=12345678 ggcheckmigrate \
  --source-host source.example.com --source-port 5432 --source-user source_admin \
  --target-host target.example.com --target-port 5432 --target-user target_admin
NOTE
  • ~/.pgpass must have the permissions 0600 (only the owner can read and write the file).

  • Using PGPASSWORD is not recommended in environments where other users can inspect process environment variables.

The utility also supports ident, peer, and trust authentication, subject to the authentication configuration of the relevant cluster and host.

Options

-h | --source-host <string>

Specifies the name or IP address of the source Greengage DB 6 cluster’s master host. Can be omitted when connecting locally; in this case, the Unix domain socket is used.

-p | --source-port <int>

Specifies the port on which the source Greengage DB 6 master accepts connections. If this option is omitted, the utility uses the PGPORT variable value if it is set or 5432 otherwise.

-u | --source-user <string>

Specifies the superuser account used to connect to the source cluster. If this option is omitted, the utility uses the PGUSER environment variable if it is set or the USER environment variable otherwise.

-d | --source-database <string>

Checks only the specified database in the source cluster.

-N | --exclude-schema <schema>

Excludes the specified schema from the check. Can be specified multiple times to exclude several schemas.

NOTE
  • If some leaf partitions of a partitioned table are stored in excluded schemas but the root table is not, these partitions are still checked by ggcheckmigrate.

  • Extension function libraries are checked even when their schema is excluded.

-H | --target-host <string>

Specifies the name or IP address of the target Greengage DB 7 coordinator host. The target cluster is used only to check the availability of required libraries used by the source cluster. This option must be specified together with --target-port.

-P | --target-port <int>

Specifies the port on which the target cluster accepts connections. This option is required when --target-host is specified.

-U | --target-user <string>

Specifies the superuser account used to connect to the target cluster. If this option is omitted, the utility uses the PGUSER environment variable if it is set or the USER environment variable otherwise. This option can be specified only when --target-host and --target-port are specified.

--quiet

Suppresses all output except warning or error messages.

--debug

Adds debug and verbose severity messages to the ggcheckmigrate output.

--verbose

Adds verbose severity messages to the ggcheckmigrate output.

-v | --version

Prints the ggcheckmigrate version.

-? | --help

Displays the help information about ggcheckmigrate.

Return codes

ggcheckmigrate has the following return codes:

  • 0 — checks completed successfully, no migration issues were found.

  • 1 — at least one migration issue was found.

  • 2 — error: the source cluster is not Greengage DB 6.

  • 3 — error: the target cluster is not Greengage DB 7.

  • 4 — invalid command-line parameters were supplied.

  • 5 — an error occurred when performing the checks.

A return code of 0 does not guarantee that migration will succeed. It indicates only that the utility did not detect any of the issues covered by its checks.

Examples

Check all connectable databases of the Greengage DB 6 cluster using the default connection settings (local):

$ ggcheckmigrate

Check the marketplace database on a remote Greengage DB 6 cluster:

$ ggcheckmigrate --source-host mdw --source-port 5432 --source-database marketplace

Exclude the staging and legacy schemas from the checks:

$ ggcheckmigrate --exclude-schema staging --exclude-schema legacy

Check possible issues (including the availability of required libraries) before migration to the specified target Greengage DB 7 cluster:

$ ggcheckmigrate \
    --source-host mdw --source-port 5432 --source-user source_admin \
    --target-host cdw --target-port 5432 --target-user target_admin