How to connect your apps to a PlanetScale database on Koyeb
5 minPlanetScale 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:
- Create a PlanetScale database and service token
- Deploy the PlanetScale proxy on Koyeb
- 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.
To connect the PlanetScale database, we will use a service token to authenticate. To create a new service token, in the terminal run:
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.
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, on the Overview tab, click Create Web Service to begin:
- Choose Docker as the deployment method.
- In the Docker image field, enter
docker.io/planetscale/pscale-proxy
. - In the Deployment section, click the Override toggle associated with Command args and enter
["--host","0.0.0.0"]
in the field. - In the Environment variables section, click Bulk edit and add the following 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 branchmain
.PLANETSCALE_ORG
: with the name of your PlanetScale organization.
- In the Exposed ports section, change the export port to
3306
. - Choose a name for your App and Service, for example
planetscale-demo
, and click Deploy.
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
: 3306user
: rootdatabase
: 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!