Patroni

https://patroni.readthedocs.io/en/latest/
Admin
Patroni is a template for high availability (HA) PostgreSQL solutions using Python, supporting a...
Tokens:359,388
Snippets:2,799
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Patroni with psycopg3, etcd3, and aws dependencies

Source: https://patroni.readthedocs.io/en/latest/installation.html

Example command to install Patroni together with psycopg3, Etcd as DCS, and AWS callbacks.

```bash
pip install patroni[psycopg3,etcd3,aws]

```

--------------------------------

### start() -> None

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.api.html

Starts the REST API server.

```APIDOC
## start() -> None

### Description
Starts the REST API server.

```

--------------------------------

### Start Patroni cluster with etcd and HAProxy

Source: https://patroni.readthedocs.io/en/latest/README.html

Start a Patroni cluster by launching etcd (with v2 API enabled) and two Patroni instances using the example configuration files postgres0.yml and postgres1.yml. Run these commands from separate terminals. Then start HAProxy with the provided haproxy.cfg so your application can connect to a single endpoint for the cluster leader.

```shell
> etcd --data-dir=data/etcd --enable-v2=true
> ./patroni.py postgres0.yml
> ./patroni.py postgres1.yml


```

```shell
> haproxy -f haproxy.cfg


```

--------------------------------

### patronictl show-config example

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example of showing dynamic configuration for cluster 'batman'. Output displays configuration parameters.

```bash
$ patronictl -c postgres0.yml show-config batman
loop_wait: 10
postgresql:
  parameters:
    max_connections: 250
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5
  - host all all 0.0.0.0/0 md5
  use_pg_rewind: true
retry_timeout: 10
ttl: 30

```

--------------------------------

### SyncState.from_node examples

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.html

Examples of parsing synchronisation state information with SyncState.from_node. Each example shows the result of the leader property for different inputs, including None, empty JSON, invalid JSON, and valid JSON.

```python
>>> SyncState.from_node(1, None).leader is None
True
```

```python
>>> SyncState.from_node(1, '{}').leader is None
True
```

```python
>>> SyncState.from_node(1, '{').leader is None
True
```

```python
>>> SyncState.from_node(1, '[]').leader is None
True
```

```python
>>> SyncState.from_node(1, '{"leader": "leader"}').leader == "leader"
True
```

```python
>>> SyncState.from_node(1, {"leader": "leader"}).leader == "leader"
True
```

--------------------------------

### start

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.postgresql.html

Starts PostgreSQL and waits for postmaster to open ports or terminate.

```APIDOC
## start

### Description
Start PostgreSQL. Waits for postmaster to open ports or terminate so pg_isready can be used to check startup completion or failure.

### Method
start

### Signature
start(_timeout : float | None = None_, _task : CriticalTask | None = None_, _block_callbacks : bool = False_, _role : PostgresqlRole | None = None_, _after_start : Callable[[...], Any] | None = None_) → bool | None

### Parameters
- **timeout** (float | None) - Optional - Timeout in seconds to wait for startup.
- **task** (CriticalTask | None) - Optional - Task to monitor for cancellation.
- **block_callbacks** (bool) - Optional - Whether to block callbacks during start.
- **role** (PostgresqlRole | None) - Optional - Role to assume after start.
- **after_start** (Callable[[...], Any] | None) - Optional - Callback invoked after start.

### Returns
- **bool | None** - True if start was initiated and postmaster ports are open, False if start failed, and None if postgres is still starting up.
```

--------------------------------

### patronictl failover example

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command and output for failing over to node postgresql2, showing the cluster topology before and after the failover.

```text
$ patronictl -c postgres0.yml failover batman --candidate postgresql2 --force
Current cluster topology
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  3 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
2023-09-12 11:52:27.50978 Successfully failed over to "postgresql2"
+ Cluster: batman (7277694203142172922) -+---------+----+-------------+---------+------------+---------+
| Member      | Host           | Role    | State   | TL | Receive LSN |     Lag | Replay LSN |     Lag |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+
| postgresql0 | 127.0.0.1:5432 | Replica | stopped |    |     unknown | unknown |    unknown | unknown |
| postgresql1 | 127.0.0.1:5433 | Replica | running |  3 |   0/4000188 |       0 |  0/4000188 |       0 |
| postgresql2 | 127.0.0.1:5434 | Leader  | running |  3 |             |         |            |         |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+

```

--------------------------------

### patronictl resume example

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example of resuming cluster 'batman' with --wait. Output shows request sent and success message.

