How to connect your apps to a PlanetScale database on Koyeb
Tags: serverless, database, tutorial, webdev
Published: 2021-06-10 15:56:23

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](https://docs.planetscale.com/reference/planetscale-environment-setup/) installed on your machine
 - A [Koyeb account](https://app.koyeb.com) to deploy and run

## Steps

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

1. [Create a PlanetScale database and service token](#create-a-planet-scale-database)
3. [Deploy the PlanetScale proxy on Koyeb](#deploy-the-planet-scale-proxy-on-koyeb)
3. [Connect your database via the Koyeb mesh](#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.

```bash
 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:

```bash
$ 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.

```bash
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](https://docs.planetscale.com/reference/planetscale-cli/#service-tokens-in-organizations).

## 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](https://slack.koyeb.com).