Run and connect to AlloyDB Omni

Select a documentation version:

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.

The Kubernetes-specific instructions on this page assume 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.

Start AlloyDB Omni

Single-server

To start a stopped AlloyDB Omni container, run either the docker container start command or the podman container start command:

Docker 

docker container start CONTAINER_NAME

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

Podman 

podman container start CONTAINER_NAME

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

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 DB_CLUSTER_NAME \
-p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge  -n DB_CLUSTER_NAMESPACE

Replace the following:

  • DB_CLUSTER_NAME: the name of this database cluster—for example, my-db-cluster.
  • DB_CLUSTER_NAMESPACE (Optional): the namespace you where created this database cluster—for example, my-db-cluster-namespace.

Check the status of AlloyDB Omni

Single-server

To check the status of all of the containers you have running, run either the docker container ls command or the podman container ls command:

Docker 

docker container ls

Podman 

podman container ls

If your AlloyDB Omni container is running, then its name will appear in the NAMES column of the output table. The corresponding row summarizes the container's state.

If the name of your container doesn't appear in the NAMES column, then your AlloyDB Omni is not running.

Kubernetes 

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME  -n DB_CLUSTER_NAMESPACE

Replace the following:

Stop AlloyDB Omni

Single-server

To stop a AlloyDB Omni container, run either the docker container stop command or the podman container stop command:

Docker 

 docker container stop CONTAINER_NAME

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

Podman 

 podman container stop CONTAINER_NAME

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

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 DB_CLUSTER_NAME -p '{"spec":{"primarySpec":{"isStopped":true}}}' --type=merge -n DB_CLUSTER_NAMESPACE

Replace the following:

  • DB_CLUSTER_NAME: the name of this database cluster—for example, my-db-cluster.
  • DB_CLUSTER_NAMESPACE (Optional): the namespace where you created this database cluster—for example, my-db-cluster-namespace.

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:

Docker 

  docker exec -it CONTAINER_NAME psql -U postgres

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

Podman 

  podman exec -it CONTAINER_NAME psql -U postgres

Replace CONTAINER_NAME with the name that you assigned to the AlloyDB Omni container when you installed it.

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, expose networking from the AlloyDB Omni docker container to your host machine by adding --network=host or -p 5432:5432 to your docker run or podman run command when you start AlloyDB Omni.

To select a custom port number, use -p [HOST_PORT]:5432 when you start AlloyDB Omni. Then, use any PostgreSQL-compatible client or code library to connect to port 5432 or the custom port number that you specified.

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 -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n DB_CLUSTER_NAMESPACE -c database -- 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.

You can skip setting the DB_CLUSTER_NAMESPACE, if you created the database cluster in the default namespace.

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 don't 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 don't 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
  namespace: DB_CLUSTER_NAMESPACE
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 the following:

  • DB_CLUSTER_NAME: the name of your database cluster. It is the same database cluster name you declared when you created it.
  • DB_CLUSTER_NAMESPACE (Optional): the namespace where you created your database cluster.

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 -n DB_CLUSTER_NAMESPACE

    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 -n DB_CLUSTER_NAMESPACE -- 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