Run and connect to AlloyDB Omni

This page describes how to run and connect to AlloyDB Omni after you install it on your own machine or deploy it to your Kubernetes cluster.

Before you begin

Single-server

Most of the commands on this page use the AlloyDB Omni CLI.

To install this command-line tool on your machine, see Install the AlloyDB Omni CLI.

Kubernetes

You need to install the AlloyDB Omni Kubernetes Operator onto your Kubernetes cluster to perform the tasks described on this page.

The Kubernetes-specific instructions on this page assumes basic familiarity with operating Kubernetes.

Run AlloyDB Omni

The procedures you use to run AlloyDB Omni depend on whether you're running AlloyDB Omni in a container on a single server, or on a Kubernetes cluster. This section divides its instructions between these deployment styles.

Single-server

Installing AlloyDB Omni sets up a system service called alloydb-dataplane that's configured to launch every time that your machine boots.

For basic control and monitoring of AlloyDB Omni, use the sudo alloydb command, as demonstrated in the following sections.

Kubernetes

To control and monitor AlloyDB Omni, update the manifests of your Kubernetes cluster, as demonstrated in the following sections.

Start AlloyDB Omni

Single-server

Caution: Make sure that the storage device containing the data directory has at least 20 GB of free space. If it doesn't, then attempting to start AlloyDB Omni might cause it to fill up all available space on the device, causing it to fail to launch.

sudo alloydb database-server start

Note: By default, AlloyDB Omni also starts when your machine boots.

To perform a test connection, see Connect using the containerized psql.

Kubernetes

Start a stopped database cluster by setting isStopped to false in its manifest definition.

You can perform this on the command line using kubectl:

kubectl patch dbclusters.alloydbomni.dbadmin.goog dbcluster-sample \
-p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge

Check the status of AlloyDB Omni

Single-server

sudo alloydb database-server status

Kubernetes

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME

Replace DB_CLUSTER_NAME with the name of your database cluster.

Stop AlloyDB Omni

Single-server

sudo alloydb database-server stop

Kubernetes

To stop a database cluster, set isStopped to true in its manifest definition.

You can perform this on the command line using kubectl:

kubectl patch dbclusters.alloydbomni.dbadmin.goog dbcluster-sample -p '{"spec":{"primarySpec":{"isStopped":true}}}' --type=merge

Disable startup launch

Running the following command prevents AlloyDB Omni from automatically starting when your machine boots.

Single-server

sudo systemctl disable alloydb-dataplane

Kubernetes

This task doesn't apply when using the AlloyDB Omni Kubernetes Operator.

Re-enable startup launch

Single-server

sudo systemctl enable alloydb-dataplane

Kubernetes

This task doesn't apply when using the AlloyDB Omni Kubernetes Operator.

Connect to AlloyDB Omni running on a single server

The AlloyDB Omni container includes its own copy of psql that lets you open an interactive SQL shell session with its database server.

You can also connect to AlloyDB Omni from outside the container, using the PostgreSQL-compatible software of your choice.

For information about connecting to an AlloyDB Omni database cluster running on a Kubernetes cluster, see Connect to AlloyDB Omni running on Kubernetes.

Connect using the containerized psql

To connect to the AlloyDB Omni database server using its own containerized copy of psql, run the following command:

Single-server

docker exec -it pg-service psql -h localhost -U postgres

This command connects you to the server as the postgres user role, and displays a postgres=# command prompt. You can now run psql commands and SQL queries.

To exit psql, run the \q command.

Connect using your own applications

Any application that works with PostgreSQL can also work with AlloyDB Omni, with no modification needed.

To connect to the AlloyDB Omni database server, use any PostgreSQL-compatible client or code library to connect to port 5432—the default PostgreSQL database server port—of the machine running AlloyDB Omni.

This works because the AlloyDB Omni container exposes its own port 5432 to the same port of the machine that it runs on.

After connecting to the database server, you can define, query, and modify your databases using DML and SQL queries by using standard PostgreSQL communication protocols.

Because AlloyDB Omni runs within your own environment, you can control how you connect to AlloyDB Omni. This includes allowing or restricting network access to this service according to the needs of your application, just as you would with an ordinary PostgreSQL server.

