Netlify Docs
Ask Netlify

Contact

Integrations /

PolyScale Integration

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. Once you have created an account and completed the verification process, you will be redirected back to the Netlify UI to complete setting up your integration.

The PolyScale Integration is enabled at a site level and must be enabled for each site you want to use with the integration. 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. Select Connect and follow the prompts to connect to your PolyScale account.

Please note, once you connect to your PolyScale account, this connection is shared across all sites on which you enable the PolyScale Integration. If you want to use a different PolyScale account for a site, you must disconnect from your current account and then select Connect to connect to a different account.

# 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.

# Connect an existing cache

  1. Select Connect existing cache.

  2. Select the name of the cache from the Database caches menu.

  3. 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.

  4. Enter your Database name.

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

  6. Select Connect cache.

# Create a new cache

  1. Select Create new cache.

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

  3. Select your Database provider name from the menu.

  4. Enter the Host, Port, and Database 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.

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

  6. Select Create cache.

When successful, find your cache listed in the Database 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 > View to access your integrated caches. In the Database caches menu select the cache you want to unlink and then select Unlink cache. Unlinking the cache from the integration doesn’t delete it from your PolyScale workspace.

# Disconnect from PolyScale

You can disconnect from the PolyScale account you connected to Netlify.

Disconnecting will delete all integrated caches

By disconnecting from PolyScale, any integrated caches are deleted from Netlify but will remain in your PolyScale workspace. If you want to delete your caches from PolyScale, you must do so from your PolyScale workspace.

Any other site on which you have enabled the PolyScale Integration will also be disconnected from your PolyScale account.

To disconnect from PolyScale, navigate to the Netlify UI and select your site, then select Integrations > Database > PolyScale > View > Disconnect and then select Disconnect again to confirm.

# Disable the integration

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

# More resources