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 to 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 demonstrate how to connect the PlaneScale using the Koyeb mesh, we will deploy the Ghost blogging platform using our database.

In the Koyeb Control Panel, go to your App and click Create Service

In the Docker image, use the Ghost official Docker image docker.io/ghost.

In the Ports section, change the port from 80 to 2368, which is the default port Ghost is listening on. This setting is required to let Koyeb know which port the Service is listening to and properly route incoming HTTP requests. We don't need to change the Path, Ghost will be available at the root of our domain: /.

In the Environment variables section, create the following environment variables which will be used by Ghost to connect the database:

• database__client: with the value mysql
• database__connection__host: with the name of the service running the PlaneScale proxy, in our case pscale-proxy
• database__connection__user: with the value root
• database__connection__database: with the name of your PlanetScale database.

Give your Service a name, i.e ghost-demo, and click Create Service

Now if you go to your Koyeb App URL <appname>-<orgname>.koyeb.app, you land on the Ghost landing page which is running and connected to your PlaneScale database using the Koyeb mesh network.

Conclusion

In this guide, we have seen how to configure, deploy and connect a PlaneScale database using the PlaneScale Proxy. We deployed a Koyeb App running two services:

• The PlaneScale Proxy to communicate with our database
• A Ghost Blog to show how to connect your own service 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.

If you have any questions or suggestions regarding this guide,
feel free to reach out on Slack.