Before importing data, you must:

1. [Create a database cluster](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-create-cluster.md.txt)
   to import the data to.

2. Upload the dump file to a storage bucket. See
   [Upload objects to storage buckets](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/upload-download-storage-objects.md.txt#upload_objects_to_storage_buckets)
   for instructions.

3. Grant the Database Service import service account read access to the dump file.
   See [Grant and obtain storage access](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/grant-obtain-storage-access.md.txt#grant_bucket_access).
   For example, you can grant the `project-bucket-object-viewer` role to the import service account.

   The Database Service system automatically creates this service account when the database cluster is created.
   The database cluster status includes both the name and namespace of the import service account.

   To retrieve the import service account's name and namespace, run the following command:

   ```bash
   kubectl --kubeconfig=MGMT_API_KUBECONFIG \
     get dbcluster.postgresql -n PROJECT_ID DATABASE_CLUSTER_NAME \
     -o jsonpath='{.status.serviceAccounts.import}'
   ```

   This command returns a JSON object containing the name and namespace details:
   `{"name":"postgresql-import-DATABASE_CLUSTER_NAME","namespace":"SERVICE_ACCOUNT_NAMESPACE"}`

WARNING: The database dump file must be created using `pg_dump` with an archive format compatible with `pg_restore`.
Plain SQL format dumps (default if no format option is specified) are **not** supported.

You can import a dump file into a database cluster using either the
GDC console or the Distributed Cloud CLI:

### Console

1. Open the **Database cluster overview** page in the GDC console to see
   the cluster that contains the database you are importing.

2. Click **Import** . The **Import data to accounts** panel opens.

3. In the **Source** section of the **Import data to accounts** panel, specify
   the location of the SQL data dump file you uploaded previously.

4. In the **Destination** field, specify an existing destination database for the import.

   > [!NOTE]
   > **Note:** You can leave this field empty if the dump file already specifies a destination. If the dump file specifies a destination and you fill the **Destination** field, the **Destination** field overrides the destination specified in the dump file.

5. Click **Import**. A banner on the GDC console shows the status of
   the import.

### gdcloud

1. Before using Distributed Cloud CLI,
   [install and initialize](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-install.md.txt) it.
   Then, [authenticate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt) with your
   organization.

2. Run the following command to import a dump file into a database:

   ```bash
   gdcloud database import sql DATABASE_CLUSTER BUCKET_NAME/sample.dmp \
       --project=PROJECT_NAME
   ```

   Replace the following:
   - <var translate="no">DATABASE_CLUSTER</var> with the name of the database cluster to import data into.
   - <var translate="no">BUCKET_NAME/SAMPLE.dmp</var> with the location of the dump file.
   - <var translate="no">PROJECT_NAME</var> with the name of the project that the database cluster is in.
3. Run the following command to check the status of the import:

   ```bash
   gdcloud database operations list --project=PROJECT_NAME --cluster=DATABASE_CLUSTER
   ```

### API

```yaml
apiVersion: postgresql.dbadmin.gdc.goog/v1
kind: Import
metadata:
  name: IMPORT_NAME
  namespace: USER_PROJECT
spec:
  dbclusterRef: DBCLUSTER_NAME
  dumpStorage:
    s3Options:
      bucket: BUCKET_NAME
      key: DUMP_FILE_PATH
    type: S3
```

Replace the following variables:

- `IMPORT_NAME`: the name of the import operation.
- `USER_PROJECT`: the name of the user project where the database cluster to import is created.
- `DBCLUSTER_NAME`: the name of the database cluster.
- `BUCKET_NAME`: the name of the object storage bucket that stores the import files.
- `DUMP_FILE_PATH`: the name of the object storage path to the stored files.