Customize your AlloyDB Omni installation

Note: Your use of AlloyDB Omni is subject to the agreement between you and Google that governs Google Cloud offerings. If you do not have a Google Cloud account, or have not otherwise entered into an agreement with Google that governs Google Cloud offerings, please do not proceed or download this software until you have done so. To create a Google Cloud account, see the Google Cloud homepage.

AlloyDB Omni is deployed through a Docker image, which allows different forms of customization. This page shows some of the common customizations that are used.

To get started quickly with AlloyDB Omni using the default configuration, see Quickstart: AlloyDB Omni.

Before you begin

The following table lists recommended hardware and software configuration for AlloyDB Omni.

OS/Platform	Recommended hardware configuration	Recommended software configuration
Linux	x86-64 or Arm (*) CPU with AVX2 support 8GB of RAM for every CPU allocated to AlloyDB Omni 20+ GB of disk space	Debian based OS (Ubuntu, etc.) or RHEL 9 Linux kernel version 6.1 or higher or any Linux kernel version older than 5.3 that has support for the MADV_COLLAPSE and MADV_POPULATE_WRITE directives Cgroupsv2 enabled Docker Engine 25.0.0+ or Podman 5.0.0+
macOS	Intel CPU with AVX2 support or M-chip 8GB of RAM for every CPU allocated to AlloyDB Omni 20+ GB of disk space	Docker Desktop 4.30 or higher
(*) Arm support is in Preview.

1. Install the AlloyDB Omni CLI.

2. Use the AlloyDB Omni CLI to confirm that your Linux machine is ready to install AlloyDB Omni:

   sudo alloydb system-check
   

   If needed, modify your system until the output of the system-check command returns a successful check.

3. Optional: To create a new disk partition for AlloyDB Omni to use for data storage, we recommend that you use an ext4 file system for optimal performance.

   1. To create an ext4 file system, use the following command:

      mkfs.ext4 -m 1 -F "$disk_path"
      

   2. To mount your disk, use the following command:

      mount --make-shared -o noatime,discard,errors=panic "$disk_path" "$disk_mountpoint"
      

4. Install the server software using one of the following options:

   Note: To install AlloyDB Omni with machine learning (ML) functions enabled, including the ability to query large language models (LLMs), see Install AlloyDB Omni with AlloyDB AI.

   • To configure the server as a primary instance, run the following command:

     sudo alloydb database-server install --data-dir=$(realpath DATA_DIR)
     

     Replace DATA_DIR with the directory on your local file system where you want AlloyDB Omni to store its data, metadata, and configuration files. AlloyDB Omni tries to create this directory if it doesn't already exist. If you don't specify this value, then AlloyDB Omni defaults to /var/alloydb/main/.

     To have AlloyDB Omni listen for connections on a TCP port other than the default 5432, include the --pg-port flag:

     sudo alloydb database-server install \
         --data-dir=$(realpath DATA_DIR) \
         --pg-port=PORT
     

     Replace PORT with the TCP port that you want AlloyDB Omni to accept connections on.

   • To configure the server as a read replica, include the --replica-source-ip and --replica-source-port flags:

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

   Replace the following:

   • CONTAINER_NAME: The name to assign this new AlloyDB Omni container in your host machine's container registry—for example, my-omni.

   • NEW_PASSWORD: The password assigned the new container's postgres user after its creation.

   • DATA_DIR: The file system path that you want AlloyDB Omni to use for its data directory.

   • HOST_PORT: The 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.

   Enable ulimits

   The ulimit parameters specify various process limits that the Docker container is allowed to use. For optimal performance, AlloyDB Omni adjusts process priorities to allow critical PostgreSQL processes to run with higher priority, that is they get a bigger allocation of available CPUs. To allow this, specify -20:-20, which removes limitations for the AlloyDB Omni container.

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

   Specify a logging driver

   By default, Docker does not perform log rotations. This can use up a lot of disk space, and eventually lead to disk space exhaustion. You can configure Docker to use a different logging driver. For example, to log to journald:

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

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

   You can also configure logging using PostgreSQL. For more information, refer to PostgreSQL documentation Error reporting and logging.

   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 run --name CONTAINER_NAME \
       -e POSTGRES_PASSWORD=NEW_PASSWORD \
       -p HOST_PORT:5432 \
       -v /dev/shm:/dev/shm \
       -d google/alloydbomni
    ```
   

   macOS

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

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

   Replace SHARED_MEMORY_SIZE with the 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.

   We recommend setting 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.