PolyScale and Koyeb

PolyScale (opens in a new tab) is a high-performance, serverless database cache. It dramatically accelerates database read performance, lowers network latency, and reduces database infrastructure costs. PolyScale is plug-and-play, meaning it requires no code to implement and zero configuration or tuning. It can be implemented in minutes by updating the database hostname in your application. PolyScale offers a global edge network SaaS platform as well as a self-hosted option.

This guide explains how to connect a PolyScale database cache to an application running on Koyeb. To successfully follow this documentation, you will need to have:

A Koyeb account (opens in a new tab) to deploy the application. You can optionally install the Koyeb CLI to deploy the application from the command line
A PostgreSQL database. PolyScale works with any PostgreSQL, MySQL, MariaDB, or MS SQL Server database, but the sample application uses PostgreSQL. Some popular managed options include Neon and Crunchy Bridge.
A free PolyScale account (opens in a new tab) for your database cache.

The example application (opens in a new tab) that connects to your PostgreSQL database via PolyScale uses Prisma as an ORM. Prisma is an open-source ORM. We use it to synchronize our database schema with our Prisma schema.

If you already have a freshly created PostgreSQL database running and connected to a PolyScale cache and want to quickly preview how to connect your database with a PolyScale cache to an application running on Koyeb, use the Deploy to Koyeb (opens in a new tab) button below.

(opens in a new tab)

Make sure to replace the DATABASE_URL environment variable in the Koyeb configuration with your PolyScale connection string.

Additionally, you can select multiple Regions (e.g. WAS and FRA) if you want to use PolyScale’s global caching.

Create a PolyScale cache for your PostgreSQL database

If you do not already have a PolyScale account, create an account on PolyScale's sign-up page (opens in a new tab). PolyScale offers a free plan and no credit card is required.

To create a new cache for your PostgreSQL database, click the New Cache button in the upper right corner of the caches dashboard (opens in a new tab).

Fill out the form that appears with the information for your PostgreSQL database:

Cache Name: The name to give the new cache.
DB Type: The type of database this cache is for. For this guide, choose PostgreSQL.
DB Host: The hostname of your PostgreSQL database.
DB Port: The port where PostgreSQL is listening. By default, PostgreSQL listens on port 5432.
Caching? A toggle to enable or disable caching for the database. Leave this in the "on" position for this guide.
Cache Defaults: Determines the default caching behavior for the database. Select "Auto-cached" for this guide.
Description: A human-readable field where you can provide additional information to help you identify and use the cache.

PolyScale new cache form

Once you've filled out the required and optional fields, click the Create button.

A pop-up will appear with the connection information for your new PolyScale database cache. You can use this information to connect your applications to the cache instead of directly to your database. The connection URI will have the following format:

postgres://<USER>:<PASSWORD>@psedge.global:5432/<DATABASE>?application_name=<POLYSCALE_CACHE_ID>

Save the Connection URI value in a safe place. We will use this later as the target for our application.

⚠️

Depending on the version of PostgreSQL you are using, you may see the following error when trying to connect to your database with Prisma via PolyScale:

User `postgres` was denied access on the database `postgres.public`

You can resolve this by adding channel_binding=disable to the list of options in your DATABASE_URL:

DATABASE_URL=postgresql://<USER>:<PASSWORD>@psedge.global:5432/<DATABASE>?application_name=<POLYSCALE_CACHE_ID>&channel_binding=disable

Channel binding (opens in a new tab) is a security measure to ensure that client and server are connecting to each other without anything in the middle. Because PolyScale needs to act as an intermediary between the client and database, channel binding must be disabled.

PolyScale will run a network test to ensure your database is accessible to the PolyScale edge network. If the test fails, adjust your database's firewall to allow the list of PolyScale source IP addresses (opens in a new tab).

Deploy the application on Koyeb

You can deploy on Koyeb using the control panel or via the Koyeb CLI.

To deploy the example application (opens in a new tab) using the Koyeb control panel (opens in a new tab), follow these steps:

Click Create App in the Koyeb control panel.
Select GitHub as the deployment option.
Use the https://github.com/koyeb/example-express-prisma as the GitHub repository and select the main branch.
Name your service (for example polyscale-service).
Click Build and deploy settings to view additional options. Click the Override toggle associated with the Build command field and then set npm run postgres:init as the field value.
Select multiple Regions (e.g. WAS and FRA) to take advantage of PolyScale’s global caching.
Click Advanced to view additional options. Under Environment variables, click Add Variable to add a DATABASE_URL environment variable. Set the value to the Connection URI you copied from PolyScale. Be sure to update the username, password, and database to the values that match your PostgreSQL database.
Name your App (for example polyscale-demo).
Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

The example application exposes a /planets endpoint that you can use to list planets from the database. Once your deployment is live, you should see the following results when navigating to https://<YOUR_APP_URL>.koyeb.app/planets:

[
  {
    "id": 1,
    "name": "Mercury"
  },
  {
    "id": 2,
    "name": "Venus"
  },
  {
    "id": 3,
    "name": "Mars"
  }
]

PolyScale will automatically begin caching queries, intelligently determining how long to cache items for and evicting data when there are updates.

Delete the example application and PolyScale cache

To delete the example application and avoid incurring any charges, complete the following steps:

From the Koyeb control panel (opens in a new tab), select your App. Click the Settings tab, and click the Danger Zone. Click Delete App and follow the instructions. Alternatively, from the CLI, you can delete your Koyeb App and service by typing koyeb app delete polyscale-demo.
If you created a database using a service that charges, delete the database following the database provider's instructions.
With PolyScale, you are only charged for usage that exceeds the free tier. You can find more about the free tier on the PolyScale pricing page (opens in a new tab). To delete the PolyScale cache, click on the cache in your workspace (opens in a new tab). Click the Settings tab of the cache, click the Delete Cache button, and then follow the instructions.

Upstash Terraform