```bash
$ patronictl -c postgres0.yml resume batman --wait
'resume' request sent, waiting until it is recognized by all nodes
Success: cluster management is resumed

```

--------------------------------

### Get patronictl version only

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command to get only the patronictl version. Output shows 'patronictl version 4.0.0'.

```bash
$ patronictl -c postgres0.yml version
patronictl version 4.0.0

```

--------------------------------

### Bootstrap.bootstrap(config: Dict[str, Any]) -> bool

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.postgresql.bootstrap.html

Initialize a new node from scratch and start it.

```APIDOC
## Bootstrap.bootstrap(config: Dict[str, Any]) -> bool

### Description
Initialize a new node from scratch and start it.

### Method
Callable method

### Endpoint
Bootstrap.bootstrap(config)

### Parameters
- **config** (Dict[str, Any]) - Required - Configuration for the bootstrap process.

### Returns
`True` if the bootstrap was successful, `False` otherwise.
```

--------------------------------

### Get DSN of the primary node

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command to get the DSN of the primary node, showing the output host=127.0.0.1 port=5432.

```bash
$ patronictl -c postgres0.yml dsn batman -r primary
host=127.0.0.1 port=5432

```

--------------------------------

### Get DSN of the node named postgresql1

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command to get the DSN of a specific member by name, showing the output host=127.0.0.1 port=5433.

```bash
$ patronictl -c postgres0.yml dsn batman --member postgresql1
host=127.0.0.1 port=5433

```

--------------------------------

### Get patronictl and cluster member versions

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command to get the patronictl version and the versions of all members of cluster 'batman'. Output includes patronictl version and per-member Patroni and PostgreSQL versions.

```bash
$ patronictl -c postgres0.yml version batman
patronictl version 4.0.0

postgresql0: Patroni 4.0.0 PostgreSQL 16.4
postgresql1: Patroni 4.0.0 PostgreSQL 16.4
postgresql2: Patroni 4.0.0 PostgreSQL 16.4

```

--------------------------------

### KVStoreTTL.__init__

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.raft.html

Initializes the KVStoreTTL class, which extends DynMemberSyncObj.

```APIDOC
## KVStoreTTL.__init__

### Description
Initializes the KVStoreTTL class, which extends DynMemberSyncObj.

### Method
Constructor

### Signature
`__init__(on_ready: Callable[[...], Any] | None, on_set: Callable[[str, Dict[str, Any]], None] | None, on_delete: Callable[[str], None] | None, **config: Any) -> None`

### Parameters
- **on_ready** (Callable[[...], Any] | None) - Required - callback when the store is ready
- **on_set** (Callable[[str, Dict[str, Any]], None] | None) - Required - callback when a key is set
- **on_delete** (Callable[[str], None] | None) - Required - callback when a key is deleted
- **config** (Any) - Optional - additional configuration parameters

### Returns
None
```

--------------------------------

### Get patronictl and specific member versions

Source: https://patroni.readthedocs.io/en/latest/patronictl.html

Example command to get the patronictl version and the versions of specific members 'postgresql1' and 'postgresql2' of cluster 'batman'. Output includes patronictl version and the requested member versions.

```bash
$ patronictl -c postgres0.yml version batman postgresql1 postgresql2
patronictl version 4.0.0

postgresql1: Patroni 4.0.0 PostgreSQL 16.4
postgresql2: Patroni 4.0.0 PostgreSQL 16.4

```

--------------------------------

### CoreV1ApiProxy.__init__

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.kubernetes.html

Initializes a proxy to work with k8s_client.CoreV1Api() object.

```APIDOC
## CoreV1ApiProxy.__init__

### Description
Initializes a proxy to work with k8s_client.CoreV1Api() object.

### Method
Constructor

### Parameters
- **use_endpoints** (bool | None) - Optional - Whether to use endpoints.
- **bypass_api_service** (bool | None) - Optional - Whether to bypass API service.

### Returns
None
```

--------------------------------

### K8sClient.CoreV1Api.__init__

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.kubernetes.html

Initializes a CoreV1Api instance.

```APIDOC
## K8sClient.CoreV1Api.__init__

### Description
Initializes a CoreV1Api instance.

### Method
Constructor

### Parameters
- **api_client** (ApiClient | None) - Optional - The API client to use.

### Returns
None
```

--------------------------------

### Check node status after PATCH: pending_restart flag

Source: https://patroni.readthedocs.io/en/latest/rest_api.html

