How to connect your apps to a PlanetScale database on Koyeb

PlanetScale is a serverless database platform built on top of MySQL and Vitess. The platform provides developers great primitives simplifying the management and scaling of databases.

Following is a non-exhaustive list of the built-in features PlanetScale offers:

• Native autoscaling: to automatically scale underlying resources depending of the load
• Database branching: to create database copies with a click and apply schema changes to a branch
• Non-blocking schema changes: to update your database tables without locking and downtime

In this guide, we will explain how to use and connect your apps to your PlanetScale databases on the Koyeb serverless platform.

We will deploy the official PlanetScale planetscale/pscale-proxy Docker image inside a Koyeb App which avoids dealing with IP whitelisting or SSL certificates by proxifying connection to your PlanetScale databases. We will also take advantage of the Koyeb service mesh and discovery, built-in features which provide an isolated, secure private network allowing your apps to communicate with your PlanetScale database securely.

Requirements

To successfully follow and complete this tutorial, you need:

• A PlanetScale account and the PlaneScale CLI installed on your machine
• A Koyeb account to deploy and run

Steps

To successfully follow this guide, you need to follow these steps:

1. Create a PlanetScale database and service token
2. Deploy the PlanetScale proxy on Koyeb
3. Connect your database via the Koyeb mesh

Create a PlanetScale database

To get started, let's start by creating a database using the PlanetScale CLI. In the terminal, execute the following command replacing the <dbname> with the database name you want to use.

pscale database create <dbname>

To connect the PlanetScale database, we will use a service token to authenticate. To create a new service token, in the terminal run:

$pscale service-token create
NAME           TOKEN
-------------- ------------------------------------------
asd9eeectsti   f0d0d1426bf30957f8526d52208a07c08f000000

Save the token in a safe place, you will need it in the next section when deploying the PlaneScale Proxy on Koyeb.

To be able to properly authenticate to our database, we need to grant permissions on the service token we previously created. In the terminal execute the following replacing the <dbname> with your database name and <tokenname> with your service token name.

pscale service-token add-access <tokenname> connect_production_branch connect_branch --database <dbname>

By running this command, we grant the service token access to connect the production branch and all other branches. To learn more about service token permissions, please refer to the PlanetScale documentation.

Deploy the PlanetScale Proxy on Koyeb

PlanetScale provides a proxy to securely connect to your database without having to deal with IP whitelisting or SSL certificates manually. We will deploy the PlanetScale proxy in a Koyeb Service to easily connect to the associated databases.

On the Koyeb Control Panel, click the Create App button.

In the Docker image section:

• Docker image: use the PlanetScale Proxy Docker image hosted on the Docker registry docker.io/planetscale/pscale-proxy
• Args: Enter ["--host","0.0.0.0"] to be able to connect to the proxy from another Koyeb Service instead of just locally

In the Ports section, change the export port from 80 to 3306 and from protocol HTTP to TCP. This setting is required to let Koyeb performs health checks and ensure your service is up and running properly.

In the Environment variables section, create the following environment variables:

• PLANETSCALE_SERVICE_TOKEN: with the PlanetScale service token you created in the previous section. We strongly recommend using a Secret environment variable to store it.
• PLANETSCALE_SERVICE_TOKEN_NAME: with the PlanetScale service token name you created in the previous section. We strongly recommend using an environment variable of type Secret to store it.
• PLANETSCALE_DATABASE: with the name of your PlanetScale database.
• PLANETSCALE_BRANCH: with the name of the PlanetScale database branch to use, here I set the value to the default production branch main.
• PLANETSCALE_ORG: with the name of your PlanetScale organization

Give your App a name, i.e planetscale-demo, and click Create App

This will create the Koyeb App with the PlanetScale proxy Service running it.

Now all Services you deployed inside this application will be able to securely connect the database using the Koyeb service mesh and discovery.

Connect your database via the Koyeb mesh

To connect the PlaneScale database using the Koyeb mesh, provide your application the following mysql configuration:

• host: The name of the Koyeb service running the PlanetScale, i.e. pscale-proxy
• port: 3306
• user: root
• database: your PlanetScale database name

We recommend to use environment variables to store and pass the connection parameters to your application.

Conclusion

In this guide, we have seen how to configure, deploy and connect a PlaneScale database using the PlaneScale Proxy and how to connect your application to the database using the Koyeb mesh network. The Service Mesh & Discovery features offer a simple and secure way to communicate between your services and your database.

Questions or suggestions to improve this guide? Join us on the community platform to chat!