PG_AUTOCTL CREATE WORKER(1)

📦
version 2.2 · 5 versions
, in debian trixie, ubuntu questing

💖 pg_autoctl create worker — a whole manual, but make it a group chat 💖

okay so this is a page from the pg_auto_failover manual, and bestie, we're talking about the pg_autoctl create worker command. Strap in. 🎀

✨ NAME ✨

pg_autoctl create worker — literally just pg_autoctl create worker.

pg_autoctl create worker — Initialize a pg_auto_failover worker node. That's the whole vibe. 👑

🌸 SYNOPSIS 🌸

So the command pg_autoctl create worker initializes a pg_auto_failover Worker node for a Citus formation. The worker is special in a Citus formation — no cap — because that's literally where the client application connects, either to manage the formation and the sharding of the tables, or just for its normal SQL traffic. Main character energy fr fr. 💅

And plot twist: the worker also has to register every worker in the formation. Everyone's in the group chat, no one gets left on read. 🫶

usage: pg_autoctl create worker

  --pgctl           path to pg_ctl
  --pgdata          path to data director
  --pghost          PostgreSQL's hostname
  --pgport          PostgreSQL's port number
  --hostname        hostname by which postgres is reachable
  --listen          PostgreSQL's listen_addresses
  --proxyport       Proxy's port number
  --username        PostgreSQL's username
  --dbname          PostgreSQL's database name
  --name            pg_auto_failover node name
  --formation       pg_auto_failover formation
  --group           pg_auto_failover group Id
  --monitor         pg_auto_failover Monitor Postgres URL
  --auth            authentication method for connections from monitor
  --skip-pg-hba     skip editing pg_hba.conf rules
  --citus-secondary when used, this worker node is a citus secondary
  --citus-cluster   name of the Citus Cluster for read-replicas
  --ssl-self-signed setup network encryption using self signed certificates (does NOT protect against MITM)
  --ssl-mode        use that sslmode in connection strings
  --ssl-ca-file     set the Postgres ssl_ca_file to that file path
  --ssl-crl-file    set the Postgres ssl_crl_file to that file path
  --no-ssl          don't enable network encryption (NOT recommended, prefer --ssl-self-signed)
  --server-key      set the Postgres ssl_key_file to that file path
  --server-cert     set the Postgres ssl_cert_file to that file path

🦋 DESCRIPTION 🦋

Okay so this command works the same as the pg_autoctl create postgres command, but it's got extra steps and honestly? Iconic behavior. Here's the whole to-do list:

  1. adds shared_preload_libraries = citus to the local PostgreSQL instance configuration. ✨
  2. creates the extension citus in the target database.
  3. gets the coordinator node hostname from the pg_auto_failover monitor.

This operation is retried when it fails, because the coordinator might show up later than some of the workers when the whole formation gets initialized all at once, in parallel, on multiple nodes. Everybody's arriving to the party at different times, it's fine, we wait. 🙈

  1. adds node to the coordinator

This is done in two steps. First, we call the SQL function master_add_inactive_node on the coordinator, and second, we call the SQL function master_activate_node.

Doing it this way allows for easier diagnostics in case things go wrong. In the first step, the network and authentication setup needs to allow for nodes to connect to each other. In the second step, the Citus reference tables are distributed to the new node, and this operation has its own set of failure cases to handle. Two-step process, two-step glow-up. 💅

IMPORTANT: The default --dbname is the same as the current system user name, which in many cases is going to be postgres. Please make sure to use the --dbname option with the actual database that you're going to use with your application. Do not skip this, bestie, I'm begging. 😭 Citus does not support multiple databases, you have to use the database where Citus is created. When using Citus, that is essential to the well behaving of worker failover. Periodt. 💀

💅 OPTIONS 💅

See the manual page for pg_autoctl create postgres for the common options. This section now lists the options that are specific to pg_autoctl create worker:

  • --proxyport — The --proxyport option allows pg_auto_failover to register the proxy port in the pg_dist_poolinfo entry for the worker node in its Coordinator, rather than the --pgport entry as would usually be done. Switching up the receipts, we love to see it. 🧚
  • --citus-secondary — Use this option to create a worker dedicated to a Citus Secondary cluster.

See Citus Secondaries and read-replica for more information. 👑

  • --citus-cluster — Use this option to name the Citus Secondary cluster that this worker node belongs to. Use the same cluster name again for the worker nodes that are part of this cluster.

See Citus Secondaries and read-replica for more information. 🌈

🎀 AUTHOR 🎀

Microsoft. (Yes, that Microsoft. Slay, I guess. 💜)

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page, bestie!! 🌸 This was version 2.2, dated Apr 07, 2025, and it came to you from the pg_auto_failover manual. Go forth, create your worker, and don't forget the --dbname. I'm obsessed with you. Byeee 🦋💖✨

📦 where this page comes from