Upstash Redis and Koyeb

Upstash (opens in a new tab) is a data platform that provides serverless Redis, Kafka, and QStash databases for high performance web applications, functions, and edge computing. Using Upstash, you can quickly deploy databases to multiple regions, scale effortlessly, and benefit from low latency durable storage using standard tooling.

This guide explains how to connect an Upstash Redis data store as a database cache with an application running on Koyeb. To successfully follow this documentation, you will need to have:

If you already have a freshly created Upstash Redis database running and want to quickly preview how to connect your Upstash database to an application running on Koyeb, use the Deploy to Koyeb button below.

Deploy to Koyeb (opens in a new tab)

Make sure to replace the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables with the values for your Upstash database.

Create an Upstash Redis database

To create an Upstash Redis database, sign into your Upstash account (opens in a new tab).

In the Upstash console, select Redis from the top navigation bar. On the Redis page, click Create database:

  1. In the Name field, choose a name for your database. In this example, we'll use example-koyeb-upstash.
  2. Select the Type of deployment you want. Because this is demo does not have global requirements, we will use "Regional" in this guide to limit the choices we have to make.
  3. In the Region drop-down menu, choose a location that's geographically convenient for your database and users. We use "N. Virginia (us-east-1)".
  4. Select your preferred options. In this example, we will select "TLS (SSL) Enabled" so that connections to the database are encrypted and "Eviction" so that older data will be purged when we run out of space.
  5. Click Create to provision the Redis database.

Retrieve your Upstash URL and token

On your Upstash Redis page, scroll down to the REST API section of the page.

Click on the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN buttons to copy their respective values to your clipboard. Paste the copied values to a safe location so that you can reference them later when testing and deploying your application.

Alternatively, you can click on the @upstash/redis tab to view a code snippet:

import { Redis } from '@upstash/redis'
const redis = new Redis({
const data = await redis.set('foo', 'bar')

When you copy the code block using the provided copy button, the code snippet, along with your database's URL and access token will be copied to your clipboard. While this works well for private or demonstration code, it generally isn't good practice to hard-code sensitive data like tokens within your application. To avoid this, we will configure the application to get these values from the environment instead.

Create a demo application

Next, you can create a simple Node.js application that uses your Upstash Redis database. The application will use the Express (opens in a new tab) web framework to build and serve a simple page and Upstash's own @upstash/redis (opens in a new tab) package to connect to the database.

Install the dependencies

Create a new directory for your demo application and navigate to the new location:

mkdir example-koyeb-upstash
cd example-koyeb-upstash

Within the new directory, generate a package.json file for the new project using the default settings:

npm init -y

Next, install the @upstash/redis package so that you can connect to your Redis database from within the application and the express package so that we can build a basic web application:

npm install @upstash/redis express

Create the application file

Now, create a new file called index.js with the following contents:

// Note: if you are using Node.js version 17 or lower,
//       change the first line to the following:
// const { Redis } = require ("@upstash/redis/with-fetch");
const { Redis } = require('@upstash/redis')
const express = require('express')
const app = express()
const redis = Redis.fromEnv()
app.get('/', async (req, res) => {
  const value = await redis.get('counter')
  await redis.set('counter', parseInt(value || 0) + 1)
  res.send(`Counter: ${value || 0}`)
const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)

If you are running Node.js version 17 or lower, you need to adjust the first line of the app to import from the @upstash/redis/with-fetch instead of @upstash/redis (see the code comment at the top of the file). Node.js versions prior to 18 did not natively support fetch API, so you need to change the import path in order to access that functionality.

This above code will introduce a simple counter key to your Redis database. It will use this key to store the number of times the page has been accessed and display that value on the page.

Add the run scripts

Finally, edit the package.json file to define the scripts used to run the application. The dev script runs the application in debug mode while the start script starts the application normally:

  "name": "example-koyeb-upstash",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "DEBUG=express:* node index.js",
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@upstash/redis": "^1.20.6",
    "express": "^4.18.2"

Run the demo application locally

Now that the project is set up, you can run the application locally verify that it functions correctly.

In your shell, set and export the variables you copied from your Upstash Redis page:


In the same terminal, you should now be able to test your application by typing:

npm run dev

The application server should start in debug mode, printing information about the process to the display. In your browser, navigate to to see your application. It should show the counter and number of visits you've made: "Counter: 0". The number should increase by one every time you refresh the page.

Press CTRL-c to stop the application when you are finished.

Push the project to GitHub

Once you've verified that the project runs locally, create a new Git repository to save your work.

Run the following commands to create a new Git repository within the project's root directory, commit the project files, and push changes to GitHub. Remember to replace the values of <YOUR_GITHUB_USERNAME> and <YOUR_REPOSITORY_NAME> with your own information:

git init
echo 'node_modules' >> .gitignore
git add .
git commit -m "Initial commit"
git push -u origin main

Deploy the application to Koyeb using git-driven deployment

You can deploy the demo application to Koyeb and connect it to the Upstash Redis database using the control panel or via the Koyeb CLI.

To deploy the using the control panel (opens in a new tab), follow these steps:

  1. Click Create App in the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Choose the GitHub repository and branch containing your application code.
  4. Name your service, for example upstash-service.
  5. Click Advanced to view additional options. Under Environment variables, click Add Variable to add two new variables called UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN. Populate them with the values you copied for your Upstash Redis database.
  6. Name the App, for example upstash-demo.
  7. Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

Deploy the application to Koyeb using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the application, start by adding a file called .dockerignore to the project's root directory. Paste the following contents to limit the files copied to the Docker image:


Afterwards, create a Dockerfile in your project root directory and copy the content below:

FROM node:18-alpine AS base
FROM base AS deps
RUN apk add --no-cache libc6-compat
COPY package.json package-lock.json ./
RUN npm ci
FROM base AS runner
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nodejs
COPY --from=deps /app/node_modules ./node_modules
COPY . .
USER node
CMD ["npm", "run", "start"]

The Dockerfile above provides the minimum requirements to run the sample Node.js application. You can easily extend it depending on your needs.

Be sure to set the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables to the values you copied from the Upstash console when you deploy the container in the Koyeb control panel.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the Deploy an app from a Docker image documentation.

A Koyeb App and Service will be created. Your Docker image will be pulled and deployed to Koyeb. Once the deployment has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

Delete the example application and Upstash Redis database

To delete the example application and the Upstash Redis database and avoid incurring any charges, follow these steps:

  • From the Upstash console (opens in a new tab), select your Redis database and scroll to the bottom of the Details page. Click Delete this database and follow the instructions.
  • From the Koyeb control panel (opens in a new tab), select your App. Click the Settings tab, and click the Danger Zone. Click Delete App and follow the instructions. Alternatively, from the CLI, you can delete your Koyeb App and service by typing koyeb app delete example-koyeb-upstash.