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:
- Select Sites, then the site you want to use with the integration.
- Select Integrations > Database > PolyScale > Enable.
- 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:
Paste the API key into the API Key field.
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.
- Select Add cache.
- Choose to Create new cache or Select existing cache.
If you choose to select an existing cache:
Select the name of the cache from the menu.
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 variablePOLYSCALE_CUSTOMERS_USERNAME
.Enter the Username and Password associated with your database.
Select Save.
If you choose to create a new cache:
Create an Alias, which the integration uses to create environment variable names as noted above.
Select your Database provider name from the menu.
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.
Enter the Username and Password associated with your database.
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.
# Unlink a cache
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.
Did you find this doc useful?
Your feedback helps us improve our docs.