The following sections provide steps to configure your
AlloyDB Omni primary server for replication, configure the
replica server, and verify replication status on the primary server.
Update the network or firewall settings of your primary server's host so
that it allows ingress traffic from the replica server's host through the primary server's Postgres port.
Create a replication user:
Docker
dockerexecCONTAINER_NAMEpsql-hlocalhost-Upostgres-c"create user REPLICA_USER with replication password 'PASSWORD'"
Replace the following:
REPLICA_USER: the name of the replica user.
PASSWORD: the password for the replica user.
CONTAINER_NAME: the name that you assigned to the AlloyDB Omni container when you installed it.
Podman
podmanexecCONTAINER_NAMEpsql-hlocalhost-Upostgres-c"create user REPLICA_USER with replication password 'PASSWORD'"
Replace the following:
REPLICA_USER: the name of the replica user.
PASSWORD: the password for the replica user.
CONTAINER_NAME: the name that you assigned to the AlloyDB Omni container when you installed it.
Add the following lines in the /DATA_DIR/pg_hba.conf file of the primary server beforehost all all all scram-sha-256 that exists in the file:
SOURCE_PORT: the TCP port of the primary
AlloyDB Omni instance to replicate from. If you don't
provide this value, then AlloyDB Omni applies a default
value of 5432.
SLOT_NAME: the label for the name of the replication slot.
SOURCE_PORT: the TCP port of the primary
AlloyDB Omni instance to replicate from. If you don't
provide this value, then AlloyDB Omni applies a default
value of 5432.
SLOT_NAME: the label for the name of the replication slot.
To verify replication is configured properly, run the following command on the
primary server's host:
Docker
dockerexec-itCONTAINER_NAMEpsql-hlocalhost-Upostgres-c"select * from pg_stat_replication"
Podman
podmanexec-itCONTAINER_NAMEpsql-hlocalhost-Upostgres-c"select * from pg_stat_replication"
The output table contains one row for every replica connected to your primary
database server.
After you set up replication, all inserts, updates, and deletions to rows in
your primary database server become readable on your replica within seconds.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eCreating an AlloyDB Omni replica server enhances read throughput and availability by providing a read-only clone of the primary database server that continuously updates with the primary server's data.\u003c/p\u003e\n"],["\u003cp\u003eConfiguring the primary server for replication involves updating network/firewall settings to allow traffic from the replica, creating a replication user, and modifying the \u003ccode\u003e/DATA_DIR/pg_hba.conf\u003c/code\u003e file to permit replication connections.\u003c/p\u003e\n"],["\u003cp\u003eSetting up a replica server includes ensuring network connectivity to the primary, verifying the replica can connect using \u003ccode\u003epsql\u003c/code\u003e, establishing a persistent storage location, and initiating the replica instance.\u003c/p\u003e\n"],["\u003cp\u003eReplication status can be verified on the primary server by executing a command that displays information about connected replicas in a table format, and all changes on the primary will reflect on the replica within seconds.\u003c/p\u003e\n"]]],[],null,["# Create a read-only replica\n\nSelect a documentation version: 15.7.0keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/set-up-read-replica)\n- [16.8.0](/alloydb/omni/16.8.0/docs/set-up-read-replica)\n- [16.3.0](/alloydb/omni/16.3.0/docs/set-up-read-replica)\n- [15.12.0](/alloydb/omni/15.12.0/docs/set-up-read-replica)\n- [15.7.1](/alloydb/omni/15.7.1/docs/set-up-read-replica)\n- [15.7.0](/alloydb/omni/15.7.0/docs/set-up-read-replica)\n- [15.5.5](/alloydb/omni/15.5.5/docs/set-up-read-replica)\n- [15.5.4](/alloydb/omni/15.5.4/docs/set-up-read-replica)\n- [15.5.2](/alloydb/omni/15.5.2/docs/set-up-read-replica)\n\n\u003cbr /\u003e\n\nTo increase read throughput and availability, you can create an AlloyDB Omni replica server for an existing AlloyDB Omni server. A replica server provides a read-only clone of your primary database server. It continuously updates its own data to reflect changes to your primary server's data.\n\n\u003cbr /\u003e\n\nThe following sections provide steps to configure your\nAlloyDB Omni primary server for replication, configure the\nreplica server, and verify replication status on the primary server.\n\n\n| The information on this page applies only to AlloyDB Omni for containers. It does not apply to AlloyDB Omni for Kubernetes.\n\n\u003cbr /\u003e\n\nFor details, see [Install AlloyDB Omni on Kubernetes](/alloydb/omni/15.7.0/docs/deploy-kubernetes).\n\nConfigure your primary server for replication\n---------------------------------------------\n\n1. Update the network or firewall settings of your primary server's host so\n that it allows ingress traffic from the replica server's host through the primary server's [Postgres port](/alloydb/omni/15.7.0/docs/install).\n\n2. Create a replication user:\n\n ### Docker\n\n docker exec \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e psql -h localhost -U postgres -c \"create user \u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e with replication password '\u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e'\"\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e: the name of the replica user.\n - \u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e: the password for the replica user.\n - \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e: the name that you assigned to the AlloyDB Omni container when you installed it.\n\n ### Podman\n\n podman exec \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e psql -h localhost -U postgres -c \"create user \u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e with replication password '\u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e'\"\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e: the name of the replica user.\n - \u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e: the password for the replica user.\n - \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e: the name that you assigned to the AlloyDB Omni container when you installed it.\n3. Add the following lines in the `/`\u003cvar translate=\"no\"\u003eDATA_DIR\u003c/var\u003e`/pg_hba.conf` file of the primary server **before** `host all all all scram-sha-256` that exists in the file:\n\n host alloydbmetadata alloydbmetadata \u003cvar translate=\"no\"\u003eIP_RANGE\u003c/var\u003e trust\n host replication \u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e \u003cvar translate=\"no\"\u003eIP_RANGE\u003c/var\u003e scram-sha-256\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eIP_RANGE\u003c/var\u003e: the IP range, in CIDR notation, of the subnet where your replica machine is located. For example, `203.0.113.0/24`.\n - \u003cvar translate=\"no\"\u003eDATA_DIR\u003c/var\u003e: the data directory path of the primary server.\n4. Restart your primary server:\n\n ### Docker\n\n docker restart \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e\n\n ### Podman\n\n podman restart \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e\n\nCreate and configure the replica server\n---------------------------------------\n\nTo create and configure an AlloyDB Omni replica server, complete\nthe following steps:\n\n1. Ensure the replica has network connectivity to the primary server:\n\n ping \u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e with the IP address of the primary AlloyDB Omni instance to replicate from.\n2. Ensure the replica can connect to the primary server:\n\n ### Docker\n\n docker run -it --rm google/alloydbomni psql \"host=\u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e user=\u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e replication=1\" -c \"IDENTIFY_SYSTEM;\"\n\n ### Podman\n\n podman run -it --rm google/alloydbomni psql \"host=\u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e user=\u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e replication=1\" -c \"IDENTIFY_SYSTEM;\"\n\n The output should look similar to the following: \n\n systemid | timeline | xlogpos | dbname\n ---------------------+----------+-----------+--------\n 7376500460465963036 | 1 | 0/454B670 |\n (1 row)\n\n3. The replica must have a persistent storage location on disk:\n\n ### Docker\n\n mkdir alloydb && docker run --rm -it \\\n -e PGDATA=/var/lib/postgresql/data/pgdata \\\n -v \"$PWD/alloydb\":/var/lib/postgresql/data \\\n -p 5432:5432 \\\n --user $(id -u):$(id -g) \\\n google/alloydbomni \\\n /usr/lib/postgresql/15/bin/pg_basebackup \\\n --pgdata=/var/lib/postgresql/data/pgdata \\\n --checkpoint=fast \\\n --host=\"\u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e\" \\\n --port=\"\u003cvar translate=\"no\"\u003eSOURCE_PORT\u003c/var\u003e\" \\\n --username=\u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e \\\n --create-slot \\\n --write-recovery-conf \\\n --slot=\"\u003cvar translate=\"no\"\u003eSLOT_NAME\u003c/var\u003e\"\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSOURCE_PORT\u003c/var\u003e: the TCP port of the primary AlloyDB Omni instance to replicate from. If you don't provide this value, then AlloyDB Omni applies a default value of `5432`.\n - \u003cvar translate=\"no\"\u003eSLOT_NAME\u003c/var\u003e: the label for the name of the replication slot.\n\n ### Podman\n\n mkdir alloydb && podman run --rm -it \\\n -e PGDATA=/var/lib/postgresql/data/pgdata \\\n -v \"$PWD/alloydb\":/var/lib/postgresql/data \\\n -p 5432:5432 \\\n --user $(id -u):$(id -g) \\\n google/alloydbomni \\\n /usr/lib/postgresql/15/bin/pg_basebackup \\\n --pgdata=/var/lib/postgresql/data/pgdata \\\n --checkpoint=fast \\\n --host=\"\u003cvar translate=\"no\"\u003eSOURCE_IP\u003c/var\u003e\" \\\n --port=\"\u003cvar translate=\"no\"\u003eSOURCE_PORT\u003c/var\u003e\" \\\n --username=\u003cvar translate=\"no\"\u003eREPLICA_USER\u003c/var\u003e \\\n --create-slot \\\n --write-recovery-conf \\\n --slot=\"\u003cvar translate=\"no\"\u003eSLOT_NAME\u003c/var\u003e\"\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSOURCE_PORT\u003c/var\u003e: the TCP port of the primary AlloyDB Omni instance to replicate from. If you don't provide this value, then AlloyDB Omni applies a default value of `5432`.\n - \u003cvar translate=\"no\"\u003eSLOT_NAME\u003c/var\u003e: the label for the name of the replication slot.\n4. Start your replica instance:\n\n ### Docker\n\n docker run --detach \\\n --name pg-service \\\n -e POSTGRES_PASSWORD=a \\\n -e PGDATA=/var/lib/postgresql/data/pgdata \\\n -v \"$PWD/alloydb\":/var/lib/postgresql/data \\\n -v /dev/shm:/dev/shm \\\n -p 5432:5432 \\\n --user $(id -u):$(id -g) \\\n google/alloydbomni\n\n ### Podman\n\n podman run --detach \\\n --name pg-service \\\n -e POSTGRES_PASSWORD=a \\\n -e PGDATA=/var/lib/postgresql/data/pgdata \\\n -v \"$PWD/alloydb\":/var/lib/postgresql/data \\\n -v /dev/shm:/dev/shm \\\n -p 5432:5432 \\\n --user $(id -u):$(id -g) \\\n google/alloydbomni\n\nVerify replication status on the primary server\n-----------------------------------------------\n\nTo verify replication is configured properly, run the following command on the\nprimary server's host: \n\n### Docker\n\n docker exec -it \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e psql -h localhost -U postgres -c \"select * from pg_stat_replication\"\n\n### Podman\n\n podman exec -it \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e psql -h localhost -U postgres -c \"select * from pg_stat_replication\"\n\nThe output table contains one row for every replica connected to your primary\ndatabase server.\n\nAfter you set up replication, all inserts, updates, and deletions to rows in\nyour primary database server become readable on your replica within seconds.\n\nWhat's next\n-----------\n\n- [Logical replication](/alloydb/omni/15.7.0/docs/about-pglogical)"]]