Integrations
Databases
CockroachDB

CockroachDB and Koyeb

CockroachDB (opens in a new tab) is a cloud-native distributed SQL database built for speed, durability, and scale. It scales horizontally, survives disk and data center failures, and supports strongly-consistent ACID transactions all while providing a familiar SQL API for querying data.

This guide explains how to connect a CockroachDB serverless database to an application running on Koyeb. To successfully follow this documentation, you will need to have:

The application that connects to the CockroachDB database uses Prisma as an ORM. Prisma is an open-source ORM. We use it to synchronize our database schema with our Prisma schema.

If you already have a freshly created CockroachDB database running and want to quickly preview how to connect your 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 DATABASE_URL environment variable with the connection string of your CockroachDB database.

Create a CockroachDB database

To create a CockroachDB database, sign in to your CockroachDB account (opens in a new tab).

On the CockroachDB control panel, start by clicking the Create Cluster button to provision a cluster and access the database creation page:

  1. Choose Serverless as the plan type. This creates a managed CockroachDB cluster.
  2. Select the Cloud provider for your CockroachDB between AWS or GCP. For this guide, we use AWS.
  3. Pick the Region to run the database in. Here, we selected Frankfurt as our compute will be deployed in this region on Koyeb.
  4. Give your cluster a name, e.g. cockroachdb-koyeb.

When you are done configuring your database, click the Create your free cluster button. Your cluster will be provisioned.

Retrieve your CockroachDB connection string

On your CockroachDB cluster page, click on the Connection tab to create a new user and password. Save that information in a safe place. Under General connection string you will find the connection string you can use to connect to your cluster. The connection string should be similar to the following:

postgres://<USER>:<PASSWORD>@<HOST>:<PORT>/defaultdb?sslmode=verify-full

Save it in a safe place. We will need it in the next step to connect our application to the database.

Deploy the application to Koyeb

You can deploy on Koyeb using the control panel or via the Koyeb CLI.

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

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Set github.com/koyeb/example-express-prisma as the GitHub repository to deploy.
  4. Expand the Builder section. Click the override toggle associated with the Build command and enter npm run cockroachdb:init in the field.
  5. Expand the Environment variables section. Add a DATABASE_URL environment variable to tell the application how to connect to the CockroachDB. Give the environment variable the name DATABASE_URL and enter the connection string from earlier as the value.
  6. Name your App and Service, for instance, express-cockroachdb.
  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 .koyeb.app.

The example application exposes a /planets endpoint that you can use to list planets from the database. Once your deployment is live, you should see the following results when navigating to https://<YOUR_APP_URL>.koyeb.app/planets:

[
  {
    "id": "827696777012871169",
    "name": "Mercury"
  },
  {
    "id": "827696777225666561",
    "name": "Venus"
  },
  {
    "id": "827696777389539329",
    "name": "Mars"
  }
]

Delete the example application and Cockroach database

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

AivenCrunchy Bridge