Private connectivity - AWS PrivateLink

August 20, 2025

Connecting to PlanetScale for Postgres privately via AWS PrivateLink

AWS PrivateLink is a highly available, scalable technology that enables you to privately connect your VPC to supported AWS services, VPC endpoint services, and AWS Marketplace partner services. When you use AWS PrivateLink, your network traffic between your VPC and PlanetScale stays within the AWS network, without traversing the public internet.

When to use AWS PrivateLink

By default, PlanetScale for Postgres databases use secure connections over the public internet with industry-standard TLS encryption. This approach is secure and meets the needs of most customers. However, you may want to consider AWS PrivateLink if:

• Compliance requirements: Your organization has regulatory or compliance mandates that require database connections to avoid the public internet entirely
• Enhanced security posture: You want an additional layer of network isolation for sensitive data workloads
• Network architecture: Your existing AWS infrastructure is designed around private connectivity patterns
• Reduced network latency: AWS PrivateLink can help reduce latency by avoiding the extra network hop through a NAT gateway that's typically required for outbound internet connections from private subnets. While this latency difference is often minimal (typically single-digit milliseconds), it may be noticeable if you're migrating from a database that was previously hosted directly within your VPC

AWS PrivateLink provides these security and compliance benefits by ensuring your database traffic never leaves the AWS backbone network.

PrivateLink pricing

PlanetScale does not charge any additional fees for AWS PrivateLink connectivity. However, AWS charges standard PrivateLink pricing for VPC endpoints, which includes:

• VPC endpoint hourly charges: ~$0.01 per hour per VPC endpoint (varies by region)
• Data processing charges: ~$0.01 per GB of data processed through the VPC endpoint (varies by region)

For current pricing in your region, see the AWS PrivateLink pricing page.

Prerequisites

• A PlanetScale for Postgres database in an AWS region
• An AWS VPC in the same region where you want to establish the private connection
• Appropriate AWS IAM permissions to create VPC endpoints (see AWS VPC endpoint permissions documentation)
• Appropriate AWS IAM permissions to create and modify Security Groups (see AWS IAM permissions for security groups documentation)

Establishing a VPC endpoint

1. Contact PlanetScale Support: Reach out to PlanetScale support to request AWS PrivateLink access for your organization. Provide your:

   • Organization name
   • Database name
   • Database branch name
   • AWS region (referred to as <aws-region> below)
   • AWS account ID

   The PlanetScale Support team will provide for you an endpoint that has the format of: com.amazonaws.vpce.<aws-region>.vpce-svc-<ID>

   Save this ID for your records and the rest of the configuration.

2. Create a Security Group for the Endpoint: You will need an AWS Security Group configured to allow inbound traffic for the required ports. You can configure access using either the security group ID of your application hosts, your VPC's CIDR configuration, or specific subnet CIDR configurations. Ensure your security groups allow:

   • Inbound PostgreSQL (port 5432): For direct database connections
   • Inbound PgBouncer (port 6432): For pooled connections via PgBouncer

   An example using the AWS CLI:

   # Create the security group (capture its ID)
   SG_ID=$(aws ec2 create-security-group \
   --group-name PScalePrivateLinkEndpointSG \
   --description "Security group for PlanetScale PrivateLink endpoint" \
   --vpc-id <your-vpc-id> \
   --query 'GroupId' --output text)
   
   # Option A (preferred): allow only from a client SG (replace sg-CLIENT)
   aws ec2 authorize-security-group-ingress \
      --group-id "$SG_ID" \
      --ip-permissions '[
        {"IpProtocol":"tcp","FromPort":5432,"ToPort":5432,"UserIdGroupPairs":[{"GroupId":"sg-CLIENT"}]},
        {"IpProtocol":"tcp","FromPort":6432,"ToPort":6432,"UserIdGroupPairs":[{"GroupId":"sg-CLIENT"}]}
      ]'
   
   # Option B: allow from entire VPC CIDR (replace with your actual CIDR)
   #aws ec2 authorize-security-group-ingress \
   #--group-id "$SG_ID" \
   #--ip-permissions '[
   #   {"IpProtocol":"tcp","FromPort":5432,"ToPort":5432,"IpRanges":[{"CidrIp":"10.0.0.0/16"}]},
   #   {"IpProtocol":"tcp","FromPort":6432,"ToPort":6432,"IpRanges":[{"CidrIp":"10.0.0.0/16"}]}
   #]'
   

   Replace <your-vpc-id> with your actual VPC ID. You can find your VPC ID and its CIDR block using:

   aws ec2 describe-vpcs --query 'Vpcs[*].[VpcId,CidrBlock]' --output table
   

