Neon Serverless Postgres

This guide explains how to connect a Neon Postgres database to a PolyScale cache and how to work with Neon branches in conjunction with PolyScale. Neon is a Postgres compatible database. Neon offers an integration with PolyScale that allows you to create a PolyScale cache directly from your Neon database. A Neon database instance can also be connected to PolyScale just like any other database. Read on for details of working with Neon and PolyScale via the integration or directly.

Neon PolyScale Integration

tip

The Neon integration with PolyScale creates a cache only for the read-write compute endpoint associated with the primary branch of your Neon project. It does not cache queries for read-only compute endpoints or non-primary branches. If you want to create a PolyScale cache for those, please follow the manual setup process below.

The instructions below show you how to create enable the PolyScale integration from within Neon. This integration allows the automated creation of a cache for the primary branch of your Neon database. This cache functions like any other PolyScale cache. Additional documentation from Neon about the integration can be found on Neon's website

Adding the PolyScale Integration

To add the PolyScale integration to your Neon project:

1. In the Neon Console, navigagte to the Integrations page for your project.

2. Under the Available section, click Add to open the Add PolyScale drawer

   

3. Under How to add, click Sign in. If you already have a PolyScale account, you can sign in using Google, GitHub or email. If you do not already have a PolyScale account, you can create one by clicking the Click here to sign up! link at the bottom of the page.

   

4. Select the desired PolyScale Workspace and click Authorize Access to allow Neon to have API access to caches in your workspace. This allows Neon to create and manage the cache associated with your Neon database.

   

5. The integration has now been added and your cache is created. You are returned to the Integrations page in the Neon Console where the PolyScale integration appears under the Manage heading and the Manage PolyScale drawer is open.

   

Here, you can view information about your newly created PolyScale cache and copy the PolyScale connection string. Use this connection string in place of your Neon connection string in your application.

You can use the drop-down menus for Database and Role to modify your connection string for any other databases and roles on the primary branch of your Neon project.

caution

To ensure your cache remains current, always use the PolyScale connection string. Modifying your database directly through a Neon connection string or the Neon SQL Editor can result in an outdated cache.

Accessing your PolyScale cache from Neon

You can access the PolyScale dashboard for your cache directly from the Neon PolyScale integration.

1. In the Neon Console, navigate to the Integrations page.

2. Under Manage, locate the PolyScale integration and click Manage to open the Manage PolyScale drawer.

3. Click the View cache in PolyScale link. You will be directed to PolyScale where you will be required to log in if not logged in already.

Purging your PolyScale cache from Neon

If you have made changes to your Neon database through a direct connection (either via a Neon connection string or via the Neon SQL editor), you may want to purge your PolyScale cache to ensure stale data is purged immediately. You can do this via the Neon integration.

To purge your PolyScale cache:

1. In the Neon Console, navigate to the Integrations page.
2. Under Manage, locate the PolyScale integration and click Manage to open the Manage PolyScale drawer.
3. Click Purge PolyScale cache. Purging the cache purges all cached data globally.

Removing the PolyScale Integration

To remove the PolyScale integration from Neon:

1. In the Neon Console, navigate to the Integrations page.
2. Under Manage, locate the PolyScale integration and click Manage to open the Manage PolyScale drawer.
3. Click Remove integration.

Removing the integration deletes the cache and terminates all current connections using the PolyScale connection string. If you create your PolyScale cache via the integration, it is best to delete the cache by removing the integration.

Manual Setup

The video below illustrates how to get connected. Or you can read the steps below.

Step 0: Create a PolyScale account

If you do not already have a PolyScale account, you can create an account here. PolyScale offers a free tier and no credit card is required.

Step 1: Create your PolyScale Cache

1.1 Retrieve your Neon Host

In your Neon project, from the Connection details section of your Dashboard, you can find your host name within the Connection string. Be sure you have selected the Branch for which you wish to add a PolyScale cache.

1.2 Configure your PolyScale Cache

• In your PolyScale account, click on the New Cache button
• Give the cache a Name
• Select PostgreSQL for the Type
• Enter the Host from Step 1.1 above
• Enter 5432 for the Port
• Click Create

Your cache is now created. PolyScale automatically checks to see that your database is accessible from all our global PoPs.

Step 2: Connect to your PolyScale Cache

Using your PolyScale cache is simple -- instead of connecting to your Neon database directly, you'll replace your original connection string with the PolyScale connection string in your application.

For example, if your original connection string was: postgres://postgres:zqGHFAbPLvVCKw@ep-black-flask-024570.ap-southeast-1.aws.neon.tech:5432/neondb

Your PolyScale connection string might be: postgres://postgres:zqGHFAbPLvVCKw@psedge.global:5432/neondb?application_name=590174cd-2dde-4bf0-adab-2cc5c55cd6ea

tip

If the client you are connecting from does not enable SSL by default (eg PG), you will need to append a sslmode=require parameter to your Neon connection string, whether connecting directly or via PolyScale.

That's it.

Using Neon Branches with PolyScale

If you are using Branching in Neon and would like to connect PolyScale to multiple branches, a best practice approach is to create a separate PolyScale Cache for each branch. This allows you to work on each branch independently and not run the risk of mixing cached data across branches, which may be undesirable. There is no additional cost for creating an additional Cache for the branch. Finally, be sure when creating the Branch to create an endpoint.

To create the new branch with an associated PolyScale Cache, simply create the new Cache using the hostname of the new branch. That will provide a new cache id which is then passed in as part of the connection string using the application_name parameter.

So, if the connection string for your orignal branch via PolyScale was: postgres://postgres:zqGHFAbPLvVCKw@psedge.global:5432/neondb?application_name=590174cd-2dde-4bf0-adab-2cc5c55cd6ea

The connection string for your new branch might be: postgres://postgres:zqGHFAbPLvVCKw@psedge.global:5432/neondb?application_name=7e011c18-2cd0-4995-8c9d-ebe66a1dd393

You now have a PolyScale cache you can use in conjunction with your Neon database branch.