Customize your AlloyDB Omni installation

Select a documentation version:

This page describes how to customize your AlloyDB Omni installation, which is deployed through a container image that supports different forms of customization. This page shows some common customizations.

Enable and disable AlloyDB Omni telemetry

AlloyDB Omni telemetry implements a lightweight client agent that runs only in the AlloyDB Omni container image. This agent periodically collects a set of basic, pseudonymous metrics and sends them to a Google-managed endpoint.

Because AlloyDB Omni is a downloadable product that's offered at no charge, this telemetry provides Google with essential, non-personally identifiable information (non-PII) metrics regarding the generic adoption and deployment environments of running instances. This data helps inform product development and support prioritization.

Collected metrics include the following:

  • Unique installation ID (pseudonymized UUID)
  • AlloyDB Omni version and PostgreSQL major version
  • Host system information like CPU count, RAM, and uptime

Disable telemetry reporting

To prevent the telemetry agent from running and reporting usage metrics, set the PostgreSQL configuration parameter omni_enable_telemetry to off. You can disable the telemetry agent by setting the telemetry flag in the postgresql.conf file or by setting the flag at runtime using ALTER SYSTEM.

Set the telemetry flag in the postgresql.conf file

To modify the PostgreSQL configuration file in your container's persistent data directory, follow these steps:

  1. Locate the postgresql.conf file in your database's data directory ($PGDATA).

  2. Disable AlloyDB Omni telemetry.

    omni_enable_telemetry = off

  3. To apply the change, restart your AlloyDB Omni container. The telemetry agent stops collecting and sending usage metrics to Google.

Set the telemetry flag at runtime using ALTER SYSTEM

To set the telemetry flag and persist the change across restarts, follow these steps:

  1. Connect to your AlloyDB Omni instance using psql:

    psql -h HOST -U USER -d DATABASE

    Make the following replacements:

    • HOST: the hostname or IP address of your AlloyDB Omni instance—for example, 127.0.0.1.
    • USER: the database user that you want to connect as—for example, postgres.
    • DATABASE: the database that you want to connect to—for example, postgres.

  2. Run the following command:

    ALTER SYSTEM SET omni_enable_telemetry = 'off';

  3. Reload the configuration or restart the instance. In some container setups, you might need to restart your instance to make sure that the change is fully picked up by the background worker.

    SELECT pg_reload_conf();

    The telemetry agent stops collecting and sending usage metrics to Google.

Enable telemetry reporting

If you previously disabled AlloyDB Omni telemetry, you can re-enable it by setting the omni_enable_telemetry flag to on. You enable the telemetry agent by setting the flag in the postgresql.conf file or by setting the flag at runtime using ALTER SYSTEM.

Set the telemetry flag in the postgresql.conf file

  1. Locate the postgresql.conf file in your database's data directory ($PGDATA).

  2. Set the following line:

    omni_enable_telemetry = on

  3. To apply the change, restart your AlloyDB Omni container.

Set the telemetry flag at runtime using ALTER SYSTEM

  1. Connect to your AlloyDB Omni instance using psql.

  2. Run the following command:

    ALTER SYSTEM SET omni_enable_telemetry = 'on';

  3. To apply the change, restart your AlloyDB Omni container.

    docker restart CONTAINER_NAME

    Make the following replacement:

    • CONTAINER_NAME: The name of your AlloyDB Omni container—for example, my-omni-1.

Check AlloyDB Omni telemetry status

You can check the status of the AlloyDB Omni telemetry agent, including whether it's enabled or running. You can also check telemetry agent activity.

Check if the telemetry agent is enabled or disabled

To check the status of the telemetry setting, follow these steps:

  1. Connect to your instance.
  2. Run the following:
SHOW omni_enable_telemetry;

The output returns on or off, depending on whether you disabled or enabled AlloyDB Omni telemetry.

Check if the telemetry agent is running

To check whether the telemetry agent is running, run the following command in the container host:

docker top CONTAINER_NAME

Make the following replacement:

  • CONTAINER_NAME: The name of your AlloyDB Omni container—for example, my-omni-1.

If telemetry is enabled and running, the output contains a line with the text postgres: omni telemetry worker.

Check telemetry agent activity

To check the activity of the telemetry agent, run the following command in the container host:

docker logs CONTAINER_NAME 2>&1 | grep telemetry

Make the following replacement:

  • CONTAINER_NAME: The name of your AlloyDB Omni container—for example, my-omni-1.

If the telemetry agent is running, the logs contain messages similar to the following:

LOG:  [telemetry_agent_worker.cc:143]  Started telemetry worker
LOG:  [telemetry_agent_worker.cc:161]  Running telemetry reporting agent
telemetry_agent: Uploading telemetry data to https://cloud.google.com/log.

Mount an external data directory

