diff --git a/knowledge base/peerdb.md b/knowledge base/peerdb.md index b6d94d0..45a7e3e 100644 --- a/knowledge base/peerdb.md +++ b/knowledge base/peerdb.md @@ -10,6 +10,8 @@ Fast, simple, and cost effective Postgres replication. 1. [Peers](#peers) 1. [Mirrors](#mirrors) 1. [Alerts](#alerts) +1. [PostgreSQL peers](#postgresql-peers) + 1. [AWS RDS PostgresSQL peers](#aws-rds-postgressql-peers) 1. [Gotchas](#gotchas) 1. [Further readings](#further-readings) 1. [Sources](#sources) @@ -92,96 +94,6 @@ If Catalog and Temporal are HA, then the whole service is pretty much HA. Peers are connection settings to databases that PeerDB can operate upon. -_Source_ PostgreSQL peers **require** logical replication to be enabled. - -
- -```sql --- Check settings -sourceDb=> SELECT name,setting FROM pg_settings WHERE name IN ('wal_level','rds.logical_replication'); - name | setting --------------------------+--------- - rds.logical_replication | on - wal_level | logical -(2 rows) -``` - -```sql --- Configure sources -ALTER SYSTEM SET wal_level = logical; -ALTER SYSTEM SET max_wal_senders = 10; -ALTER SYSTEM SET max_replication_slots = 10; -``` - -
- -Operations: - -
- List - -```sql -SELECT id, name, type FROM peers; -``` - -```plaintext -GET /api/v1/peers/list -``` - -
- -
- Create or update - -```sql -CREATE PEER IF NOT EXISTS some_postgresql_peer -FROM POSTGRES -WITH ( - host='pg.example.org', - port='5432', - database='postgres', - user='postgres', - password='password' -); -``` - -| Peer type | `peer.type` attribute | Configuration attribute | -| ---------- | --------------------- | ----------------------- | -| ClickHouse | `8` | `clickhouse_config` | -| Kafka | `9` | `kafka_config` | -| PostgreSQL | `3` or `'POSTGRES'` | `postgres_config` | - -> The optional `"allow_update": true` attribute in the API seems to do **absolutely nothing** as of the time of writing. - -```plaintext -POST /api/v1/peers/create -{ - "allow_update": true, - "peer": { - "name": "some_postgresql_peer", - "type": "POSTGRES", - "postgres_config": { - "host": "pg.example.org", - "port": "5432", - "database": "postgres", - "user": "postgres", - "password": "password" - } - } -} -``` - -
- -
- Delete - -```sql -DELETE FROM peers WHERE name == 'some_postgresql_peer'; -``` - -
- ### Mirrors Mirrors can be in the following states: @@ -340,6 +252,192 @@ GET /api/v1/alerts/config +## PostgreSQL peers + +> [!caution] +> Specific implementations of PostgreSQL (e.g., AWS RDS) should be configured in their specific way.
+> Refer the specific section or upstream documentation. + +Refer [Generic PostgreSQL Source Setup Guide]. + +Requirements: + +1. Configure _generic_ _source_ PostgreSQL DBs as follows: + + - WAL level must be set to `logical`. + - Max WAL senders must be set to a reasonable amount (more than `1` is advised). + - Max replication slots must be set to a reasonable amount (at least `4` is advised). + +
+ + ```sql + -- Check settings + postgres=> SELECT name,setting FROM pg_settings WHERE name IN ('wal_level','max_wal_senders','max_replication_slots'); + name | setting + -------------------------+--------- + max_replication_slots | 20 + max_wal_senders | 35 + wal_level | logical + (3 rows) + + -- Configure settings + ALTER SYSTEM SET wal_level = logical; + ALTER SYSTEM SET max_wal_senders = 10; + ALTER SYSTEM SET max_replication_slots = 10; + ``` + +
+ +1. Create a DB user with `REPLICATION` permissions. + +
+ + ```sql + CREATE ROLE peerdb WITH LOGIN REPLICATION PASSWORD 'someSecurePassword'; + GRANT USAGE ON SCHEMA public TO peerdb; + GRANT SELECT ON ALL TABLES IN SCHEMA public TO peerdb; + ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO peerdb; + ``` + +
+ +1. Create a publication for the mirrors to use. + +
+ + ```sql + CREATE PUBLICATION peerdb FOR ALL TABLES; + ``` + +
+ +Operations: + +
+ List + +```sql +SELECT id, name, type FROM peers; +``` + +```plaintext +GET /api/v1/peers/list +``` + +
+ +
+ Create or update + +```sql +CREATE PEER IF NOT EXISTS some_postgresql_peer +FROM POSTGRES +WITH ( + host='pg.example.org', + port='5432', + database='postgres', + user='postgres', + password='password' +); +``` + +| Peer type | `peer.type` attribute | Configuration attribute | +| ---------- | --------------------- | ----------------------- | +| ClickHouse | `8` | `clickhouse_config` | +| Kafka | `9` | `kafka_config` | +| PostgreSQL | `3` or `'POSTGRES'` | `postgres_config` | + +> The optional `"allow_update": true` attribute in the API seems to do **absolutely nothing** as of the time of writing. + +```plaintext +POST /api/v1/peers/create +{ + "allow_update": true, + "peer": { + "name": "some_postgresql_peer", + "type": "POSTGRES", + "postgres_config": { + "host": "pg.example.org", + "port": "5432", + "database": "postgres", + "user": "postgres", + "password": "password" + } + } +} +``` + +
+ +
+ Delete + +```sql +DELETE FROM peers WHERE name == 'some_postgresql_peer'; +``` + +
+ +### AWS RDS PostgresSQL peers + +Refer [RDS Postgres Source Setup Guide]. + +- Configure _source_ AWS RDS PostgreSQL DBs as follows: + + - RDS logical replication must be enabled. + - WAL sender timeout must be set to `0`. + - WAL level must be set to `logical`. + - Max WAL senders must be set to a reasonable amount (more than `1` is advised). + - Max replication slots must be set to a reasonable amount (at least `4` is advised). + +
+ + ```sql + -- Check settings + postgres=> SELECT name,setting + FROM pg_settings + WHERE name IN ('rds.logical_replication','wal_sender_timeout','wal_level','max_wal_senders','max_replication_slots'); + name | setting + -------------------------+--------- + max_replication_slots | 20 + max_wal_senders | 35 + rds.logical_replication | on + wal_level | logical + wal_sender_timeout | 0 + (5 rows) + ``` + +
+ + Prefer modifying the settings by creating a parameter group for one's Postgres version and apply that to the RDS + instance.
+ It will require the instance to be rebooted. + +- Peers need a DB user with `REPLICATION` permissions.
+ AWS RDS does not allow that directly. Assign the `rds_replication` role to that user instead. + +
+ + ```sql + CREATE ROLE peerdb WITH LOGIN PASSWORD 'someSecurePassword'; + GRANT USAGE ON SCHEMA public TO peerdb; + GRANT SELECT ON ALL TABLES IN SCHEMA public TO peerdb; + ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO peerdb; + GRANT rds_replication TO peerdb; + ``` + +
+ +- Create a publication for the mirrors to use. + +
+ + ```sql + CREATE PUBLICATION peerdb FOR ALL TABLES; + ``` + +
+ ## Gotchas - The [documentation] is **sorely lacking**. @@ -502,10 +600,12 @@ GET /api/v1/alerts/config [blog]: https://blog.peerdb.io/ [codebase]: https://github.com/PeerDB-io/peerdb [documentation]: https://docs.peerdb.io/ +[Generic PostgreSQL Source Setup Guide]: https://docs.peerdb.io/connect/postgres/generic_postgres [helm chart]: https://github.com/PeerDB-io/peerdb-enterprise [peerdb ui - deeper dive: part 1]: https://blog.peerdb.io/peerdb-ui-deeper-dive-part-1 [peers.proto#PostgresConfig]: https://github.com/PeerDB-io/peerdb/blob/6a591128908cbd76df8f7e4094ec838fac08dcda/protos/peers.proto#L73 [public ips for peerdb cloud]: https://docs.peerdb.io/peerdb-cloud/ip-table +[RDS Postgres Source Setup Guide]: https://docs.peerdb.io/connect/postgres/rds_postgres [sql reference]: https://docs.peerdb.io/sql/reference [website]: https://www.peerdb.io/