Database Caching for Cloudflare Workers with PolyScale.ai Serverless

Sam Aybar

May 22, 2023

Introduction

When using Cloudflare Workers, the addition of PolyScale’s database cache can dramatically increase database performance. It does this by intelligently caching data, close to the Cloudflare Worker. This has two primary benefits: decrease database query execution times (all cached queries execute sub-millisecond) and dramatically reduce network latency by being physically closer. Additionally, PolyScale also supports database connection pooling for faster connectivity.

PolyScale is particularly attractive to use in conjunction with Cloudflare Workers because Workers are designed to execute close to the user, which means they execute in multiple locations, often far from the source data.

PolyScale.ai is a serverless, plug-and-play database cache. It dramatically accelerates database read performance, lowers network latency and reduces database infrastructure costs. PolyScale is plug-and-play requiring no code to implement, and zero configuration or tuning. It can be implemented in minutes with a simple configuration change. PolyScale offers a global edge network SaaS platform as well as a self hosted option.

This guide explains how to connect Cloudflare Workers to any database supported by PolyScale (including Postgres, MySQL, MariaDB and MS SQL Server) using PolyScale.ai’s Serverless API for SQL over HTTP.

Cloudflare Workers Overview

Cloudflare Workers provides a serverless execution environment that runs as close as possible to the user. Utilizing Chrome V8, Cloudflare Workers provide extremely fast runtime startups, eliminating the delays of cold starts. With a network of nearly 300 locations, Cloudflare claims to be within 50 milliseconds of 95% of the Internet-connected world population.

When working with databases however, the geographic flexibility of Cloudflare Workers introduces complexity, insofar as scaling databases globally means either tolerating high latency from distant locations, deploying read replicas, or writing distributed caching logic. While developers using Cloudflare Workers have multiple options for building a home-grown local cache for database queries (see this tutorial for example), PolyScale provides a fully autonomous and distributed high performance cache that can be integrated into a Worker in minutes.

The PolyScale Serverless API

As well as native TCP, PolyScale also supports a lightweight API that processes SQL queries via HTTP. The HTTP requests are processed (SQL extracted) and proxied through to the database at the closest PolyScale PoP, using native database TCP connectivity from the PoP to the database.

Connection Pooling

A significant overhead of serverless environments that lead to performance issues, is the cost of initalizing new TCP connections back to the database. The TLS handshake, along with the database specific authentication handshake can take hundreds of milliseconds to complete, depending on the geographic locations of the client and database server. As part of the Serverless API, PolyScale supports connection pooling for all supported databases. Once a connection has been established, it is held open (for a configurable period) for reuse. In the Cloudflare Worker context, this is extremely effective. The TCP based TLS handshake is no longer part of the Worker request roundtrip and hence the latency is reduced down to only the HTTP request and TLS handshake between the Worker and the closest PolyScale PoP.

Benefits

With PolyScale being geographically closer to the Cloudflare Worker than the database, connection pooling in place, cache hits are served at very low latency with massive concurrency.

PolyScale has a TS/JS Fetch API-compatible Serverless Client which can be used to simplify access to the API.

Prerequisites

To connect a Cloudflare Worker to a database via PolyScale, you will need to have:

A Cloudflare Account, and a basic Cloudflare Worker deployed
A Postgres, MySQL, MariaDB or MS SQL Server database that is connected to the internet and can be accessed from the PolyScale edge network.
A PolyScale Account (Sign up for free here.)

Getting Connected

In order to connect Cloudflare Workers to PolyScale via the Serverless API, follow the steps below.

Step 1: Create PolyScale Cache

The first step is to create a PolyScale cache. A cache in the PolyScale context simply identifies your database hostname and port, so make sure you have these to hand.

In your PolyScale account, click on the New Cache button (top right corner)
Give the cache a Name
Select the Type of database you have
Enter the Host address for your existing database
Enter the Port used for your existing database
Click Create

Once created, PolyScale will automatically run a network test to ensure it can make a TCP connection to your database from all edge network regions. If you see any locations that cannot connect, you can add their source IP’s to your database IP Allow List.

You now have a working database cache configured! Now, just connect the Worker to the cache. To do this, note the application_name value from your cache for use in Step 2 below. This contains the cacheId that will be used as part of the connection string.

Step 2: Connect a Worker to your PolyScale Cache

This connection method uses the PolyScale Serverless Client to connect from your Cloudflare Worker to PolyScale.

First, in your Cloudflare Worker project install the PolyScale Serverless Client:

npm install @polyscale/serverless-js

Then use the following code in your Worker

import { Client } from "@polyscale/serverless-js";

export interface Env {
  CACHE_ID: string;
  USERNAME: string;
  PASSWORD: string;
  DATABASE_NAME: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const polyscale = new Client("https://serverless.aws.polyscale.global", {
      cacheId: env.CACHE_ID,
      username: env.USERNAME,
      password: env.PASSWORD,
      database: env.DATABASE_NAME,
      provider: "mysql", // mysql, postgres, mariadb or mssql
    });

    const result = await polyscale.query("SELECT 1;");
    return new Response(JSON.stringify(result));
  },
};

You can then use Wrangler secrets to securely store your database credentials. The username, password, and database will be the credentials you use to connect to your database directly; the cache ID value is the application_name copied in Step 1 above.

To easily upload credentials in bulk, create a .json file as follows:

//secrets.json
{
    "CACHE_ID": "MY_CACHE_ID",
    "USERNAME": "MY_DB_USER",
    "PASSWORD": "MY_DB_PASS"
    "DATABASE": "MY_DB_NAME"
}

Then use the following wrangler secret:bulk command:

wrangler secret:bulk secrets.json

See Cloudflare Docs here for complete documentation of the wrangler secret:bulk command.

Finally, you can deploy your Worker with:

wrangler deploy

For reference, you can also find an example Cloudflare Worker function using the Serverless Client here.

That’s it. Now your Cloudflare Worker is connected to PolyScale. Database queries will be automatically cached (unless configured otherwise) to speed up query execution times and lower network latency. Note that PolyScale will expect a few repeat queries (typically 3) before serving a cache hit. You can read more about the time to first hit here.

Performance

With your Cloudflare Worker connected via PolyScale, you can expect improved query response times not only for cache hits, but also cache misses and writes. This is because PolyScale maintains a connection to the database and does not need to re-establish it for each time the Worker executes. While specific results may vary, the chart below illustrates how PolyScale Serverless delivers lower latency for simple queries, complex queries, and even writes.

Summary

For data-driven and data-intensive uses case with Cloudflare Workers, PolyScale provides a global low latency cache and connection pool, without the need to develop cache logic. PolyScale’s lightweight Serverless client provides HTTP connectivity to any PolyScale supported database (including MySQL, Postgres, MariaDB and MS SQL Server) in minutes.

If you didn’t already set up a PolyScale account to try this tutorial, sign up for your own free PolyScale account here (no credit card required). Connect your database to a Cloudflare Worker and start delivering your data around the globe, faster.

Written by