gpcopy命令详解

注：本文部分翻译自https://docs.vmware.com/en/VMware-Greenplum-Data-Copy-Utility/2.6/greenplum-copy/gpcopy.html

gpcopy实用程序将对象从源Greenplum数据库系统中的数据库复制到目标Greenplum数据库系统中的数据库。

语法

gpcopy
   { {-F | --full} |
     { {-d | --dbname} <database1>[,<database2> ... ] 
        {-D | --dest-dbname} <dest-db1>[,<dest-db2> ... ] ] } |
     {-t | --include-table} <db>.<schema>.<table>[,<db>.<schema1>.<table1> ... ] 
        [ --dest-table <db>.<schema>.<table>[,<db>.<schema1>.<table1> ... ] |
     {-T | --include-table-file} <table-file1>
        [{-T | --include-table-file} <table-file2>] ... ] | 
     --include-table-json <json-table-file1>
        [ --include-table-json <json-table-file2>] ... ] }
   [ {-m | --metadata-only} ]
   [  --no-ownership ]
   [ {-e | --exclude-table} <db>.<schema>.<table>[,<db>.<schema1>.<table1> ... ] ]
   [ {-E | --exclude-table-file} <table-file1> ]
      [ {-E | --exclude-table-file} <table-file2> ] ... ] ]

   { --dest-host <dest_host> [ --dest-port <dest_port> ]
      [ --dest-user <dest_user> ] [ --dest-mapping-file <host_ip_map_file> ]}
   [ --source-host <source_host> [ --source-port <source_port> ]
   [ --source-user <source_user> ] ]
   [ --enable-receive-daemon = {true | false }]
   [ --jobs <int> ]
   [ --snapshot <snapshot_id> ]
   [ {-o | --on-segment-threshold} <int> ]
   [ {-p | --parallelize-leaf-partitions} = { true | false} ] 
   [ --data-port-range <lower_port>-<upper_port> ]
   [ --ssl-cert <cert_file> --ssl-key <key_file>
       [ --ssl-ca <ca_file> ] [ --ssl-min-tls <min_version_str> ] ]

   { --skip-existing | --truncate | --drop | --append }
   [ {-a | --analyze} ]
   [ --no-compression ]
   [ --no-distribution-check ]
   [ --truncate-source-after [--yes ] ]
   [ {-v | --validate} <type> ]

   [ --dry-run ]
   [ --timeout <seconds> ]
   [ --dumper "" ]
   [ --quiet | --debug ]

gpcopy --version
gpcopy {-h | --help}

描述

gpcopy实用程序将数据库对象从源Greenplum数据库系统复制到目标系统。拷贝操作有以下几种:

• 使用–full选项复制Greenplum数据库系统。该选项将所有用户定义数据库的所有数据库对象(包括表、表数据、索引、视图、用户、角色、函数和资源队列)复制到不同的目标系统。

• 将一组用户定义的数据库表复制到目标系统。

  • –dbname选项复制所有用户定义的表、表数据，并从指定的数据库重新创建表索引。

  • –include-table --include-table-file或–include-table-json选项复制一组指定的用户定义的表、表数据，并重新创建表索引。

  • –exclude-table和–exclude-table-file选项排除一组指定的用户定义的表和要复制的表数据。

• 使用–metadata-only选项只复制数据库模式。

在运行gpcopy时，必须指定要从源数据库复制的数据以及如何管理目标数据库中的数据。

必须使用且只能使用以下选项中的一个来指定要从源数据库复制的数据:–full、–dbname、–include-table、–include-table-file或–include-table-json。

必须使用以下选项之一来指定如何管理目标数据库中的数据:–skip-existing、–truncate、–drop或–append。

如果同时指定–append和–validate选项，则如果目标表包含数据，源表数据的验证将失败。

如果指定了–truncate-source-after选项，则还必须指定–validate选项。当指定–truncate-source-after时，在复制表数据并验证目标表数据之后，gpcopy将截断源表。

选项

gpcopy提供了一系列选项来定义要复制的数据的范围。您可以选择选项来执行完整的Greenplum系统迁移、复制特定的数据库或表，或者使用SQL查询只复制表的一部分。其他选项使您能够排除复制某些表，或者更改复制表数据的目标数据库、模式或表名。特殊的–metadata-only命令gpcopy为选定的源表创建必要的模式，但不复制表数据。

必须使用以下选项中的至少一个–full、–dbname、–include-table、–include-table-file或–include-table-json。根据需要使用其他选项从副本中排除数据，或者为复制的表数据更改目标数据库、模式或表。

-F | --full
此选项执行将Greenplum Database源系统迁移到目标系统的操作。
迁移复制所有数据库对象，包括所有用户定义数据库的表、索引、视图、物化视图定义、角色、函数、用户定义类型(UDT)、资源队列和资源组。不复制默认数据库postgres、template0和template1。
该选项不能用–dbname、–include-table、–include-table-file或–include-table-json选项指定。

