ATTACH DATABASE

Syntax

ATTACH DATABASE <parentDB_name>
  [AS <new_branchDB_name>]
  [STORAGEID 'storage_id']
  [COMPUTEID 'compute_id']
  [READ ONLY];

Arguments

• new_branchDB_name: (optional) specifies a new name for the attached database while creating a branch. If you do not specify a new name for the branch, the system will create a default name as the <parent_DB_name> followed by <Branch_creation_time>.

• storage_id: (required if db_name is not unique) specifies the storage ID for the attached database. You can retrieve the value from the  STORAGE_ID  column in information_schema.MV_CLOUD_ATTACHED_DATABASES.

• compute_id: (required if db_name is not unique) specifies the compute ID for the attached database. You can retrieve the value from the COMPUTE_ID column in information_schema.MV_CLOUD_ATTACHED_DATABASES.

• read only: Allows viewing the data in the database but not to modify the data or database objects.

Examples

To attach an existing database DB01 in the read-write mode to a cluster, connect to the target cluster and run the following command:

ATTACH DATABASE db01;

To attach an existing database to a cluster in the read-only mode, run the following command:

ATTACH DATABASE db01 READ ONLY;

Remarks

• A database cannot have more than one read-write attachment.

• Attaching a database can be faster than restoring an equivalent database. This is because an attach of a database does not copy the data, as is the case with the restore of a database. Note that after a database is attached, queries may be slower for some time until data is cached.

• This command cannot be run on system databases.

• Databases with a large number of partitions cannot be attached to a small cluster. The engine automatically performs the following check: core count * 8 >= total number of partitions.

  • Here is an example of the error message when the total number of partitions is greater: Creating or attaching a database with 32 total partitions to a cluster with 2 total cores is not supported. Please use a larger cluster.

• SHOW DATABASES only lists the databases that are attached to the current cluster.