Netlify Docs
Ask Netlify
Our new chatbot assistant can quickly answer your questions.

Contact

PolyScale Integration

This feature is in BETA.

PolyScale is a global database edge caching platform. PolyScale caches database data locally to users, reducing latency and accelerating read performance and scaling throughput. You can use PolyScale to add a cache in front of your existing databases.

With the PolyScale Integration on Netlify, you can create a PolyScale cache from the Netlify UI, execute queries against your cache within your serverless functions, and use code snippets generated in the Netlify UI to get started.

# Before you begin

To use the PolyScale Integration, you need a database on which you want to add a PolyScale cache. Make sure you have your database credentials, name, host, and port available to set up the integration.

This integration supports the following types of databases:

If you don’t already have a PolyScale account, you can set one up when you enable the integration.

The PolyScale Integration connects Netlify to PolyScale on the site level. To use the integration on multiple sites, follow the steps below for each site on which you want to enable the integration.

# Connect to PolyScale on Netlify

In the Netlify UI:

  1. Select Sites, then the site you want to use with the integration.
  2. Select Integrations > Database > PolyScale > Enable.
  3. Choose to either Connect to existing account if you already have a PolyScale account, or Create account with Netlify.

# Connect to an existing account

If you’re connecting to an existing account, you need to use an API key to connect. To create an API key, in your PolyScale account select your user avatar, then select Settings > Workspace > API Keys. Select Create new to create your key.

Copy the key, then return to the Netlify UI and from your PolyScale Integration page:

  1. Paste the API key into the API Key field.

  2. Select Save.

# Create an account

Alternatively, you can create a new account here. To create a new account, select Create account with Netlify. This emails a sign-up link to the email address associated with your Netlify user. Follow the prompts in the email to complete the sign-up process with PolyScale. When you create an account with Netlify, the API key generates automatically and you can add a cache right away.

# Add a cache

Once you’ve connected to your PolyScale account, the Netlify UI detects any existing caches on your account. You need to add a cache on Netlify to complete the integration.

  1. Select Add cache.
  2. Choose to Create new cache or Select existing cache.

If you choose to select an existing cache:

  1. Select the name of the cache from the menu.

  2. Create an Alias. The PolyScale Integration uses this value in the environment variables created when integrating your cache. For example, if the alias is CUSTOMERS, this integration creates the environment variable POLYSCALE_CUSTOMERS_USERNAME.

  3. Enter the Username and Password associated with your database.

  4. Select Save.

If you choose to create a new cache:

  1. Create an Alias, which the integration uses to create environment variable names as noted above.

  2. Select your Database provider name from the menu.

  3. Enter the Database name, Host, and Port values for your database. These values should correspond to the settings of whatever database you have set up, so make sure you have the connection information for your database available when you configure this.

  4. Enter the Username and Password associated with your database.

  5. Select Save.

When successful, find your cache listed in the Connected caches menu.

Netlify stores your database username and password as environment variables only. They’re not stored anywhere else as part of enabling this integration. Enabling this integration creates environment variables like the following, in this case with the CUSTOMERS example:

POLYSCALE_CUSTOMERS_USERNAME
POLYSCALE_CUSTOMERS_PASSWORD
POLYSCALE_CUSTOMERS_CONNECTION_URI
POLYSCALE_CUSTOMERS_PORT
POLYSCALE_CUSTOMERS_DATABASE

# Call your cache from a function

After you add a cache, you can select the cache you want to use from the Database cache menu. Note that the name of your cache uses the alias you created above.

When you select a cache, the Netlify UI detects the type of database and generates a code snippet you can use to get started. For example, if a CUSTOMERS cache uses Postgres, the following code snippet generates:

import postgres from "postgres";

const sql = postgres(process.env.POLYSCALE_CUSTOMERS_CONNECTION_URI);

You can use this snippet in a serverless function. In a project, you may have a file structure similar to this:

├─ netlify/
   │  └─functions/
   │   └─ customers/
   │     └─ index.ts
   └─package.json

In this example, index.ts is a function that executes a call to the Postgres database to select all customers. The snippet provides the starter code to add to this file. In this example, the snippet has been modified slightly to use TypeScript:

import type { Handler } from "@netlify/functions";
import postgres from "postgres";

const handler: Handler = async function(event, context) {
  const sql = postgres(
    process.env.POLYSCALE_CUSTOMERS_CONNECTION_URI as string
  );

  const customers = await sql`SELECT * from customers`;

  console.log("customers", customers);

  return {
    statusCode: 200,
    body: JSON.stringify({
      customers,
    }),
  };
};

export { handler };

# Test locally

Test your function using Netlify CLI. Run this command to install Netlify CLI:

npm install netlify-cli -g

Use Netlify CLI to test your function locally. After creating a function with the code snippet to call your cache, run:

netlify dev

This injects your new PolyScale environment variables.

When your application runs and the function executes the database query, you can monitor these queries in your PolyScale workspace. In your PolyScale workspace, select Caches > Observability to access your query counts.

You can unlink a cache in the Netlify UI. After selecting your site, select Integrations > Database > PolyScale to access your integrated caches. In the Connected caches menu, select Unlink for the cache you want to unlink. Unlinking the cache from the integration doesn’t delete it from your PolyScale workspace.

# Disable the integration

To disable the PolyScale Integration, navigate to the Netlify UI and select your site, then select Integrations > Database > PolyScale. From the Disable PolyScale menu, select Disable to disconnect PolyScale from your Netlify site.

# More resources

# Feedback

We welcome your feedback on the PolyScale Integration! Fill out our survey to share your thoughts or ideas.