Announcing US-East 🇺🇸 region: Deploy your apps in Washington, DC

CockroachDB and Koyeb

Integrate a managed CockroachDB serverless database to your application and benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network with zero configuration.

CockroachDB is a cloud-native distributed SQL database built for speed, durability, and scale. It scales horizontally; survives disk and datacenter 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

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 into your CockroachDB account.

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 for us
  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 on Koyeb

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

Via the Koyeb control panel

To deploy the example application using the control panel, follow these steps:

  1. Create a new Koyeb App.
  2. Setgithub.com/koyeb/example-express-prisma as the GitHub repository to deploy and keep the default branch main
  3. Set npm run cockroachdb:init as the Build command
  4. Add a DATABASE_URL environment variable to indicate the application how to connect to the CockroachDB. Give the environment variable a name, DATABASE_URL and enter the connection string from earlier as the value
  5. Name your service, for instance, express-cockroachdb
  6. Click the Create service button

Koyeb is now building the application. 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"
  }
]

Via the Koyeb CLI

To deploy the example application using the Koyeb CLI, run the following command in your terminal:

koyeb app init express-cockroachdb \
--git github.com/koyeb/example-express-prisma \
--git-build-command "npm run cockroachdb:init" \
--git-branch main \
--ports 8080:http \
--routes /:8080 \
--env PORT=8080 \
--env DATABASE_URL="postgresql://<user>:<password>@<host>:<port>/defaultdb?sslmode=verify-full"

Make sure to replace user, password, host, and port with your own.

Access deployment logs

To track the app deployment and visualize build logs, execute the following command:

koyeb service logs express-cockroachdb/express-cockroachdb -t build

Access your app

Once the deployment of your application has finished, you can retrieve the public domain to access your application by running the following command:

$ koyeb app get express-cockroach
ID      	NAME                  	STATUS  	DOMAINS                                      	CREATED AT
b60982b7	express-cockroachdb   	STARTING	["express-cockroachdb-ed.koyeb.app"]	        01 Dec 22 15:06 UTC

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:

  • From the CockroachDB dashboard, go to the Actions tab and click Delete cluster. Follow the instructions
  • From the Koyeb control panel, select the App to delete. Under the Settings tab, click the Delete button and follow the instructions
← Crunchy Bridge PostgresPlanetScale MySQL →