{-d | --dbname}
要复制的源数据库。若要将多个数据库复制到目标系统，请指定一个以逗号分隔的数据库列表，名称之间没有空格。所有用户定义的表和表数据都被复制到目标系统。
如果源数据库不存在，gpcopy将返回一个错误并退出。如果目标数据库不存在，则创建一个数据库。
对–full、–include-table、–include-table-file或–include-table-json选项无效。
或者，您可以使用–include-table、–include-table-file或–include-table-json选项复制一组表。

{-D | --dest-dbname}
若要将数据库复制到其他目标数据库，请指定目标数据库的名称。对于多个数据库，指定一个以逗号分隔的数据库列表，名称之间没有空格。数据库名称的数量必须与–dbname选项中指定的名称数量匹配。该实用程序按照列出的顺序将源数据库复制到目标数据库。在本例中，db1被复制到destdb1, db2被复制到destdb2, db3被复制到db3。
gpcopy --dest-host mdw-2 --dbname=db1,db2,db3 --dest-dbname=destdb1,destdb2,db3 --drop
如果源数据库不存在，gpcopy将返回一个错误并退出。如果目标数据库不存在，则创建一个数据库。

{-t | --include-table} ..

从源数据库系统复制一个或多个表。必须提供完全限定的表名(..

)。不能指定物化视图或系统编目表。对于依赖于其他表的表，还必须指定从属表。
若要复制多个表，请包含以逗号分隔的表名列表，不要使用空格，或使用正则表达式来描述一组表。可以选择使用–dest-table来更改数据库、模式或表名，将–include-table中的表数据复制到其中。
可以在完全限定表名的数据库、模式和表部分使用Go语言正则表达式来定义一组输入表。正则表达式模式必须用斜杠(//)括起来。例如，–include-table mytest.public.demo/. /指定公共模式下mytest数据库中所有以demo开头的表。
下面两个关于–include-table选项的示例是等效的。它们都指定了一组表，以demo开头，以0或多个数字结尾。
–include-table testdb.schema1.demo/[0-9]/
–include-table testdb.schema1./demo[0-9]*/
可以在–dest-table中引用全限定名的数据库部分中的正则表达式捕获组，以更改表数据的目标数据库、模式或表名。
注意:如果更改目标模式或表名，目标表必须存在，并且具有与源表完全相同的表结构;当目标表与源表不同时，gpcopy不会生成创建新目标模式或表所需的DDL。
如果源表不存在，gpcopy将返回一个错误并退出。
如果目标表或数据库不存在，则创建它。只复制表和表数据，不复制依赖对象。只有在指定–drop选项时才会重新创建索引。不复制依赖对象。
选项–full、–dbname、–include-table-file或–include-table-json不允许此选项。

–dest-table ..

(可选)。修改复制用–include-table定义的表中的数据的数据库、模式或表。
注意:如果更改目标模式或表名，目标表必须存在，并且具有与源表完全相同的表结构;当目标表与源表不同时，gpcopy不会生成创建新目标模式或表所需的DDL。
必须提供完全限定的表名(..

)。使用逗号分隔的列表(不含空格)或引用用–include-table定义的正则表达式捕获组来指定多个表。如果使用逗号分隔的表列表和–include-table，则在–dest-table列表中使用相同的数字位置来更改相应表数据的目标数据库、模式或表。例如，要只移动带有如下选项的第二个表
–include-table mytest.public.table1,mytest.public.table2
使用类似如下的选项:
–dest-table production.public.table1,production.public.table2

{-T | --include-table-file}
定义要复制的表和数据的文本文件的位置和名称。若要使用多个文件，请为每个文件指定此选项。
–include-table-file <> --include-table-file <>
在文本文件中，每行指定一个完全限定的表(database.schema.table)。不能指定视图、物化视图或系统编目表。对于依赖于其他表的表，还必须指定从属表。
可以使用Go语言正则表达式语法选择多个表。有关使用正则表达式选择表的信息，请参阅–dest-table选项。
该选项不能用–full、–dbname或–include-table选项指定。

–include-table-json
json格式文件的位置和名称，该文件定义要复制的表和数据。与–include-table-file使用的文本文件不同，JSON文件可以包含一个目标表名，用于更改表数据复制到的数据库、模式或表。

-m | --metadata-only
只创建命令指定的模式。数据不传输。
如果使用–full选项指定，gpcopy将复制完整的数据库模式，包括源数据库的所有表、索引、物化视图、视图、用户定义类型(UDT)和用户定义函数(UDF)。无数据传输。
如果使用–dbname选项指定数据库，或者使用–include-table --include-table-file或–include-table-json选项指定表，gpcopy将只创建表和索引。无数据传输。
此选项不能与——truncate选项一起使用。

–no-ownership
默认情况下，如果角色存在于目标数据库中，gpcopy会将表的所有者和特权信息从源数据库中的表复制到目标数据库中的表。如果指定–no-ownership，则不会将所有者和特权信息复制到目标表。目标数据库中表的所有者设置为gpadmin。
此选项不能与–full选项一起使用。

{-e | --exclude-table} ..

表从源数据库系统中排除，不能传输。必须指定完全限定的表名(..

)。
若要排除多个表，请指定以逗号分隔的表名列表。
可以使用Go语言正则表达式语法指定一组表。有关使用正则表达式的信息，请参阅–include-table选项。
只排除指定的表，不排除依赖对象。不能指定视图、物化视图或系统编目表。
该选项必须使用以下选项之一指定:–full、–dbname、–include-table、–include-table-file或–include-table-json。如果选项–exclude-table导致没有表可以复制，则不会在目标系统中创建数据库或模式。

{-E | --exclude-table-file}
包含要排除复制到目标系统的完全限定表名列表的文件的位置和名称。在文本文件中，每行指定一个完全限定的表(..

)。若要指定多个文件，请为每个文件指定此选项。
–exclude-table-file <> --exclude-table-file <>
在该文件中，可以使用Go语言正则表达式语法指定一组表。有关使用正则表达式的信息，请参阅–include-table选项。
如果源表不存在，gcopy将显示警告。
只排除指定的表。不能指定视图、物化视图或系统编目表。
该选项必须使用以下选项之一指定:–full、–dbname、–include-table、–include-table-file或–include-table-json。如果选项–exclude-table导致没有表要复制，则不会在目标系统中创建数据库或模式。

连接选项

以下选项指定目标和源Greenplum系统的连接信息。只有–dest-host是必需的。–jobs、–on-segment-threshold和–parallelize-leaf-partitions会影响用于数据传输的并发连接数。–data-port-range定义用于数据传输到目的段或目的协调器的端口。

–dest-host
必需的。目标Greenplum数据库协调器段主机名或IP地址。

–dest-mapping-file
可选的。是一个文本文件的位置和名称，该文件列出了所有目标Greenplum Database主机名及其相应的IP地址(协调器、备用协调器、主主机和镜像主机)。文件中的每一行都以这种格式列出了一个主机及其对应的IP地址:

host, IP

如果由于某种原因gcopy无法将目标主机名解析为相应的IP地址，请使用此选项。

–dest-port
目标Greenplum数据库协调器段端口号。如果没有指定–dest-port，那么默认值是5432。

–dest-user
用于连接到目标Greenplum协调器的用户ID。如果没有指定，默认为gpadmin。

–source-host
源Greenplum数据库协调器段的主机名或IP地址。如果没有指定，默认主机是运行gpcopy(127.0.0.1)的系统。

–source-port
源Greenplum数据库协调器端口号。如果不指定，默认为5432。

–source-user
用于连接到源Greenplum数据库系统的用户ID。如果没有指定，默认为gpadmin。

–ssl-cert
(当目标Greenplum数据库集群配置为使用SSL/TLS时需要。)SSL/TLS证书文件的文件系统位置。该文件必须位于目标Greenplum数据库集群中所有主机(协调器、段)上的相同位置。在指定证书文件时，还必须提供SSL/TLS私钥(–ssl-key)。

–ssl-key
(当目标Greenplum数据库集群配置为使用SSL/TLS时需要。)SSL/TLS私钥文件的文件系统位置。该文件必须位于目标Greenplum数据库集群中所有主机(协调器、段)上的相同位置。在指定私钥时，还必须提供SSL/TLS证书(–ssl-cert)。

–ssl-ca
(可选)。SSL/TLS证书颁发机构根证书文件的文件系统位置。当指定该文件时，该文件必须位于源Greenplum数据库集群中所有主机(协调器、段)上的相同位置。Gpcopy使用根证书颁发机构验证密钥和证书。

–ssl-min-tls
(可选)。在连接上请求的最小TLS版本。有效的< min_version_str >值是“1.0”,“1.1”,“1.2”、“1.3”。默认最低TLS版本为1.0。

–jobs
gpcopy并行运行的最大进程数。默认值是4。取值范围是1 ~ 64512。
选项–jobs产生2*+1个数据库连接。默认值为4，表示创建9个连接。
默认情况下，此选项可能会影响分区表的复制。有关gpcopy如何处理分区表的信息，请参阅–parallelize-leaf-partitions选项。
如果增加此选项，请确保为Greenplum Database系统配置了足够的最大并发连接值，以容纳gpcopy连接和其他并发连接(如用户连接)。请参阅Greenplum数据库服务器配置参数max_connections。
如果指定了–enable-receive-daemon = false和–data-port-range，–data-port-range端口范围指定的端口数必须大于或等于用–jobs创建的并行进程数。

–snapshot
指定gpcopy在其中运行复制操作的事务快照的标识符。

{-o | --on-segment-threshold}
标识gpcopy在何处(源和目标Greenplum数据库协调器或源和目标Greenplum数据库段实例)执行数据传输。有效值为-2、-1或大于0的正整数。
默认值为-1,gpcopy通过源和目的段实例复制所有表数据。
当指定值-2时，gpcopy通过源和目标Greenplum数据库协调器复制所有表数据。
或者，您可以指定标识行号阈值的正整数值。如果一个表包含这么多或更少的行，gpcopy将使用源和目标协调器复制表数据。如果表中的行数超过阈值，gpcopy将使用源和目标段实例复制数据。
注意:当您指定一个正整数值时，gpcopy使用源表统计信息来确定表的行数。如果源表没有被分析，gpcopy会假设该表是一个小表，忽略阈值设置，只使用协调器复制表数据。如果您的数据库包含没有统计数据的大型表，请将此选项设置为-1，以强制gpcopy使用Greenplum段实例复制表数据。

-p | --parallelize-leaf-partitions
并行复制分区表的叶子分区表，或者基于根分区表复制单个表。默认值为true，并行复制叶子分区表。若要将分区表复制为单个表，请将此选项设置为false。
–jobs选项指定gpcopy并行运行的最大进程数，并且可能影响并行复制的叶子分区的数量。
如果还指定了–validate选项，则该实用程序将在复制过程中验证每个叶子分区表，然后验证整个分区表。
如果JSON文件包含查询分区表的sql:键，则不能使用–include-table-json指定此选项。

–enable-receive-daemon = {true | false}
控制目的主机从源主机接收数据时是否使用单个端口。Gpcopy允许目标主机上的守护进程在从源主机接收数据时使用单个端口。默认为true，使用单个端口。
当使用单个端口并且指定了–data-port-range时，gpcopy将在–data-port-range指定的范围内选择端口。否则，gcopy将使用可用的端口。

–data-port-range -
在Greenplum数据库目标主机上用于数据传输的一系列端口号。这适用于目标段主机，或者，如果使用协调器段传输数据，则仅适用于协调器段主机。Gpcopy使用范围(包括范围)中指定的第一个可用端口。必须大于等于1024(避免预留系统接口)，必须大于1024。
如果没有指定–data-port-range，那么gcopy使用任何可用的端口。
如果指定了该选项并且–enable-receive-daemon=false，则该范围指定的端口数必须大于或等于使用–jobs创建的并行进程数。

–timeout
在源系统和目标系统都准备好进行数据传输之前等待的最大时间(以秒为单位)。缺省值是30秒。值为0使超时失效。

示例

该命令使用–full选项将源系统中所有用户创建的数据库复制到目标系统。并删除表，如果它已经存在于目标中，则重新创建它。

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

该命令使用–dbname选项将源系统中的指定数据库复制到目标系统。truncate选项在从源表复制表数据之前截断表数据。

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

该命令使用–include-table选项将源系统中的指定表复制到目标系统。如果表已经存在于目标数据库中，那么–skip-existing选项将跳过该表。

gpcopy --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 --skip-existing

这个命令将表从源数据库复制到目标系统，不包括在/home/ guser /mytables中使用–exclude-table-file选项指定的表中指定的表。–truncate选项将截断目标系统中已经存在的表。使用–analyze和–validate count选项，该实用程序对复制的表执行analyze操作，并通过比较源表和目标表之间的行数来验证复制的表数据。

gpcopy --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 --analyze --validate count

该命令指定–full和–metadata-only选项，用于从所有源数据库复制完整的数据库模式，包括所有表、索引、视图、用户定义类型(UDT)和用户定义函数(UDF)。–drop选项指定如果表在源数据库和目标数据库中都存在，则在再次创建表之前将表删除到目标数据库中。

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

该命令使用–dbname选项将源系统中的指定数据库复制到目标系统，并使用–jobs选项指定8个并行进程。该命令指定–truncate选项，如果表已经存在于目标数据库中，则截断表并重新创建它，并使用2000-2010范围内的端口用于并行进程连接。

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

该命令使用–dbname选项将源系统中的指定数据库复制到目标系统，并使用–jobs选项指定16个并行进程。–truncate选项将截断表，并在目标数据库中已经存在的情况下重新创建它。–truncate-source-after选项在源数据库中的表数据在目标数据库中验证之后，截断源数据库中的表。

gpcopy --source-host mytest --source-port 1234 --source-user gpuser \
   --dest-host demohost --dest-port 1234 --dest-user gpuser \
   --dbname database1 --truncate --jobs 16 --truncate-source-after --validate count