Skip to content

Commit 0c03713

Browse files
committed
Docs: improve README clarity and completeness
- Add link to gpbackup GitHub repository - Add requirement for database superuser privileges - Add best practice recommendation for migration steps - Improve wording for global objects handling section - Add table_test.go to example references These changes make the documentation more complete and user-friendly, helping users better understand the prerequisites and recommended approaches for using cbcopy.
1 parent e442aa7 commit 0c03713

File tree

1 file changed

+6
-3
lines changed

1 file changed

+6
-3
lines changed

README.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ cbcopy is an efficient database migration tool designed to transfer data and met
77
## How does cbcopy work?
88

99
### Metadata migration
10-
The metadata migration feature of cbcopy is based on gpbackup. Compared to GPDB's built-in `pg_dump`, cbcopy's main advantage is its ability to retrieve metadata in batches. While `pg_dump` fetches metadata one row or a few rows at a time, cbcopy retrieves it in batches. This batch processing approach significantly enhances performance, especially when handling large volumes of metadata, making it much faster than `pg_dump`.
10+
The metadata migration feature of cbcopy is based on [gpbackup](https://github.com/greenplum-db/gpbackup-archive). Compared to GPDB's built-in `pg_dump`, cbcopy's main advantage is its ability to retrieve metadata in batches. While `pg_dump` fetches metadata one row or a few rows at a time, cbcopy retrieves it in batches. This batch processing approach significantly enhances performance, especially when handling large volumes of metadata, making it much faster than `pg_dump`.
1111

1212
### Data migration
1313
Both GPDB and CBDB support starting programs via SQL commands, and cbcopy utilizes this feature. During data migration, it uses SQL commands to start a program on the target database to receive and load data, while simultaneously using SQL commands to start a program on the source database to unload data and send it to the program on the target database.
@@ -91,7 +91,9 @@ This will:
9191

9292
## Migrating Data with cbcopy
9393

94-
Before migrating data, you need to copy cbcopy_helper to the `$GPHOME/bin` directory on all nodes of both the source and target databases. Then you need to find a host that can connect to both the source database and the target database, and use the cbcopy command on that host to initiate the migration. By default, both metadata and data are migrated.
94+
Before migrating data, you need to copy cbcopy_helper to the `$GPHOME/bin` directory on all nodes of both the source and target databases. Then you need to find a host that can connect to both the source database and the target database, and use the cbcopy command on that host to initiate the migration. Note that database superuser privileges are required for both source and target databases to perform the migration.
95+
96+
By default, both metadata and data are migrated. You can use `--metadata-only` to migrate only metadata, or `--data-only` to migrate only data. Based on our best practices, we recommend migrating metadata first using `--metadata-only`, and then migrating data using `--data-only`. This two-step approach helps ensure a more controlled and reliable migration process.
9597

9698
### Database version requirements
9799
cbcopy relies on the "COPY ON SEGMENT" command of the database, so it has specific version requirements for the database.
@@ -122,7 +124,7 @@ cbcopy supports two data loading modes.
122124

123125
### Object dependencies
124126

125-
If the tables you are migrating depend on certain global objects (such as tablespaces), you have two options:
127+
If the tables you are migrating depend on certain global objects (such as tablespaces), there are two ways to handle this:
126128

127129
1. Include the `--with-global-metadata` option (default: false) during migration, which will automatically create these global objects in the target database.
128130

@@ -245,6 +247,7 @@ cbcopy --with-global-metadata --source-host=127.0.0.1 \
245247

246248
For more detailed examples, you can refer to our test files:
247249
- [basic_test.go](end_to_end/basic_test.go)
250+
- [table_test.go](end_to_end/table_test.go)
248251
- [tablespace_test.go](end_to_end/tablespace_test.go)
249252

250253
## cbcopy reference

0 commit comments

Comments
 (0)