Connect to AlloyDB Omni running on Kubernetes

The AlloyDB Omni Kubernetes Operator allows connections to the database cluster from within the same Kubernetes cluster, optionally using certificates for authentication.

Connect using the preinstalled psql

You can make a test connection using a psql client already installed on the pod running the database.

To do this, run the following commands:

export DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -c database -- /bin/psql -h localhost -U postgres

Replace DB_CLUSTER_NAME with the name of your database cluster. It's the same database cluster name you declared when you created it.

After you enter the command, the database server prompts you for a password. Enter the password whose base64-encoded version you supplied as a Kubernetes secret when creating the database cluster. For example, if you created the database cluster with a secret of Q2hhbmdlTWUxMjM=, then the login password to use here is ChangeMe123.

The AlloyDB Omni Operator connects you to the server as the postgres user role and displays a postgres=# command prompt. You can now run psql commands and SQL queries.

To exit psql, run the \q command.

Connect from a separate pod in the same cluster

The pod running the AlloyDB Omni database cluster allows connections from within the same Kubernetes cluster, by default. As a best practice, we recommend securing all connections to the database cluster using TLS.

To provide your own server TLS certificate, specify a certificate secret when configuring your database cluster. If you do not specify a certificate secret, then the AlloyDB Omni Kubernetes Operator creates a TLS certificate secret for you, based on a certificate signed by a self-signed certificate authority. In either case, you can require your database client pod to require certificate validation on every connection, ensuring TLS security.

To establish secure database connections using TLS, perform the following actions:

• In the manifest that defines the pod making the client connections, specify a TLS certificate secret. It can be one of the following:

  • A TLS certificate secret that you have already created in your Kubernetes cluster. For more information about working with TLS certificate secrets in Kubernetes, see TLS Secrets.

  • The default certificate secret that the AlloyDB Omni Kubernetes Operator creates for you, named DB_CLUSTER_NAME-ca-cert, if you do not specify a TLS secret as part of your database cluster's manifest.

• Whenever your client pod connects to the database cluster, it must define the following environment variables prior to establishing the connection:

  • Set PGSSLMODE to "verify-ca".

  • Set PGSSLROOTCERT to the absolute path, on the client pod's filesystem, of the relevant ca.crt file.

The following example manifest shows how to configure a pod that installs the official PostgreSQL image, which includes the psql command-line client. The example presumes that you do not specify any TLS secret configuration in the manifest that defines your database cluster. Therefore, the AlloyDB Omni Kubernetes Operator uses the default TLS secret, which is named dbs-al-cert-DB_CLUSTER_NAME.

apiVersion: v1
kind: Pod
metadata:
  name: postgres
spec:
  containers:
  - image: "docker.io/library/postgres:latest"
    command:
      - "sleep"
      - "604800"
    imagePullPolicy: IfNotPresent
    name: db-client
    volumeMounts:
    - name: ca-cert
      mountPath: "/DB_CLUSTER_NAME-ca-cert"
      readOnly: true
  volumes:
  - name: ca-cert
    secret:
      secretName: dbs-al-cert-DB_CLUSTER_NAME
  restartPolicy: Always

Replace DB_CLUSTER_NAME with the name of your database cluster. It is the same database cluster name you declared when you created it.

You can now use the pod to securely connect to your database cluster using the following steps:

1. Determine the internal IP address of your database cluster:

   kubectl get dbclusters.alloydbomni.dbadmin.goog

   The output resembles the following:

   NAME              PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE
   DB_CLUSTER_NAME   IP_ADDRESS        Ready          DBClusterReady
   

   Take note of IP_ADDRESS, and use it in the following step.

2. Use psql to connect to your cluster from the client pod, setting the environment variables that enable and require TLS certificate verification:

   kubectl exec -it postgres -- bash
   PGSSLMODE="verify-ca" PGSSLROOTCERT=/DB_CLUSTER_NAME-ca-cert/ca.crt psql -h IP_ADDRESS -p 5432 -U postgres -d postgres

   Replace IP_ADDRESS with the internal IP address that you determined in the previous step.

What's next

• Manage and monitor AlloyDB Omni.