After patching the configuration, verify that the node processed it. The example shows a GET /patroni request that returns the node status, including the pending_restart flag and reason when a parameter change requires a restart.

```bash
$ curl -s http://localhost:8008/patroni | jq .
{
  "database_system_identifier": "6287881213849985952",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "xlog": {
    "location": 2197818976
  },
  "timeline": 1,
  "dcs_last_seen": 1724874545,
  "database_system_identifier": "7408277255830290455",
  "pending_restart": true,
  "pending_restart_reason": {
    "max_connections": {
      "old_value": "100",
      "new_value": "101"
    }
  },
  "patroni": {
    "version": "4.0.0",
    "scope": "batman",
    "name": "patroni1"
  },
  "state": "running",
  "role": "primary",
  "server_version": 160004
}
```

--------------------------------

### patroni.scripts.barman.utils.set_up_logging

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.scripts.barman.utils.html

Sets up logging to a file if a log file path is provided, otherwise logs to the console.

```APIDOC
## patroni.scripts.barman.utils.set_up_logging

### Description
Sets up logging to a file if a log file path is provided, otherwise logs to the console.

### Method
Function

### Signature
`set_up_logging(log_file: str | None = None) -> None`

### Parameters
- **log_file** (str | None) - Optional - File where to log messages, if any.
```

--------------------------------

### Run test suites (flake8, pytest, behave)

Source: https://patroni.readthedocs.io/en/latest/contributing_guidelines.html

Run various test suites after installing dependencies. Use Virtualenv or specify python3. The -s option includes print output during test execution. For behave, modify DCS as desired; raft has no dependencies and is easiest to start with.

```bash
# You may want to use Virtualenv or specify python3.

# Run flake8 to check syntax and formatting:
python setup.py flake8

# Run the pytest suite in tests/:
python setup.py test

# Moreover, you may want to run tests in different scopes for debugging purposes,
# the -s option include print output during test execution.
# Tests in pytest typically follow the pattern: FILEPATH::CLASSNAME::TESTNAME.
pytest -s tests/test_api.py
pytest -s tests/test_api.py::TestRestApiHandler
pytest -s tests/test_api.py::TestRestApiHandler::test_do_GET

# Run the behave (https://behave.readthedocs.io/en/latest/) test suite in features/;
# modify DCS as desired (raft has no dependencies so is the easiest to start with):
DCS=raft python -m behave

```

--------------------------------

### strtod examples

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.utils.html

Examples of the strtod function extracting a double precision number from the beginning of a string. Each example shows the input and the expected tuple output.

```python
>>> strtod(' A ') == (None, 'A')
True
```

```python
>>> strtod('1 A ') == (1.0, ' A')
True
```

```python
>>> strtod('1.5A') == (1.5, 'A')
True
```

```python
>>> strtod('8.325e-10A B C') == (8.325e-10, 'A B C')
True
```

--------------------------------

### Leader.checkpoint_after_promote example

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.html

Shows how to call the checkpoint_after_promote property on a Leader instance. The example constructs a Leader with a Member created from a JSON string and prints the result.

```python
>>> Leader(1, '', Member.from_node(1, '', '', '{"version":"z"}')).checkpoint_after_promote

```

--------------------------------

### is_starting()

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.postgresql.html

Checks if the PostgreSQL instance is starting.

```APIDOC
## is_starting()

### Description
Checks if the PostgreSQL instance is starting.

### Returns
- **bool** - True if starting, False otherwise.
```

--------------------------------

### SyncState.matches examples

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.html

Examples of checking if a node is present in the /sync state using SyncState.matches. The examples show case-insensitive matching and the effect of the check_leader parameter.

```python
>>> s = SyncState(1, 'foo', 'bar,zoo', 0)
```

```python
>>> s.matches('foo')
False
```

```python
>>> s.matches('fOo', True)
True
```

```python
>>> s.matches('Bar')
True
```

```python
>>> s.matches('zoO')
True
```

```python
>>> s.matches('baz')
False
```

```python
>>> s.matches(None)
False
```

```python
>>> SyncState.empty(1).matches('foo')
False
```

--------------------------------

### unquote examples

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.utils.html

Examples of the unquote function removing quotes from a fully quoted string. The examples show that strings with multiple quotes or unbalanced quotes are returned unchanged.

```python
>>> unquote('"a quoted string"')
'a quoted string'
```

```python
>>> unquote('"a multi" "quoted string"')
'"a multi" "quoted string"'
```

```python
>>> unquote('unbalanced "quoted string')
'unbalanced "quoted string'
```

