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.

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To install, run, and control the simplified installation method for AlloyDB Omni, you need the docker command-line program installed on your machine. For more information, see Install Docker Engine.

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.

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To install and run the simplified AlloyDB Omni installation method, see Preview a simplified AlloyDB Omni installation method.

While the AlloyDB Omni container is running, you control it using the docker command, 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

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

docker container start CONTAINER_NAME

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

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.

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

docker 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.

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

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

docker container stop CONTAINER_NAME

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

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.

Simplified Preview

This task doesn't apply when using the simplified AlloyDB Omni installation method.

Re-enable startup launch

Single-server

sudo systemctl enable alloydb-dataplane

Kubernetes

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

Simplified Preview

This task doesn't apply when using the simplified AlloyDB Omni installation method.

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

Simplified Preview

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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.

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.