Skip to main content

Vercel

This guide explains how to connect Vercel to a PolyScale database cache.

When working with Vercel, whether with apps running Next.js, other frameworks, or using serverless functions, the addition of PolyScale can dramatically increase database performance. It does this by intelligently caching data, close to the Vercel application servers. 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, for faster connectivity and data transfer.

Use Case​

This tutorial assumes that you have already connected a database to a Vercel application or serverless function. If you have not done so yet, you can read more about connecting a database to Vercel here. Note that Vercel Edge Functions are not yet supported as they do not allow connections to the database over TCP. However, we do expect to be able to provide support in the coming months. Please email support@polyscale.ai to be added to our Vercel Edge Function beta wait list.

To connect to your database via PolyScale instead, it is as simple as creating a PolyScale cache, and then replacing your original database connection details with those provided by PolyScale.

Step 1: Create PolyScale Cache​

Before creating a PolyScale cache, make sure you have your current database host and port credentials, as you will need them to set up PolyScale.

  • In your PolyScale account, click on the New Cache button
  • 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

When you create your cache, 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.

tip

PolyScale will automatically run a network connectivity test to ensure your database is accessible from all PolyScale PoPs. Be sure that you have added PolyScale's source IP addresses to your allow-list. You can read more here.

Step 2: Connect to your PolyScale Cache​

To connect to the origin database via PolyScale simply update any client applications as follows:

Step 2.1: Use a PolyScale database hostname and port:​

Hostname:​

Using your PolyScale cache is simple -- instead of connecting to your database directly, you'll replace your original host with the PolyScale host - psedge.global.

Port:​

Depending on your database type, select the appropriate port choice below.

  • MySQL: 3306
  • MariaDB: 3307
  • PostgreSQL 5432
  • SQL Server 1433

Step 2.2: Provide a PolyScale Cache ID as part of the connection string:​

The Cache ID tells PolyScale where to route your database traffic, and as such must be passed as part of your connection URI.

The Cache ID can be found under the Settings tab of any cache (as detailed in Step 2 above). For MySQL, MariaDB and SQL Server, this is prepended to the database username separated with a hyphen. For PostgreSQL, an application_name property containing the PolyScale Cache ID is required as part of the connection string e.g. application_name=my_cache_id.

For further details, see Getting Connected.

Step 2.3: Update your Vercel environment variables​

Typically, your database credentials for Vercel are stored in an environment variable (usually as DATABASE_URL by default), using the full database Connection URI, which includes your username, password, host, port and database name. To connect your PolyScale cache, simply update the value for your DATABASE_URL environment variable to use the PolyScale connection URI (making the changes indicated in Step 2.1 and Step 2.2 above) in place of your original.

You can always find the PolyScale connection URI on the Connect tab for your PolyScale cache. Copy this string, and insert your USERNAME, PASSWORD, and DATABASE name in the indicated places.

Your Vercel enviornment variables can be set through the Vercel UI Under Settings and then choosing the Environment Variables page. You can edit the value of an existing environment variable by clicking the menu at the bottom left as show in the image below.

Alternatively, you can update environment variables through the Vercel CLI:

vercel env add DATABASE_URL

You will be prompted for the value, which should be the PolyScale database URI. You can specify which environments (Production, Preview, or Development) you want this variable to apply to.

tip

If you have already created a DATABASE_URL environment variable, you will have to first delete it to add a new one via CLI.

vercel env rm DATABASE_URL

That's it. Now your Vercel application/serverless function is connected to PolyScale. Database queries will be automatically cached (unless configured otherwise) to speed up query execution times and lower network latency.