cbcopy

Copy utility for migrating data from Greenplum Database to SynxDB, or between SynxDB clusters.

Synopsis

cbcopy [flags]

Description

The cbcopy utility copies database objects from a source database system to a destination system. You can perform one of the following types of copy operations:

Copy a SynxDB system with the --full option. This option copies all database objects including, tables, table data, indexes, views, users, roles, functions, and resource queues for all user-defined databases to a different destination system.
Copy a set of user-defined database tables to a destination system.
- The --dbname option copies all user-defined tables, table data, and re-creates the table indexes from specified databases.
- The --include-schema, --include-table, or --include-table-file option copies a specified set of user-defined schemas or tables.
- The --exclude-table and --exclude-table-file options exclude a specified set of user-defined tables and table data to be copied.
Copy only the database schemas with the --metadata-only option.

Prerequisites

The user IDs for connecting to the source and destination systems must have appropriate access to the systems.

When the --full option is specified, resource groups and table spaces are copied, however, the utility does not configure the destination system. For example, you must configure the system to use resource groups and create the host directories required for the tablespaces.

General Settings

The following settings display basic information about the cbcopy utility or control the amount of information displayed for copy operations.

`--help`

Display help information and exit (default: false).

`--version`

Display the application version and exit (default: false).

`--debug`

Enable debug-level log messages for troubleshooting (default: false).

`--verbose`

Enable verbose logging for detailed output (default: false).

`--quiet`

Suppress informational logs; only show warnings and errors (default: false).

Source Cluster Settings

cbcopy provides a range of options to define the scope of data that is copied from the source cluster. You can choose options to perform a full cluster migration or to copy specific databases or tables. Additional options enable you to exclude certain tables from being copied.

Use one of the options --dbname, --schema, --include-table, or --include-table-file, or use the migration option --full to copy all data in the cluster. Use additional options as needed to exclude data from the copy.

`--source-host <host_or_ip>`

The host name or IP address of the source cluster master segment (default: 127.0.0.1).

`--source-port <port>`

Port number for the source database master segment (default: 5432).

`--source-user <user_id>`

User ID to use to connect to the source database (default: gpadmin).

`--dbname <database[,...]>`

Comma-separated list of databases to migrate from the source. Copies all the user-defined tables and table data from the source system.

`--schema <database.schema[,...]>`

Comma-separated list of schemas to migrate using the format: database.schema.

`--include-table <database.schema.table[,...]>`

Comma-separated list of specific tables to migrate using the format: database.schema.table.

`--include-table-file <file_name>`

Migrate tables listed in the specified file_name. Specify one table per line in the file, using the format: database.schema.table.

`--exclude-table <database.schema.table[,...]`

Exclude specific tables from migration. Use a comma-separated list with the format: database.schema.table.

`--exclude-table-file <file_name>`

Exclude tables listed in the specified file_name. Specify one table per line in the file, using the format: database.schema.table.

Destination Database Settings

Options in this category specify connection details for the destination cluster, and provide options for mapping source databases, schemas, and tables to destination databases, schemas, and tables.

`--dest-host <host_or_ip>`

The host name or IP address of the destination cluster master segment (default: 127.0.0.1).

`--dest-port <port>`

Port number for the destination database master segment (default: 5432).

`--dest-user <user_id>`

User ID to use to connect to the destination database (default: gpadmin).

`--dest-dbname <database[,...]>`

Comma-separated list of target databases in the destination cluster. Use this option to copy a database to a different destination database. The number of database names provided with this option must match the number of names specified in the --dbname option. The utility copies the source databases to the destination databases in the listed order.

`--dest-schema <database.schema[,...]>`

Comma-separated list of target schemas in the destination cluster. Use this option to copy to a different destination schema. The number of schemas provided with this option must match the number of schemas specified in the --schema option.

`--schema-mapping-file <file_name>`

File that maps source schemas to target schemas using the format: source_db.schema,dest_db.schema.

`--dest-table <database.schema.table[,...]>`

Specifies new table names for migrated tables. The number of tables provided with this option must match the number of tables specified in the --include-table option.

`--dest-table-file <file_name>`

File containing new table names for migration. The number of tables defined in the file must match the number of tables specified in the file provided to --include-table-file.

Data Migration Controls

Options in this category specify whether cbcopy migrates data as well as metadata, and how the utility handles existing data in the destination cluster.

`--full`

Migrates the entire data cluster, including all databases, schemas, and tables (default: false).

`--data-only`

Migrates only the table data; skips metadata like schema definitions (default: false).

`--metadata-only`

Migrates only metadata (schemas, tables, roles); excludes table data (default: false).

`--global-metadata-only`

Migrates global metadata (roles, tablespaces) without table data (default: false).

`--with-global-metadata`

Include global objects (roles, tablespaces) during migration (default: false).

`--append`

Appends data to existing tables in the destination (default: false).

`--truncate`

Clears (truncates) existing data in destination tables before migration (default: false).

`--validate`

Validates data consistency after migration (default: true).

Performance Tuning & Parallelism

Options in this category affect the number of jobs and the copy mode that cbcopy uses to migrate data.

`--copy-jobs <count>`

Maximum number of tables to migrate concurrently (1-512, default: 4).

`--metadata-jobs <count>`

Maximum number of concurrent metadata restore tasks (1-512, default: 2).

`--on-segment-threshold <count>`

Threshold (row count) for switching to direct coordinator copy mode (default: 1000000).

Advanced Settings

These less-frequently-used options provide additional control over mapping data to the destination cluster, provide compression options, or control connectivity options for the destination cluster.

`--owner-mapping-file <file_name>`

File that maps source roles to target roles using the format: source_role,dest_role.

`--dest-tablespace <tablespace>`

Create all migrated objects in the specified tablespace in the destination cluster.

`--tablespace-mapping-file <file_name>`

File that maps source tablespaces to destination tablespaces using the format: source,dest.

`--compression`

Transfers compressed data instead of uncompressed/plain data (default: false).

`--data-port-range`

Port range for data transfer during migration (format: start-end) (default: 1024-65535).

Examples

This command copies all user created databases in a source system to a destination system with the --full option.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
    --dest-host demohost --dest-port 1234 --dest-user gpuser \
    --full

This command copies the specified databases in a source system to a destination system with the --dbname option. The --truncate option truncates the table data before copying table data from the source table.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --dbname database1,database2 --truncate

This command copies the specified tables in a source system to a destination system with the --include-table option.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --include-table database.schema.table1,database.schema.table2

This command copies the tables from the source database to the destination system, excluding the tables specified in /home/gpuser/mytables with the --exclude-table-file option. The --truncate option truncates tables that already exist in the destination system.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --dbname database1 --exclude-table-file /home/gpuser/mytables \
   --truncate

This command specifies the --full and --metadata-only options to copy the complete database schema, including all tables, indexes, views, user-defined types (UDT), and user-defined functions (UDF) from all the source databases. No data is copied.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --full --metadata-only

This command copies the specified databases in a source system to a destination system with the --dbname option and specifies 8 parallel processes with the --copy-jobs option. The command uses ports in the range 2000-2010 for the parallel process connections.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --dbname database1,database2 --truncate --copy-jobs 8 --data-port-range 2000-2010

This command copies the specified database in a source system to a destination system with the --dbname option and specifies 16 parallel processes with the --copy-jobs option. The --truncate option truncates the table if it already exists in the destination database.

cbcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --dbname database1 --truncate --copy-jobs 16

SynxDB 2 Documentation