Updated on 2022-07-29 GMT+08:00

Overview

GaussDB(DWS) provides gs_dump and gs_dumpall to export required database objects and related information. To migrate database information, you can use a tool to import the exported metadata to a target database. gs_dump exports a single database or its objects. gs_dumpall exports all databases or global objects in a cluster. For details, see Table 1.

Table 1 Application scenarios

Application Scenario

Export Granularity

Export Format

Import Method

Exporting a single database

Database-level export

  • Export full information of a database.

    You can use the exported information to create a same database containing the same data as the current one.

  • Export all object definitions of a database, including the definitions of the database, functions, schemas, tables, indexes, and stored procedures.

    You can use the exported object definitions to quickly create a same database as the current one, without data.

  • Export data of a database.
  • Plain text
  • Custom
  • Directory
  • .tar

Schema-level export

  • Export full information of a schema.
  • Export data of a schema.
  • Export all object definitions of a schema, including the definitions of tables, stored procedures, and indexes.
Table-level export
  • Export full information of a table.
  • Export data of a table.
  • Export the definition of a table.

Exporting all databases in a cluster

Database-level export

  • Export full information of a cluster.

    You can use the exported information to create a same cluster containing the same databases, global objects, and data as the current one.

  • Export all object definitions of a cluster, including the definitions of tablespaces, databases, functions, schemas, tables, indexes, and stored procedures.

    You can use the exported object definitions to quickly create a same cluster as the current one, containing the same databases and tablespaces but without data.

  • Export data of a cluster.

Plain text

For details about how to import data files, see Using a gsql Meta-Command to Import Data.

Global object export
  • Export tablespaces.
  • Export roles.
  • Export tablespaces and roles.

gs_dump and gs_dumpall use -U to specify the user that performs the export. If the specified user does not have the required permission, data cannot be exported. In this case, you can set --role in the export command to the role that has the permission. Then, gs_dump or gs_dumpall uses the specified role to export data. See Table 1 for application scenarios and Data Export By a User Without Required Permissions for operation details.

gs_dump and gs_dumpall encrypt the exported data files. These files are decrypted before being imported to prevent data disclosure for higher database security.

When gs_dump or gs_dumpall is used to export data from a cluster, other users can still access (read data from and write data to) databases in the cluster.

gs_dump and gs_dumpall can export complete, consistent data. For example, if gs_dump is used to export database A or gs_dumpall is used to export all databases from a cluster at T1, data of database A or all databases in the cluster at that time point will be exported, and modifications on the databases after that time point will not be exported.

Obtain gs_dump and gs_dumpall by decompressing the gsql CLI client package.

Precautions

  • Do not modify an exported file or its content. Otherwise, restoration may fail.
  • If the number of objects (data tables, views, and indexes) in a database exceeds 500,000, you are advised to use gs_guc to configure the following parameters for CNs and DNs. This operation is not required if the parameter values are greater than the recommended ones.
    gs_guc set -N all -Z coordinator -Z datanode -I all -c 'max_prepared_transactions = 1000'
    gs_guc set -N all -Z coordinator -Z datanode -I all -c 'max_locks_per_transaction = 512'
  • For data consistency and integrity, gs_dump and gs_dumpall set a share lock for a table to be dumped. If a share lock has been set for the table in other transactions, gs_dump and gs_dumpall lock the table after the lock is released. If the table cannot be locked within the specified time, the dump fails. You can customize the timeout duration to wait for lock release by specifying the --lock-wait-timeout parameter.
  • During an export, gs_dumpall reads all tables in a database. Therefore, you need to connect to the database as a cluster administrator to export a complete file. When you use gsql to import scripts, cluster administrator permissions are also required to add users and user groups, and create databases.
  • By default, the definitions of all views in the GaussDB(DWS) database contain the prefix of table names or aliases (in tab.col format). Therefore, the definitions may be inconsistent with the original ones. As a result, the base table corresponding to the rebuilt view column is incorrect and an error is reported. However, this rarely happens. To prevent this problem, you are advised to set the GUC parameter behavior_compat_options to compat_display_ref_table when exporting view definitions, so the exported definitions are consistent with the original statements.