3. Navigate to VPC Endpoints: In your AWS Console:

   1. Confirm you are in the proper <aws-region> from the dropdown on the top right
   2. In the search field at the top left enter "Endpoints".
   3. Click the link listed as a VPC Feature.

   

4. Create a new endpoint: Click "Create Endpoint".

   

5. Select endpoint type: Choose "Endpoint services that use NLBs and GWLBs".

   

6. Enter service name: Enter in the "Service name" text box the VPC endpoint service name provided by PlanetScale support. Click "Verify service" to confirm the service exists.

   

7. Configure VPCs: Choose the VPC that should have access to the PlanetScale service endpoint.

8. Enable DNS names: Click the "Additional settings" dropdown arrow to reveal DNS configuration options, and select the "Enable DNS name" checkbox.

9. Configure Subnets: Choose the Subnets that should have endpoint interfaces for the PlanetScale service endpoint. It is recommended you select at least 2. You should select subnets that your application servers have access to.

   

10. Configure security groups: Choose the appropriate security group to control which resources can send traffic to the PlanetScale service endpoint. Use the one created earlier if you created one for this purpose.

    

11. Create the endpoint: Click "Create endpoint" and wait for the VPC endpoint status to show "Available" (this may take several minutes).

    

Verifying your VPC endpoint connectivity

1. Confirm endpoint status: In the AWS Console, verify that your endpoint's status shows "Available".

2. Test DNS resolution: From an EC2 instance in your configured VPC, run a DNS lookup to confirm resolution to your VPC's IP range. You can find the Private DNS names on the details tab in the console (see previous screenshot)

   dig +short <YOUR ENDPOINT>.private-pg.psdb.cloud
   10.0.2.120
   10.0.1.118
   

3. Test your new connection:

   Once you have modified your security groups and/or NACLs, test the private endpoint:

   psql 'host=<YOUR ENDPOINT>.private-pg.psdb.cloud port=5432 user=postgres.XYZ234 password=pscale_pw_REDACTED dbname=postgres sslnegotiation=direct sslmode=verify-full sslrootcert=system'
   

Update your connection strings

Once your VPC endpoint is established and verified, you're ready to update your application's connection strings to use the private endpoint address instead of the standard public endpoint.

Security group considerations

Ensure your security groups allow:

• Outbound PostgreSQL (port 5432): For direct database connections
• Outbound PgBouncer (port 6432): For pooled connections via PgBouncer
• Inbound - any application-specific ports: Based on your connection requirements

For more details about connection types and when to use each port, see our connection documentation and PgBouncer guide.

Network ACL considerations

VPC Network ACLs (NACLs) operate at the subnet level and provide an additional layer of security beyond security groups. For AWS PrivateLink connections to PlanetScale, ensure your NACLs allow:

• Outbound PostgreSQL (ports 5432, 6432): For database connections
• Ephemeral ports (1024-65535): For return traffic from AWS PrivateLink endpoints

Most default NACL configurations allow all outbound traffic and are compatible with PrivateLink. If using custom restrictive NACLs, add explicit allow rules for the above ports.

Troubleshooting

If you're experiencing connectivity issues:

1. Verify endpoint status: Ensure your VPC endpoint shows "Available" status
2. Check security groups: Confirm your security groups allow the required ports
3. Check NACLs: Confirm that your VPC's NACLs are configured to allow the right network traffic
4. Test DNS resolution: Verify DNS is resolving to private IP addresses in your VPC CIDR range
5. Use AWS Reachability Analyzer: The Reachability Analyzer allows you to inspect the path between two resources (such as a client and your PlanetScale for Postgres endpoint) and provides guidance on why connectivity might be failing
6. Contact support: If issues persist, contact PlanetScale support with your endpoint configuration details

Next steps

• Learn about PostgreSQL roles and permissions
• Configure connection pooling with PgBouncer
• Monitor your connections and performance

Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.