By default, the command in Quickstart: Install AlloyDB Omni stores the database data in an area managed by Docker or Podman. This is convenient for getting started but makes it difficult to find and use the data directory. Instead, you can set up a bind mount to map the data directory to a known location on your disk.

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Replace the following variables:

  • CONTAINER_NAME: Name that you used for your container. For example, my-omni-1.
  • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
  • DATA_DIR: Host directory path that your data is stored in.
  • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.
  • IMAGE_TAG: Use 16.9.0 for the latest Debian image or 16.9.0-ubi for the latest UBI image.

Enable ulimits

The ulimit parameters specify process limits that the Docker or Podman container can use. For optimal performance, we recommend that you set the following ulimits:

  • nice=-20:-20: AlloyDB Omni adjusts process priorities to allow critical PostgreSQL processes to run with higher priority. The higher priority gives the processes a bigger allocation of available CPUs. To adjust process priorities, specify --ulimit=nice=-20:-20, which removes limitations for the AlloyDB Omni container.

  • memlock=-1:-1: AlloyDB Omni performs automatic memory management. Setting --ulimit=memlock=-1:-1 allows the database to better control how memory pages are swapped in and out, which can result in better performance.

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--ulimit=nice=-20:-20 --ulimit=memlock=-1:-1 \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--ulimit=nice=-20:-20 --ulimit=memlock=-1:-1 \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--ulimit=nice=-20:-20 --ulimit=memlock=-1:-1 \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--ulimit=nice=-20:-20 --ulimit=memlock=-1:-1 \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Replace the following variables:

  • CONTAINER_NAME: Name you used for your container. For example, my-omni-1.
  • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
  • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.
  • IMAGE_TAG: Use AlloyDB Omni for the latest Debian image or AlloyDB Omni-ubi for the latest UBI image.

Specify a logging driver

By default, Docker and Podman don't perform log rotations. This can use up a lot of disk space, and eventually lead to disk space exhaustion. To use a different logging driver, you can specify the --log-driver field. For example, to log to journald:

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--log-driver=journald \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--log-driver=journald \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--log-driver=journald \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--log-driver=journald \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Replace the following variables:

  • CONTAINER_NAME: Name you used for your container. For example, my-omni-1.
  • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
  • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.
  • IMAGE_TAG: Use 16.9.0 for the latest Debian image or use 16.9.0-ubi for the latest UBI image.

For more information about logging drivers, refer to Docker's Configure logging drivers and Podman's podman-run documentation.

Also, you can configure logging using PostgreSQL. For more information, see Configure AlloyDB Omni log rotation.

Mount a shared memory volume

If you plan to use the AlloyDB columnar engine with AlloyDB Omni, we recommend making shared memory available to the AlloyDB Omni container. The method for doing this differs depending upon your host operating system, as shown in the following examples.

Linux

To make shared memory available to the container, mount /dev/shm:

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v /dev/shm:/dev/shm \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v /dev/shm:/dev/shm \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v /dev/shm:/dev/shm \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v /dev/shm:/dev/shm \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Replace the following variables:

  • CONTAINER_NAME: Name you used for your container. For example, my-omni-1.
  • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
  • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.
  • IMAGE_TAG: Use 16.9.0 for the latest Debian image or use 16.9.0-ubi for the latest UBI image.

macOS

To make shared memory available to the container, include the --shm-size flag:

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--shm-size=SHARED_MEMORY_SIZE \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--shm-size=SHARED_MEMORY_SIZE \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--shm-size=SHARED_MEMORY_SIZE \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
--shm-size=SHARED_MEMORY_SIZE \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:IMAGE_TAG

Replace the following variables:

  • CONTAINER_NAME: Name you used for your container. For example, my-omni-1.
  • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
  • SHARED_MEMORY_SIZE: Size to set for /dev/shm on the container, in the format described on Running containers. For example, to specify one gigabyte, use the value 1g.
  • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.
  • IMAGE_TAG: Use 16.9.0 for the latest Debian image or 16.9.0-ubi for the latest UBI image.

We recommend that you set the shared memory size to a number of megabytes equal to at least your database's value of the google_job_scheduler.max_parallel_workers_per_job flag, times 250. For more information about the columnar engine, see Configure the columnar engine in AlloyDB Omni.

For example, if the google_job_scheduler.max_parallel_workers_per_job database flag is set to its default value of 2, consider adding a flag of --shm-size=500m or greater when starting your database server.

For more information about the --shm-size flag, see Running containers.

Enable extensions

The list of extensions available in AlloyDB Omni is available in Supported database extensions. Although PostGIS and Orafce are not included with AlloyDB Omni, they can both be installed by following instructions:

Installed extensions are enabled using standard PostgreSQL CREATE EXTENSION statements as detailed in Enable an extension.