Skip to content
Last updated on June 7, 2023
8 min read

Vercel KV Quickstart

Start using durable Redis with Vercel KV.

Vercel KV is available in Beta on Pro and Hobby plans

In this quickstart, you'll learn how to do the following:

  • Create a KV store called my-store that is connected to one of your projects
  • See how to use the Vercel dashboard to create and manage your database
  • Populate the KV store using the CLI
  • Query the KV store using the SDK

Learn more about how Vercel KV works.

Vercel KV works with any frontend framework. First, install the package:

pnpm i @vercel/kv

Then, install the Vercel CLI so we can retrieve the Environment Variables:

pnpm i -g vercel@latest

Navigate to the Project you'd like to add a KV database to. Select the Storage tab, then select the Connect Database button.

Under the Create New tab, select KV and then the Continue button.

Note: During the Vercel KV beta phase, you must accept the Data Acknowledgement notice that this product should not be considered SOC 2 Type 2 compliant. If this compliance is required by your organization, please do not proceed.

Next, create a new store in the dialog:

  1. Enter my-store (or any other name) under Database Name. The name can not exceed 32 characters
  2. Select a primary region
  3. Click Create & Continue
  4. Select which environments of the project to make the database available to. This determines the scope of the environment variables
  5. Click Connect

Your empty store is created in the primary region specified. This is the region that all write operations will be routed to.

Environment Variables for your KV store were automatically added to your project. These are used to connect to your store. Later in this quickstart, we'll pull them locally so you can use them with your project.

  • KV_URL
  • KV_REST_API_URL
  • KV_REST_API_TOKEN
  • KV_REST_API_READ_ONLY_TOKEN

You can send Redis commands to your KV store with the CLI interface in the dashboard. To access the CLI, select your KV store and go to the CLI tab.

Use the following command to create a user:me hash:

CLI
hset user:me email email@me.com id 123

You can then read the hash with the following command:

CLI
hgetall user:me

The CLI will respond with email, email@me.com, id, 123.

The CLI supports most Redis commands. See our compatibility docs to learn which commands are available.

When you created your KV database, your KV_REST_API_URL and KV_REST_API_TOKEN were created as Environment Variables automatically.

To use these Environment Variables in your code, we recommend pulling them with the following Vercel CLI command:

vercel env pull .env.development.local

You can now retrieve data from your KV Store:

pages/api/user.ts
import { kv } from '@vercel/kv';
import { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  const user = await kv.hgetall('user:me');
  return response.status(200).json(user);
}

To connect to multiple KV stores, use createClient:

pages/api/create-client.ts
import { createClient } from '@vercel/kv';
import { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  const users = createClient({
    url: process.env.USERS_REST_API_URL,
    token: process.env.USERS_REST_API_TOKEN,
  });
 
  const user = await users.hgetall('user:me');
 
  const products = createClient({
    url: process.env.PRODUCTS_REST_API_URL,
    token: process.env.PRODUCTS_REST_API_TOKEN,
  });
 
  const product = await products.hgetall('product:shirt');
 
  return response.status(200).json({ user, product });
}

See our Redis compatibility docs to learn more about available commands.

Run your application locally and visit /api/user to see your data.