--------------------------------

### Install Patroni on Debian derivatives using apt

Source: https://patroni.readthedocs.io/en/latest/installation.html

Install Patroni via apt after the PGDG repository is installed. The package is provided by the Postgres community, not the Patroni developers.

```bash
apt-get install patroni

```

--------------------------------

### Etcd3ClientError.__init__

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.etcd3.html

Initializes an Etcd3ClientError instance.

```APIDOC
## Etcd3ClientError.__init__

### Description
Initializes an Etcd3ClientError instance.

### Method
Constructor

### Signature
`__init__(_code: int | None = None, _error: str | None = None, _status: int | None = None) -> None`

### Parameters
- **code** (int | None) - Optional - Error code.
- **error** (str | None) - Optional - Error message.
- **status** (int | None) - Optional - HTTP status code.

### Returns
None
```

--------------------------------

### Etcd3Client.__init__

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.etcd3.html

Initializes an Etcd3Client instance with the given configuration, DNS resolver, and cache TTL.

```APIDOC
## Etcd3Client.__init__

### Description
Initializes an Etcd3Client instance with the given configuration, DNS resolver, and cache TTL.

### Method
Constructor

### Signature
`__init__(_config: Dict[str, Any], _dns_resolver: DnsCachingResolver, _cache_ttl: int = 300) -> None`

### Parameters
- **config** (Dict[str, Any]) - Required - Configuration dictionary.
- **dns_resolver** (DnsCachingResolver) - Required - DNS resolver instance.
- **cache_ttl** (int) - Optional - Cache TTL in seconds. Default is 300.

### Returns
None
```

--------------------------------

### Install Patroni with etcd DCS on RHEL 9 using dnf

Source: https://patroni.readthedocs.io/en/latest/installation.html

Install Patroni and the etcd DCS package on RHEL 9 and derivatives using dnf. Requires the PGDG repository to be installed.

```bash
dnf install patroni patroni-etcd

```

--------------------------------

### parse_version example

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.html

Example usage of patroni.parse_version converting a version string to a tuple of integers.

```python
>>> parse_version('2.5.4.dev1 (dt dec pq3 ext lo64)')
(2, 5, 4)
```

--------------------------------

### wal_e replica creation method example

Source: https://patroni.readthedocs.io/en/latest/replica_bootstrap.html

Example configuration for using wal_e as a replica creation method, with basebackup as fallback. The wal_e method uses the command patroni_wale_restore and sets no_leader, envdir, and use_iam parameters.

```yaml
postgresql:
    create_replica_methods:
        - wal_e
        - basebackup
    wal_e:
        command: patroni_wale_restore
        no_leader: 1
        envdir: {{WALE_ENV_DIR}}
        use_iam: 1
    basebackup:
        max-rate: '100M'

```

--------------------------------

### Etcd3Client.authenticate_on_start

Source: https://patroni.readthedocs.io/en/latest/modules/patroni.dcs.etcd3.html

Authenticates with Etcd v3 at startup and exits on invalid credentials.

```APIDOC
## Etcd3Client.authenticate_on_start

### Description
Authenticates with Etcd v3 at startup and exits on invalid credentials.

### Method
authenticate_on_start

### Signature
`authenticate_on_start(_auth_request_func: Callable[[...], Dict[str, Any]] | None = None)`

### Parameters
- **auth_request_func** (Callable[[...], Dict[str, Any]] | None) - Optional - Optional custom authentication request function. If not provided, call_rpc() will be used.

### Returns
None
```

--------------------------------

### Bootstrap from Barman backup

Source: https://patroni.readthedocs.io/en/latest/replica_bootstrap.html

Example configuration to bootstrap a fresh Patroni cluster from a Barman backup using the patroni_barman command. Requires Barman and pg-backup-api configured on the Barman host. keep_existing_recovery_conf is set to true to preserve generated recovery configuration.

```yaml
bootstrap:
    method: barman
    barman:
        keep_existing_recovery_conf: true
        command: patroni_barman --api-url https://barman-host:7480 recover
        barman-server: my_server
        ssh-command: ssh postgres@patroni-host

```

--------------------------------

### Install Patroni on SUSE Enterprise Linux using zypper

Source: https://patroni.readthedocs.io/en/latest/installation.html

Install Patroni and the etcd DCS package on SLES 15 with the PGDG repository installed. May require enabling SUSE PackageHub repositories for dependencies.

```bash
zypper install patroni patroni-etcd

```
Tokens:
Raw