Skip to content

Configuration

There are 7 sections of ECOX configuration:

  • global configuration.

    This section contains global configuration such as cluster name, node name, path of PostgreSQL binary, and etc.

  • log configuration.

    This section contains the log configuration such as log level, log rotation, and etc.

  • vip configuration.

    This section contains the virtual IP (VIP) configuration.

  • dcs configuration.

    This section contains the DCS configuration.

  • initdb configuration.

    This section contains arguments for PostgreSQL's initdb program.

  • postgres configuration.

    This section contains the PostgreSQL's configuration parameters.

  • hba configuration.

    This section contains the host-based authentication for PostgreSQL.

global

  • namespace (string)

    The namespace for this cluster.

  • cluster (string)

    The cluster name. Must be unique in the namespace.

  • nodename (string)

    The name of current node. Must be unique in the cluster.

  • sync_node_num (integer)

    The number of synchronous replication nodes.

    This parameter can be reloaded.

  • single_node_writable (boolean)

    Whether the single node can be writable?

    This parameter can be reloaded.

  • auto_promote_async (boolean)

    Whether the asynchronous nodes can automatically promote to synchronous nodes. If true it will automatically elevate the asynchronous nodes to the synchronous nodes when the synchronous node is no longer present.

    This parameter can be reloaded.

  • enable_primary_slot (boolean)

    If true, use the physical replication slot to control the WALs resource removal on the upstream node.

  • pg_bindir (string)

    Specify the path of the PostgreSQL's binary.

  • pg_datadir (string)

    Specify the path of the PostgreSQL data directory.

  • pg_conninfo (string)

    Specify the PostgreSQL database connection information in format ip:port.

  • pg_backup_conninfo (string)

    Optional, specify the database backup connection information in format ip:port.

    This parameter can be reloaded.

  • pg_super_username (string)

    Specify the super user name for PostgreSQL database connection.

    This parameter can be reloaded.

  • pg_super_password (string)

    Specify the super user password for PostgreSQL database connection.

    This parameter can be reloaded.

  • pg_rewind_username (string)

    Optional, specify the username for PostgreSQL rewind user. If omit, use pg_super_username instead.

    This parameter can be reloaded.

  • pg_rewind_password (string)

    Optional, specify the password for PostgreSQL rewind user.

    This parameter can be reloaded.

  • pg_replica_username (string)

    Optional, specify the username for PostgreSQL replication. If omit, use pg_super_username instead.

    This parameter can be reloaded.

  • pg_replica_password (string)

    Optional, specify the password for PostgreSQL replication.

    This parameter can be reloaded.

log

  • level (enum)

    Controls which message levels are written to the log. Valid values are DEBUG, INFO, WARN, ERROR, and FATAL. Each level includes all the levels that follow it. The later the level, the fewer messages are sent to the log. The default is WARN.

    This parameter can be reloaded.

  • filename (string)

    This parameter sets the file names of the created log files. The value is treated as a strftime pattern, so %-escapes can be used to specify time-varying file names. The default is ecox-%d.log.

  • directory (string)

    This parameter determines the directory in which log files will be created. It can be specified as an absolute path, or relative to the cluster data directory. The default is log.

  • rotation_age (integer)

    This parameter determines the maximum amount of time to use an individual log file, after which a new log file will be created. If this value is specified without units, it is taken as minutes. The default is 24 hours. Set to zero to disable time-based creation of new log files.

vip

ECOX includes built-in VIP functionality, which can be configured using the parameters in this section. Refer to the installation guide to install the required software.

Warning

The VIP functionality requires sudo privileges for the ECOX runtime user. The example below assumes the user is postgres:

cat <<EOF | sudo tee /etc/sudoers.d/postgres
postgres ALL=(ALL) NOPASSWD: /usr/sbin/ip, /usr/sbin/arping
EOF

  • enable_master_vip (boolean)

    Determines whether to enable the VIP for the master node. If true, a high-availability VIP will be configured for write operations. The default is false.

  • master_vip_interface (string)

    Optional, specify the network interface name to which the master VIP will be bound.

  • master_vip_ipnetwork (string)

    Optional, specify the virtual IP address and subnet mask for the master node in CIDR notation (e.g., 192.168.1.100/24).

  • enable_readonly_vip (boolean)

    Determines whether to enable the Virtual IP for read-only traffic. If true, a separate VIP will be configured for load-balancing read requests across replica nodes. The default is false.

  • readonly_vip_interface (string)

    Optional, specify the network interface name to which the read-only VIP will be bound.

  • readonly_vip_ipnetwork (string)

    Optional, specify the virtual IP address and subnet mask for read-only access node in CIDR notation (e.g., 192.168.1.101/24).

dcs

  • type (enum)

    Specify the distributed coordination service type. Currently, the only supported value is zookeeper.

  • hosts (string)

    A comma-separated list of server addresses in ip:port format.

    Example: 192.168.1.10:2181,192.168.1.11:2181

  • session_timeout (integer)

    The session timeout duration (in milliseconds). This defines the maximum time the client waits for a response before considering the connection lost. The default is 10s.

  • username (string)

    The username used for authentication with the distributed coordination service. Optional.

  • password (string)

    The password associated with the specified username. Optional.

initdb

Note

The initdb supports more arguments, see PostgreSQL documentation. However, we only support the following arguments when initializing database cluster.

If pg_super_username is specified, it will create super using pg_super_username and pg_super_password (if pg_super_password not empty).

  • data_checksums (boolean)

    Specify whether data checksums should be enabled. When enabled, the system calculates checksums on data pages to detect corruption caused by the I/O system that might otherwise go unnoticed. The default is true.

  • encoding (string)

    Set the default character encoding for the template databases. This determines how character data is stored in the database. Optional.

  • wal_directory (string)

    Specify the directory path where the write-ahead log (WAL) files are stored. Note that pg_basebackup also utilizes this parameter to locate the WAL files. Optional.

  • wal_segsize (integer)

    Set the size of individual WAL segments in megabytes. The value must be a power of 2 between 1 and 1024 (e.g., 16, 32, 64). The default is 0, which means let initdb choose.

postgres

This section contains the PostgreSQL parameters. See PostgreSQL Server Configuration for more details.

Upon startup, ECOX automatically overwrites postgresql.conf using the parameters defined in this section.

Tip

Certain parameter settings determine the size of shared memory used to track transaction IDs, locks, and prepared transactions. These shared memory structures on the standby database must be no smaller than those on the primary database to ensure that the standby database does not run out of shared memory during recovery. For example, if the primary database uses prepared transactions but the standby database has not allocated any shared memory to track prepared transactions, recovery will not proceed until the standby database's configuration is changed. The affected parameters include:

  • max_connections
  • max_locks_per_transaction
  • max_prepared_transactions
  • max_wal_senders
  • max_worker_processes

For more details, see the PostgreSQL documentation.

In addition, because ECOX relies on PostgreSQL's streaming replication, wal_level must be at least replica (the default).

hba

This section contains PostgreSQL client authentication settings controlled by pg_hba.conf. See PostgreSQL Client Authentication for more details.

Upon startup, ECOX automatically overwrites pg_hba.conf using the parameters defined in this section.