Connect to a database cluster

By default, a database cluster only allows connection from within the user cluster and the same project.

To enable connections to all database clusters in your project from another project, see Enable cross-project connections.

To enable connections to a database cluster from IP addresses outside your GDC organization, see Enable external connections.

Sign in to the GDC console with an account bound to the project-db-admin role to find the following information for connecting to your database cluster. This information is in the Connectivity section of the Database Service page.

These steps include an example for connecting to the database using psql. The exact steps will vary depending on the client software you choose.

Console

  1. Navigate to the Connectivity section of the Database Service page for the database cluster. This page includes:

    • The password of the administrator account (the username is dbsadmin)
    • Hostname and port number of the database cluster's primary endpoint
    • If the database cluster allows external connection from outside of the organization.
    • A psql command for connecting to the cluster (for PostgreSQL and AlloyDB Omni database clusters)
    • A string for connecting to the cluster with Java Database Connectivity (JDBC) (for Oracle database clusters)
    • A link to download the certificate authority (CA) certificate of the database cluster

  2. Download the CA certificate from the GDC console in the Connectivity section of the Database Service page for your database cluster.

  3. Configure your client to use the CA certificate to verify the database. For psql clients, set the PGSSLROOTCERT env variable to the path of the certificate file and the PGSSLMODE env variable to your preference:

    export PGSSLROOTCERT=path/to/accounts_cert.pem
export PGSSLMODE="verify-full"

  4. Connect to the database from your client software. If you're using psql, run the following command:

    PGPASSWORD=DB_PASSWORD psql -h DB_HOSTNAME -p PORT -U USERNAME -d postgres

Replace the following variables:

  • path/to/: the path to the accounts_cert.pem certificate.
  • DB_PASSWORD: the password from the console.
  • DB_HOSTNAME: the database hostname from the console.
  • DB_PORT: the database port number from the console.
  • DB_USERNAME: the database username from the console.

API

  1. Retrieve the database endpoint from the database cluster status:

    kubectl get dbcluster.DBENGINE_NAME.dbadmin.gdc.goog DBCLUSTER_NAME -n USER_PROJECT -o=jsonpath='{.status.primary.url}'

  2. Download the CA certificate from the Kubernetes secret:

    kubectl get secret dbs-certificates -n USER_PROJECT -o json | jq -r '.data."dbs-DBENGINE_SHORT_NAME-cert-DBCLUSTER_NAME"' | base64 -d > path/to/ca.crt

  3. Configure your client to use the CA certificate to verify the database. For psql clients, you can set the PGSSLROOTCERT env variable to the path of the certificate file and the PGSSLMODE env variable to your preference:

    export PGSSLROOTCERT=path/to/accounts_cert.pem
export PGSSLMODE="verify-full"

  4. Connect to the database from your client software. If you're using psql, run the following command:

    PGPASSWORD=DB_PASSWORD psql -h DB_HOSTNAME -p DB_PORT -U DB_USERNAME -d postgres

Replace the following variables:

  • DBENGINE_NAME: the name of the database engine. This is one of alloydbomni, postgresql, or oracle.
  • USER_PROJECT: the name of the user project where the database cluster was created.
  • DBENGINE_SHORT_NAME: the abbreviated name of the database engine. This is one of al (AlloyDB Omni), pg (PostgreSQL), or ora (Oracle).
  • DBCLUSTER_NAME: the name of the database cluster.
  • path/to/: the path to the database CA certificate.
  • DB_PASSWORD: database password for administrator user.
  • DB_HOSTNAME: the hostname from the database cluster status.
  • DB_PORT: the database port number from the database cluster status.
  • DB_USERNAME: with the database username (default is dbsadmin).