This page describes how to use the Database Service
to create and manage databases in Google Distributed Cloud (GDC) air-gapped.

## Authorization and roles

Users must be authorized to access the Database Service. Authorization is
required to access Database Service with both the GDC console and the
Distributed Cloud CLI.

> [!NOTE]
> **Note:** Authorization to access the Database Service is distinct from authorization to access the databases managed by Database Service. Refer to your database management system (DBMS) documentation for guidance on controlling access to databases.

The following roles grant permissions to users:

Project Viewer (`project-viewer`)
:   Users with this role can access the GDC console and the
    Distributed Cloud CLI.

Database Project Viewer(`project-db-viewer`)
:   Users with this role can view database clusters.

Database Project Editor (`project-db-editor`)
:   Users with this role have the capabilities conferred by `project-db-viewer`
    and can also edit database clusters.

Database Project Admin (`project-db-admin`)
:   Users with this role have the capability conferred by `project-db-editor` and
    can also create and delete database clusters.

Bucket Object Project Viewer (`project-bucket-object-viewer`)
:   Users with this role can use the storage browser in the Database Service
    interface in the GDC console. This interface is used to specify files
    for database imports and to specify destinations for files generated by
    database exports.

Project Monitoring Viewer (`project-monitoring-viewer`)
:   Users with this role can access the monitoring instance. See [Observe metrics](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-view-metrics.md.txt) for
    more information about observing Database Service metrics. You
    should only grant this role to users who need to access the monitoring instance.

Maintenance Policy Project Admin (`project-mp-admin`)
:   Users with this role have the capabilities conferred by both
    `project_mp_editor` and `project_mpb_editor` roles, so they can create, edit,
    and delete both maintenance policies and maintenance policy bindings.

Maintenance Policy Project Viewer (`project-mp-viewer`)
:   Users with this role can view maintenance policies.

Maintenance Policy Project Editor (`project-mp-editor`)
:   Users with this role have the capabilities conferred by the
    `project_mp_viewer` role, and can also create, edit, and delete maintenance
    policies.

Maintenance Policy Binding Project Viewer (`project-mpb-viewer`)
:   Users with this role can view maintenance policy bindings.

Maintenance Policy Binding Project Editor (`project-mpb-editor`)
:   Users with this role have the capabilities conferred by the
    `project_mpb_viewer` role, and can also create, edit, and delete maintenance
    policy bindings.

## Available database engines

The following database engines are available to use in a GDC
environment:


\| Database \| Versions \|
\|---\|---\|
\| PostgreSQL \| 13, 14, 15 \|

## Create a database cluster

> [!IMPORTANT]
> **Important:** It is recommended that you have your Platform Administrator [create a backup repository](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-back-repo.md.txt) named `dbs-backup-repository` prior to creating your first database. Confirm with your administrator the existence of a proper backup repository, and that they have followed the steps to [validate a backup](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-back-repo.md.txt#verify-backup). Once confirmed, you can enable the backup during the creation of your database cluster.

A user with the Database Project Admin role must perform the following steps.
Use
either the GDC console or the Distributed Cloud CLI to create database
clusters.

> [!NOTE]
> **Note:** By default, disk volumes use the standard storage class `standard-rwo`.

### Console

1. From the main menu, choose **Database Service**.
2. Click **Create Database Cluster**.
3. In the **Choose a database engine** dialog, choose a
   [database engine](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-create-cluster.md.txt#available-db-engines).

4. In the **Configure your cluster** dialog, specify the cluster
   ID, password, and database version. You can enable backups and configure
   the backup retention period.

5. You can enable high
   availability for your database cluster. If enabled, the Database Service
   provisions a standby instance in the same zone as your primary instance
   to protect against failure. See [High availability](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/db-configure-ha.md.txt)
   for more information.

6. In the **Configure your primary instance** dialog, specify the CPU,
   memory, and storage capacity of the primary instance of the database
   cluster. We recommend you choose enough memory to hold your largest table.

7. Click **Create** . Creating the database cluster can take a few minutes.
   Check the status of the cluster from the **Cluster overview** page. The
   status changes from *Creating* to *Ready* when the cluster is ready.

### 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 create a database cluster:

   ```bash
   gdcloud database clusters create CLUSTER_NAME \
       --database-version DB_VERSION \
       --admin-password ADMIN_PASSWORD
   ```

   Replace the following variables:
   - `CLUSTER_NAME` with the name for the new cluster.
   - `DB_VERSION` with the version string for the new cluster. For example, `POSTGRESQL_13`, `POSTGRESQL_14` or `POSTGRESQL_15`
   - `ADMIN_PASSWORD` with the administrator password for the new cluster.
3. For more information on configuring the CPU, memory, and storage
   resources for the database cluster, configuring backup, enabling high
   availability, and for other available options, run:

   ```bash
   gdcloud database clusters create --help
   ```

### API

```yaml
  apiVersion: v1
  kind: Secret
  metadata:
    name: db-pw-DBCLUSTER_NAME
    namespace: USER_PROJECT
  type: Opaque
  data:
    DBCLUSTER_NAME: "BASE64_PASSWORD"
  ---
  apiVersion: postgresql.dbadmin.gdc.goog/v1
  kind: DBCluster
  metadata:
    name: DBCLUSTER_NAME
    namespace: USER_PROJECT
  spec:
    primarySpec:
      adminUser:
        passwordRef:
          name: db-pw-DBCLUSTER_NAME
      version: "DB_VERSION"
      resources:
        memory: DB_MEMORY
        cpu: DB_CPU
        disks:
        - name: DataDisk
          size: DB_DATA_DISK
```

1. Replace the following variables:

   - `DBCLUSTER_NAME`, the name of the database cluster.
   - `USER_PROJECT`, the name of the user project where the database cluster will be created.
   - `BASE64_PASSWORD`, the base64 encoding of the database's administrator password.
   - `DB_VERSION`, the version of the database engine.
   - `DB_MEMORY`, the amount of memory allocated to the DB Cluster, for example `5Gi`.
   - `DB_CPU`, the amount of CPUs allocated to the DB Cluster, for example `2`.
   - `DB_DATA_DISK`, amount of space allocated to the DB Cluster, for example `10 Gi`.
2. [Create a DBS `BackupPlan` resource](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/enable-dbs-backup.md.txt) in the same namespace to enable backups.