June 10, 2021
Édouard Bonlieu
@edouardb_
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:
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.
To successfully follow and complete this tutorial, you need:
To successfully follow this guide, you need to follow these steps:
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.
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.io/planetscale/pscale-proxy
["--host","0.0.0.0"]
to be able to connect to the proxy from another Koyeb Service instead of just locallyIn 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 organizationGive 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.
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
: 3306user
: rootdatabase
: your PlanetScale database nameWe recommend to use environment variables to store and pass the connection parameters to your application.
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!
Koyeb is a developer-friendly serverless platform to deploy any apps globally.
Start for freeDeploy 2 services for free and enjoy our predictable pricing as you grow
Get up and running in 5 minutes