From 73d3d510f1f2552744f7d585c054b5b652025e12 Mon Sep 17 00:00:00 2001 From: bean1352 Date: Wed, 23 Sep 2026 10:31:24 +0200 Subject: [PATCH 1/2] add Aurora Postgres setup and connection steps --- configuration/source-db/connection.mdx | 21 ++++++++++ configuration/source-db/private-endpoints.mdx | 10 +++-- configuration/source-db/setup.mdx | 40 +++++++++++++------ snippets/postgres-rds-powersync-user.mdx | 18 +++++++++ 4 files changed, 74 insertions(+), 15 deletions(-) create mode 100644 snippets/postgres-rds-powersync-user.mdx diff --git a/configuration/source-db/connection.mdx b/configuration/source-db/connection.mdx index 678d0e34..011050fe 100644 --- a/configuration/source-db/connection.mdx +++ b/configuration/source-db/connection.mdx @@ -49,6 +49,27 @@ PowerSync deploys and configures an isolated cloud environment for you, which ca If you get an error such as "IPs in this range are not supported", the instance is likely not configured to be publicly accessible. A DNS lookup on the host should give a public IP, and not for example `10.x.x.x` or `172.31.x.x`. + +1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and go to the **Database Connection** view. +2. Select the **Postgres** tab. +3. Use the cluster endpoint as the "**Host**". AWS also calls it the writer endpoint: it always points at the cluster's primary instance, the writer, and its hostname contains `.cluster-`. You can find it on the cluster's details page in the RDS console, or in the `Endpoint` field of `aws rds describe-db-clusters`. Do not use an instance endpoint or the reader endpoint. Aurora only supports logical replication from the writer, and the cluster endpoint follows the writer through a failover while an instance endpoint does not. +4. Complete the remaining fields: + * "**Name**" can be any name for the connection. + * "**Port**" is 5432 for Postgres databases. + * "**Username**" and "**Password**" maps to the `powersync_role` created in [Source Database Setup](/configuration/source-db/setup#postgres). + * PowerSync has the AWS RDS CA certificates pre-configured, so the default `verify-full` SSL mode works without additional configuration. +5. If the cluster is not publicly accessible, select your endpoint in the **Private Endpoint** dropdown. Keep the cluster endpoint as the "**Host**". PowerSync verifies the server certificate against it and sends the traffic through the Private Endpoint. With a Private Endpoint, **Test Connection** does not connect to the database, so confirm the connection after deploying as described in [Private Endpoints](/configuration/source-db/private-endpoints). +6. Click **Test Connection** and fix any errors. +7. Click **Save Connection**. + +PowerSync deploys and configures an isolated cloud environment for you, which can take a few minutes to complete. + +### Troubleshooting + +If you get an error such as "IPs in this range are not supported", the host resolves to a private IP. Make the cluster publicly accessible, or connect through a [Private Endpoint](/configuration/source-db/private-endpoints). + +If Sync Config validation fails with `postgres query failed`, or the instance logs show `Hostname/IP does not match certificate's altnames`, the server that answered is not the one named in "**Host**". The log line lists the DNS names in the certificate. This happens when "**Host**" is an instance endpoint after a failover, or when a Private Endpoint still forwards to a previous writer or cluster. Switch to the cluster endpoint, or update the target group behind the Private Endpoint. + 1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and go to the **Database Connection** view. 2. Select the **Postgres** tab. diff --git a/configuration/source-db/private-endpoints.mdx b/configuration/source-db/private-endpoints.mdx index 5e927ba8..0565899e 100644 --- a/configuration/source-db/private-endpoints.mdx +++ b/configuration/source-db/private-endpoints.mdx @@ -70,11 +70,11 @@ Create an Endpoint Service: To expose a Postgres database via PrivateLink, you need a Network Load Balancer that forwards traffic to the database. This works for Postgres running on EC2 or RDS. -For AWS RDS, the steps below do not handle dynamic IPs if the RDS instance's IP changes. This is specifically relevant when using an RDS cluster with failover support. See this [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) for handling IP changes automatically. +The target group holds a fixed IP address. It does not follow the database when the IP changes, which happens on an Aurora failover, an instance replacement, or a migration to a new cluster. PowerSync then cannot connect, or reaches a different instance and rejects its certificate because the names in the certificate do not include the configured host. Update the target group when the writer changes, or automate it as described in this [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/). 1. **Create a Target Group**: - 1. Obtain the RDS instance's private IP address. Make sure this points to a writable instance. + 1. Obtain the private IP address of the instance that PowerSync must replicate from. For Aurora, resolve the cluster endpoint to get the current writer's IP. For RDS, use the instance's private IP. 2. Create a **Target Group** with IP addresses as the target type, using the IP from above. Use TCP protocol and the database port (typically `5432` for Postgres). 2. **Create a Network Load Balancer (NLB)**: 1. Select the same VPC as your RDS instance. @@ -161,13 +161,17 @@ Once the status changes to `Available`, the endpoint can be selected when config 2. Select the **Postgres** or **MongoDB** tab. 3. In the **Private Endpoint** dropdown, select your endpoint. Only endpoints in the same region as the instance with status `Available` are selectable. 4. Fill in the rest of the connection details: - * **For Postgres**: enter your database connection details as usual. PowerSync routes traffic through the Private Endpoint to your load balancer. + * **For Postgres**: enter your database connection details as usual, with the database's own hostname as the "**Host**": the cluster endpoint for Aurora, or the instance endpoint for RDS. PowerSync uses this hostname to verify the server certificate and sends the traffic through the Private Endpoint to your load balancer. Do not enter the load balancer or Endpoint Service DNS name as the host, because it is not in the database's certificate. * **For MongoDB**: on the Atlas cluster, click **Connect**, choose **Private Endpoint** as the connection type, select the provisioned endpoint, choose **Drivers** as the connection method, and copy the resulting connection string. It should look something like `mongodb+srv://:@your-cluster-pl-0.abcde.mongodb.net/`. Paste it into the **URI** field in the Dashboard. 5. Click **Test Connection** and resolve any errors. 6. Click **Save Connection**. PowerSync deploys and configures an isolated cloud environment for you, which can take a few minutes. Monitor the logs to confirm the instance connects. + +For a connection that uses a Private Endpoint, **Test Connection** checks that the configuration is complete but does not connect to the database. It reports success without verifying reachability, TLS, credentials, `wal_level`, or the `powersync` publication. Complete the [Source Database Setup](/configuration/source-db/setup) steps first, then confirm the connection in the instance's **Health** view and logs after deploying. + + diff --git a/configuration/source-db/setup.mdx b/configuration/source-db/setup.mdx index 18660e04..8e07a06e 100644 --- a/configuration/source-db/setup.mdx +++ b/configuration/source-db/setup.mdx @@ -7,6 +7,7 @@ Jump to: [Postgres](#postgres) | [MongoDB](#mongodb) | [Azure DocumentDB](#azure import PostgresPowerSyncUser from '/snippets/postgres-powersync-user.mdx'; import PostgresPowerSyncPublication from '/snippets/postgres-powersync-publication.mdx'; +import PostgresRdsPowerSyncUser from '/snippets/postgres-rds-powersync-user.mdx'; import NeonDatabaseSetup from '/snippets/neon-database-setup.mdx'; ## Postgres @@ -60,24 +61,39 @@ We have documented steps for some specific hosting providers: ### 2. Create a PowerSync database user - Create a PowerSync user on Postgres: + - ```sql - -- SQL to create powersync user - CREATE ROLE powersync_role WITH BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword'; + ### 3. Create `powersync` publication + + - -- Allow the role to perform replication tasks - GRANT rds_replication TO powersync_role; + + + PowerSync replicates from the writer, the primary instance of an Aurora Postgres cluster. This applies to provisioned clusters and to Aurora Serverless v2. All currently available Aurora Postgres versions support logical replication. + + ### Prerequisites - -- Set up permissions for the newly created role - -- Read-only (SELECT) access is required - GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role; + PowerSync must be able to reach the writer. Either make the cluster publicly accessible over IPv4 and restrict access to PowerSync's IPs (see [IP Filtering](/configuration/source-db/security-and-ip-filtering)), or connect through a [Private Endpoint](/configuration/source-db/private-endpoints) using AWS PrivateLink. - -- Optionally, grant SELECT on all future tables (to cater for schema additions) - ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; + ### 1. Ensure logical replication is enabled + + In Aurora, `rds.logical_replication` is a setting of the **DB cluster parameter group**, not of a DB instance parameter group. + + 1. In the [Amazon RDS console](https://console.aws.amazon.com/rds/), open your cluster's **Configuration** tab and follow the **Parameter group** link of type **DB cluster parameter group**. If the cluster still uses a default parameter group, [create a custom DB cluster parameter group](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_WorkingWithDBClusterParamGroups.html) and assign it to the cluster first. Default parameter groups cannot be edited. + 2. Set `rds.logical_replication` to `1` and save. + 3. Reboot the writer. The change only takes effect after the reboot. + 4. Connect to the writer through the cluster endpoint and confirm the settings: + + ```sql + SHOW rds.logical_replication; -- on + SHOW wal_level; -- logical ``` - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). + For the related parameters `max_replication_slots`, `max_wal_senders` and `max_worker_processes`, see [Setting up logical replication for your Aurora PostgreSQL DB cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Replication.Logical.Configure.html). PowerSync uses one replication slot per instance, plus a second slot while it processes a new Sync Config version. See [Postgres Maintenance](/configuration/source-db/postgres-maintenance). + + ### 2. Create a PowerSync database user + + ### 3. Create `powersync` publication diff --git a/snippets/postgres-rds-powersync-user.mdx b/snippets/postgres-rds-powersync-user.mdx new file mode 100644 index 00000000..b7a0d68d --- /dev/null +++ b/snippets/postgres-rds-powersync-user.mdx @@ -0,0 +1,18 @@ +Create a PowerSync user on Postgres: + +```sql +-- SQL to create powersync user +CREATE ROLE powersync_role WITH BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword'; + +-- Allow the role to perform replication tasks +GRANT rds_replication TO powersync_role; + +-- Set up permissions for the newly created role +-- Read-only (SELECT) access is required +GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role; + +-- Optionally, grant SELECT on all future tables (to cater for schema additions) +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; +``` + +To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). From fb1ddb5f73fc1db99fbb8d48d1aa70f09c5ca66f Mon Sep 17 00:00:00 2001 From: bean1352 Date: Mon, 28 Sep 2026 14:24:48 +0200 Subject: [PATCH 2/2] Address review comments on Aurora connection steps --- configuration/source-db/connection.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/configuration/source-db/connection.mdx b/configuration/source-db/connection.mdx index 011050fe..9caa0c1a 100644 --- a/configuration/source-db/connection.mdx +++ b/configuration/source-db/connection.mdx @@ -52,10 +52,11 @@ If you get an error such as "IPs in this range are not supported", the instance 1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and go to the **Database Connection** view. 2. Select the **Postgres** tab. -3. Use the cluster endpoint as the "**Host**". AWS also calls it the writer endpoint: it always points at the cluster's primary instance, the writer, and its hostname contains `.cluster-`. You can find it on the cluster's details page in the RDS console, or in the `Endpoint` field of `aws rds describe-db-clusters`. Do not use an instance endpoint or the reader endpoint. Aurora only supports logical replication from the writer, and the cluster endpoint follows the writer through a failover while an instance endpoint does not. +3. Use the cluster endpoint as the "**Host**". AWS also calls it the writer endpoint: it always points at the cluster's primary instance, the writer. You can find it on the cluster's details page in the RDS console, or in the `Endpoint` field of `aws rds describe-db-clusters`. Do not use the reader endpoint, whose hostname contains `.cluster-ro-`, or an instance endpoint, whose hostname has no `.cluster-` segment. Aurora only supports logical replication from the writer, and the cluster endpoint follows the writer through a failover while an instance endpoint does not. 4. Complete the remaining fields: * "**Name**" can be any name for the connection. * "**Port**" is 5432 for Postgres databases. + * "**Database name**" is the database in your cluster to replicate. * "**Username**" and "**Password**" maps to the `powersync_role` created in [Source Database Setup](/configuration/source-db/setup#postgres). * PowerSync has the AWS RDS CA certificates pre-configured, so the default `verify-full` SSL mode works without additional configuration. 5. If the cluster is not publicly accessible, select your endpoint in the **Private Endpoint** dropdown. Keep the cluster endpoint as the "**Host**". PowerSync verifies the server certificate against it and sends the traffic through the Private Endpoint. With a Private Endpoint, **Test Connection** does not connect to the database, so confirm the connection after deploying as described in [Private Endpoints](/configuration/source-db/private-endpoints).