Skip to main content
VPC peering gives your cloud network the shortest path to your Neki database. Clients connect straight to the routers with no load balancer in between. This gives you:
  • Lower latency. Each query skips the network hop through the PlanetScale load balancer.
  • Lower cross-zone costs. Per-zone hostnames keep each client’s connections inside its own zone. That avoids cross-zone latency and data transfer charges.
  • Private traffic. Traffic stays off the public internet.
PlanetScale peers its network with yours and configures its side of the connection. You accept the peering in your cloud account. You then configure routes and network access and set up DNS for the private hostnames.
VPC peering is available for single-tenant and PlanetScale Managed Neki deployments in AWS and GCP. It is not available in multi-tenant regions. PlanetScale must enable VPC peering for your deployment before you can use it. Contact your PlanetScale Solutions Engineer to enable it. Peering does not disable the public endpoint. Clients must use the private hostnames to connect over the peering connection.

Set up VPC peering

The setup steps depend on your cloud provider: For GCP contact your PlanetScale Solutions Engineer.

Compare with private endpoints

Hostnames

Each router group gets one hostname for all of its zones and one hostname per zone:
  • <ROUTER_GROUP> is the router group name such as default.
  • <BRANCH_ID> is the branch ID.
  • <ZONE_ID> is the zone ID on AWS such as use1-az1. It is the zone name on GCP such as us-central1-a. AWS maps zone names to different physical zones in each account, so Neki uses the zone ID there.
  • <DNS_SUFFIX> ends in .direct.psdb.cloud. PlanetScale supplies it.
For example:
The router group hostname resolves to the routers in every zone. A per-zone hostname resolves only to the routers in that zone. Use it to keep connections inside the client’s zone and avoid cross-zone latency and data transfer charges.
A per-zone hostname has no automatic failover. If that zone is impaired or unavailable then connections to its hostname fail or time out. Neki does not move a per-zone hostname to another zone. Your application must handle the fallback itself.
When you use per-zone hostnames give your client a fallback order. For example a client in use1-az1 can:
  1. Connect to the use1-az1 hostname.
  2. If that fails, connect to the hostname of another zone such as use1-az2.
  3. If every per-zone hostname fails, connect to the router group hostname.
Return to the client’s own zone when it recovers. Otherwise the client keeps paying for cross-zone traffic after the zone recovers.

Connection best practices

The hostnames point at individual routers and not at a load balancer. Neki updates the records when routers drain, restart or move, which happens frequently, especially with router auto-scaling enabled. The records have a short TTL. Follow these best practices in your client:
  • Resolve the hostname for every new connection and respect the DNS TTL.
  • Connect with the hostname. Do not put router IP addresses in configuration or connection strings.
  • Spread connections across every address the hostname returns. libpq 16 and later does this with load_balance_hosts=random.
  • Set a maximum connection lifetime in your connection pool such as 5 to 15 minutes.
A client that does not follow these best practices can:
  • Connect to a router that no longer serves it.
  • Send all of its connections to one router while other routers sit idle.
  • Keep long-lived connections on old routers and never use new ones.
The JVM caches DNS results for 30 seconds by default. Set networkaddress.cache.ttl=1 and networkaddress.cache.negative.ttl=3 in the java.security file or with java.security.Security.setProperty before the application does its first lookup.

Connect

The PlanetScale dashboard shows the host and username for VPC peering connections.
1
From the PlanetScale dashboard, select your Neki database.
2
Open Settings, then select Roles.
3
Open the role your application uses.
4
Under Connection details check that the Connection method is VPC peering.
5
Select the Router and the Query target.
6
Copy the Host and Username. To connect to one zone expand Availability zone hostnames and copy the host for that zone.
VPC peering shows a link to this page instead of connection details until VPC peering is set up for the branch. Use the Load balancer connection method in the meantime. The Username for VPC peering differs from the load balancer username. It has no branch suffix because the host already identifies the branch and router group. Use the username that matches the connection method. Then connect with the host, username and password:
Neki accepts VPC peering connections only on port 5432. It requires TLS and refuses plaintext. The routers present a certificate for *.<DNS_SUFFIX>.
sslnegotiation=direct requires PostgreSQL 17 or later. Older clients can omit it and still use TLS.

Troubleshooting

If the hostname does not resolve or the connection fails, check the steps for your cloud provider first. Then:
  1. Add sslmode=verify-full if Neki refuses the connection for not using TLS.
  2. Check that you use the VPC peering username from the dashboard and not the load balancer username.
  3. Ask your Solutions Engineer to check the return routes and access controls on the PlanetScale side.

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.