Skip to content

Document self-serve flow Private Endpoints flow in the dashboard #454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benitav wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document self-serve flow Private Endpoints flow in the dashboard #454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
34e867a
Document self-serve flow in the dashboard, and polish existing wordin…
benitav May 14, 2026
eab42be
Merge branch 'main' into self-serve-endpoints
benitav May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 109 additions & 90 deletions configuration/source-db/private-endpoints.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,7 @@ title: "Private Endpoints"
description: "Connect PowerSync Cloud to your database over AWS PrivateLink without public internet exposure."
---

## PowerSync Cloud: AWS Private Endpoints

To avoid exposing a database in AWS to the public internet, using AWS Private Endpoints ([AWS PrivateLink](https://aws.amazon.com/privatelink/)) is an option that provides private networking between the source database and the PowerSync Service. Private Endpoints are currently available on our [Team and Enterprise plans](https://www.powersync.com/pricing).

We use Private Endpoints instead of VPC peering to ensure that no other resources are exposed between the VPCs.
Private Endpoints use [AWS PrivateLink](https://aws.amazon.com/privatelink/) to provide private networking between your source database and the PowerSync Service, without exposing the database to the public internet. They are available on our [Team and Enterprise plans](https://www.powersync.com/pricing) and can be managed in the [PowerSync Dashboard](https://dashboard.powersync.com/) under **Organization settings**.

<Warning>
Do not rely on Private Endpoints as the only form of security. Always use strong database passwords, and use client certificates if additional security is required.
Expand All @@ -16,150 +12,173 @@ Do not rely on Private Endpoints as the only form of security. Always use strong
## Current Limitations

1. Private Endpoints are currently only supported for Postgres and MongoDB instances. [Contact us](/resources/contact-us) if you need this for MySQL or SQL Server.
2. Self-service is not yet available on the PowerSync side — [contact PowerSync support](/resources/contact-us) to configure the instance.
3. Only AWS is supported currently — other cloud providers are not supported yet.
4. The **"Test Connection"** function on the [PowerSync Dashboard](https://dashboard.powersync.com/) is not supported yet — the instance has to be deployed to test the connection.
2. Only AWS is supported currently. Other cloud providers are not supported yet.
3. Private Endpoints can currently only be managed in the Dashboard. CLI support is not yet available.

## Concepts

* [AWS PrivateLink](https://aws.amazon.com/privatelink/) is the overarching feature on AWS.
* [AWS PrivateLink](https://aws.amazon.com/privatelink/) is the overarching AWS feature.

* **VPC/Private Endpoint Service** is the service that exposes the database, and lives in the same VPC as the source database. It provides a one-way connection to the database without exposing other resources in the VPC.
* **VPC/Private Endpoint Service** is the service that exposes the database. It lives in the same VPC as the source database and provides a one-way connection without exposing other resources in the VPC.

* **Endpoint Service Name** is a unique identifier for this Endpoint Service.
* **Service Name** is the unique identifier for the Endpoint Service, in the form `com.amazonaws.vpce.<region>.vpce-svc-<id>`.
* Each Endpoint Service may have multiple Private Endpoints in different VPCs.

* **VPC/Private Endpoint** is the endpoint in the PowerSync VPC. This is what the PowerSync instance connects to.
* **VPC/Private Endpoint** is the endpoint in the PowerSync VPC that the PowerSync instance connects to.

* **VPC Endpoint ID** is the identifier of this endpoint, in the form `vpce-<id>`. You use this ID to accept the connection on the Endpoint Service side.

For custom Endpoint Services for Postgres:
* **Network Load Balancer (NLB)** is a load balancer that exposes the source database to the Endpoint Service.
* **Target Group** specifies the IPs and ports for the Network Load Balancer to expose.
* **Listener** for the Network Load Balancer is what describes the incoming port on the Network Load Balancer (the port that the PowerSync instance connects to).

* **Network Load Balancer (NLB)** forwards traffic from the Endpoint Service to the source database.
* **Target Group** specifies the IPs and ports the NLB exposes.
* **Listener** describes the incoming port on the NLB (the port the PowerSync instance connects to).

## Private Endpoint Setup

<AccordionGroup>
<Accordion title="AWS PrivateLink in MongoDB Atlas">
The flow is the same for both supported source databases: configure an Endpoint Service in front of your database, create a matching Private Endpoint in the PowerSync Dashboard, accept the connection, then point your database connection at the endpoint.

<Steps>
<Step title="Configure the Endpoint Service">

Set up an Endpoint Service in front of your source database and copy its **Service Name**.

<Tabs>
<Tab title="MongoDB Atlas">

MongoDB Atlas supports creating an Endpoint Service per project for AWS.

**Limitations:**

1. Only Atlas clusters in AWS are supported.
2. The Atlas cluster must be in one of the PowerSync [AWS regions](#aws-regions). Cross-region endpoints are not yet supported by MongoDB Atlas.
3. This is only supported for _Atlas_ clusters — PowerSync does not support PrivateLink for MongoDB clusters self-hosted in AWS.
3. PowerSync does not support PrivateLink for MongoDB clusters self-hosted in AWS, only Atlas clusters.

### 1. Configure the Endpoint Service
To configure the Endpoint Service:

1. In the Atlas project dashboard, go to **Network Access** → **Private Endpoint** → **Dedicated Cluster**.
2. Select **Add Private Endpoint**.
3. Select **AWS** and the relevant AWS region.
4. Wait for the **Endpoint Service** to be created.
5. "Your VPC ID" and "Your Subnet IDs" are not relevant for PowerSync - leave those blank.
6. Avoid running the command to create the "VPC Interface Endpoint"; this step is handled by PowerSync.
7. Note the **Endpoint Service Name**. This is displayed in the command to run, as the `--service-name` option.

The Service Name should look something like `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`.
5. Leave "Your VPC ID" and "Your Subnet IDs" blank. They are not relevant for PowerSync.
6. Do not run the command to create the "VPC Interface Endpoint". PowerSync handles this step.
7. Note the **Endpoint Service Name** displayed in the command, as the `--service-name` option. It should look like `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`.

Skip the final step of configuring the "VPC Endpoint ID" — this will be done later.
Skip the final step of configuring the "VPC Endpoint ID". You will provide this in a later step.

### 2. PowerSync Setup
</Tab>
<Tab title="Custom Endpoint Service for Postgres">

On PowerSync Cloud, create a new instance, but do not configure the connection yet. Copy the **Instance ID**.
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.

[Contact us](/resources/contact-us) and provide:
1. The **Endpoint Service Name**.
2. The PowerSync **Instance ID**.

We will then configure the instance to use the Endpoint Service for the database connection, and provide you with a **VPC Endpoint ID**, in the form `vpce-12346`.

### 3. Finish Atlas Endpoint Service Setup

On the Atlas Private Endpoint Configuration, in the final step, specify the **VPC Endpoint ID** from above.
If you have already closed the dialog, go through the process of creating a Private Endpoint again. It should have the same Endpoint Service Name as before.

Check that the **Endpoint Status** changes to _Available_.

### 4. Get the Connection String
<Warning>
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.
</Warning>

1. On the Atlas cluster, select **Connect**.
2. Select **Private Endpoint** as the connection type, and select the provisioned endpoint.
3. Select **Drivers** as the connection method, and copy the connection string.
1. **Create a Target Group**:
1. Obtain the RDS instance's private IP address. Make sure this points to a writable instance.
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.
2. Select at least two subnets in different availability zones.
3. Configure a TCP listener on a port of your choice (for example, `5432`).
4. Associate the listener with the target group from the previous step.
3. **Modify the security group** associated with your RDS instance to permit traffic from the load balancer IP range.
4. **Create a VPC Endpoint Service**:
1. In the AWS Management Console, go to the VPC service and select **Endpoint Services**.
2. Click **Create Endpoint Service**.
3. Select the Network Load Balancer from the previous step.
4. If the load balancer is in one of the PowerSync [AWS regions](#aws-regions), you do not need to select any "Supported Region". If the load balancer is in a different region, select the region corresponding to your PowerSync instance. Cross-region support incurs additional AWS charges.
5. Decide whether to require acceptance for endpoint connections. Disabling acceptance simplifies the process but reduces control over connections.
6. Under **Supported IP address types**, select both IPv4 and IPv6.
7. Note the **Service Name**. You will use this when creating the Private Endpoint in the PowerSync Dashboard.
8. Configure the Endpoint Service to accept connections from the principal `arn:aws:iam::131569880293:root`. See the [AWS documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for details.

The connection string should look something like `mongodb+srv://<db_username>:<db_password>@your-cluster-pl-0.abcde.mongodb.net/`.
</Tab>
</Tabs>

### 5. Deploy
</Step>

Once the Private Endpoint has been created on the PowerSync side, it will be visible in the instance settings
under the connection details, as **VPC Endpoint Hostname**.
<Step title="Create the Private Endpoint in the Dashboard">

Configure the instance the connection string from the previous step, then deploy.
Monitor the logs to ensure the instance can connect after deploying.
In the [PowerSync Dashboard](https://dashboard.powersync.com/), open your organization's **Settings** and locate the **Private Endpoints** section.

</Accordion>
<Accordion title="Custom Endpoint Service for Postgres">
1. Click **Create**.
2. Provide the following details:
* **Name**: a recognizable name for the endpoint (for example, `my-private-endpoint`).
* **Service Name**: the Endpoint Service Name from the previous step (for example, `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`).
* **Region**: the AWS region of your Endpoint Service. This must match the region of the PowerSync instance you plan to use the endpoint with.
3. Click **Create**.

To configure a Private Endpoint Service, a network load balancer is required to forward traffic to the database.
<Note>
A Private Endpoint can only be used by PowerSync instances in the same region. Endpoints in other regions will not appear in the connection form.
</Note>

This can be used with a Postgres database running on an EC2 instance, or an RDS instance.
The endpoint is created in a `Pending` state. Once PowerSync provisions the VPC Endpoint in its VPC, the status transitions to `Pending acceptance` and the **VPC Endpoint ID** (in the form `vpce-<id>`) becomes available on the endpoint's card.

For AWS RDS, the guide below does not handle dynamic IPs if the RDS instance's IP changes. This needs additional work to automatically update the IP — see this [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) on the topic. This is specifically relevant if using an RDS cluster with failover support.
</Step>

Use the following steps to configure the Endpoint Service:
<Step title="Accept the connection on the Endpoint Service">

### 1. Create a Target Group
Copy the **VPC Endpoint ID** from the endpoint's card in the Dashboard and use it to accept the connection on the Endpoint Service side.

1. Obtain the RDS instance's private IP address. Make sure this points to a writable instance.
2. Create a **Target Group** with IP addresses as target type, using the IP address from above. Use TCP protocol, and specify the database port (typically `5432` for Postgres).
<Tabs>
<Tab title="MongoDB Atlas">

<Warning>Note: The IP address of your RDS instance may change over time. To maintain a consistent connection, consider implementing automation to monitor and update the target group's IP address as needed. See the [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) on the topic.</Warning>
In the Atlas Private Endpoint configuration, complete the final step by entering the **VPC Endpoint ID** from the PowerSync Dashboard.

### 2. Create a Network Load Balancer (NLB)
If you have already closed the configuration dialog in Atlas, start the Private Endpoint creation process again. The wizard should show the same Endpoint Service Name as before.

1. Select the same VPC as your RDS instance.
2. Select at least two subnets in different availability zones.
3. Configure a TCP listener and pick a port (for example `5432` again).
4. Associate the listener with the target group created earlier.
</Tab>
<Tab title="Custom Endpoint Service for Postgres">

### 3. Modify the Security Group
If you required acceptance when creating the Endpoint Service, go to **VPC** → **Endpoint Services** in the AWS Management Console, select your service, and accept the connection request matching the **VPC Endpoint ID**.

1. Modify the security group associated with your RDS instance to permit traffic from the load balancer IP range.
If you disabled acceptance, the connection is accepted automatically and no action is needed here.

### 4. Create a VPC Endpoint Service
</Tab>
</Tabs>

1. In the AWS Management Console, navigate to the VPC service and select **Endpoint Services**.
2. Click on **Create Endpoint Service**.
3. Select the Network Load Balancer created in the previous step.
4. If the load balancer is in one of the PowerSync regions (see below), it is not required to select any "Supported Region". If the load balancer is in a different region, select the region corresponding to your PowerSync instance here. Note that this will incur additional AWS charges for the cross-region support.
5. Decide whether to require acceptance for endpoint connections. Disabling acceptance can simplify the process but may reduce control over connections.
6. Under **Supported IP address types**, select both IPv4 and IPv6.
7. After creating the endpoint service, note the **Service Name**. This identifier will be used when configuring PowerSync to connect via PrivateLink.
8. Configure the Endpoint Service to accept connections from the principal `arn:aws:iam::131569880293:root`. See the [AWS documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for details.
</Step>

<Step title="Wait for the endpoint to become Available">

### 5. PowerSync Setup
The endpoint's status in the Dashboard reflects the AWS connection state:

On PowerSync Cloud, create a new instance, but do not configure the connection yet.
| Status | Meaning |
| --- | --- |
| `Pending` | The endpoint is being provisioned. |
| `Pending acceptance` | Waiting for you to accept the connection on the Endpoint Service. |
| `Available` | Ready to use. |
| `Rejected` | The connection was rejected by the Endpoint Service. |
| `Failed` | Endpoint creation failed. |

[Contact us](/resources/contact-us) and provide the Service Name from above, as well as the PowerSync instance ID created above. We will then configure the instance to use the Endpoint Service for the database connection.
Once the status changes to `Available`, the endpoint can be selected when configuring a database connection.

### 6. Deploy
</Step>

Once the Private Endpoint has been created on the PowerSync side, it will be visible in the instance settings
under the connection details, as **VPC Endpoint Hostname**.
<Step title="Connect your database using the Private Endpoint">

Verify the connection details, and deploy the instance. Monitor the logs to ensure the instance can connect after deploying.
1. In the Dashboard, open the PowerSync instance and go to the **Database Connections** view.
2. Click **Connect to Source Database** (or edit an existing connection) and 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 MongoDB Atlas**: 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://<db_username>:<db_password>@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.

</Accordion>
</AccordionGroup>
</Step>
</Steps>

## AWS Regions

PowerSync Cloud currently runs in the AWS regions below. Make sure the region matching your PowerSync instance is supported by the Endpoint Service.

1. US: `us-east-1`
2. EU: `eu-west-1`
3. BR: `sa-east-1`
4. JP: `ap-northeast-1`
5. AU: `ap-southeast-2`
1. US: `us-east-1`
2. EU: `eu-west-1`
3. BR: `sa-east-1`
4. JP: `ap-northeast-1`
5. AU: `ap-southeast-2`
2 changes: 0 additions & 2 deletions resources/security.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@ SOC 2 Type 2 audit reports are available to customers on the [Team and Enterpris

See [Private Endpoints](/configuration/source-db/private-endpoints) for using a private network to your database using AWS PrivateLink.

We use Private Endpoints instead of VPC peering, to ensure that no other resources are exposed between VPCs.

### HIPAA Compliance

PowerSync Cloud is HIPAA compliant. You can sync Protected Health Information (PHI) or electronic PHI (ePHI) using PowerSync Cloud provided that you fulfill your obligations under our shared responsibility model. Refer to our [HIPAA Compliance](/resources/hipaa) page for details.
Expand Down