Deploy a Rest API using Koa, Prisma, and Aiven on Koyeb
22 minIntroduction
In this tutorial, we will showcase how to build a Notes REST API using Koajs, Prisma, and Aiven on Koyeb. By running your application on Koyeb, you natively benefit from continuous deployment using git, autoscaling, autohealing, TLS encryption, a global edge network CDN, and more.
Koa is a minimalist, expressive and robust web framework for web applications and APIs. We will use Koa to build our application REST API.
Aiven is a fully-managed, multi-cloud data platform allowing you to deploy a wide range way of open-source data services and databases such as MySQL, PostgreSQL, InfluxDB, Redis, and more. We will use Aiven to provision a MySQL database and use it to store our Notes information.
Last, we will make use of Prisma, an ORM offering powerful primitive that will help us interact with the MySQL database from our application intuitively and safely.
At the end of this guide, you will have a working Notes application deployed on Koyeb using git-driven deployment.
Requirements
To successfully follow and complete this guide, you need:
- A local development environment with Node.js installed
- A Koyeb account to deploy and run the application
- An Aiven account to run the MySQL database
- A GitHub account to version and deploy your application code on Koyeb
Steps
To deploy the Rest API using Koa, Prisma, and Aiven on Koyeb, you need to follow these three steps:
- Deploy a MySQL database on Aiven
- Create the Notes REST API using Koa and Prisma
- Deploy the Notes application to Koyeb
Deploy a MySQL database on Aiven
Aiven is a fully-managed, multi-cloud data platform allowing you to deploy a wide range of open-source databases including MySQL, PostgreSQL, InfluxDB, Redis, and many more. In this guide, we will deploy a MySQL database on Aiven and use it as the data backend for our application.
Aiven provides a 1-month free trial with $300 credits to try out the platform.
On the Aiven control panel, click the Create a new service button on the top right corner. You land on the Create Service page where you need to select the service type to deploy. Select the MySQL service.
Then, select Google Cloud as the cloud service provider to run the MySQL database.
Select the Hobbyist plan which is perfect for small test environments and is ideal to follow this guide.
Last, click the Create Service button to provision the MySQL database. You land on the Aiven Services page where you can see the newly created service.
Click the MySQL service to go to the service details page and retrieve the MySQL database credentials.
Take note of the Service URI in a secure place, that’s what we will use to connect to our database in our application. Embedded in the URI are the MySQL user, password, host, and port as well as a default database name, so don't share it publicly!
Tip: If you’re more of a command line person, you can make use of the Aiven CLI as well.
Connect to the database
Before we go further, let's ensure we can properly connect to the MySQL database we just deployed to ensure everything is working as expected. In the terminal, run the following command to connect to the database:
Don't forget to replace AIVEN_DB_USER
, AIVEN_DB_PASSWORD
, AIVEN_DB_HOST
, and AIVEN_DB_PORT
with your own information.
Once the command is executed, if everything goes well, you should see the following output:
Create the Notes REST API using Koa and Prisma
Create the Koa application
First, we will create a new Koa application and install the necessary packages required by our application. To start, create a new directory for our application code and change to the newly created directory using the command below:
Next, initialize a new Node project using the command below:
This command creates a package.json
file inside the koa-prisma-notes-api
directory containing basic information such as the project name, version, and author.
We can then install the dependencies required by our API using the npm
command:
This command installs Koa, koa-router
a router for Koa which we will use to define the API endpoints, and koa-body
a body-parser middleware to parse the request body as JSON.
With those dependencies installed, create a new src
containing an index.js
file:
Open and add the following code to the index.js
file using your preferred editor:
In the code above, we:
-
import the dependencies required by our application
,
-
create a new instance of Koa to which everything will be tied to,
-
add the Koa router and Koa body middlewares to the Koa application,
-
launch the Koa server on port
8080
.
You can then start the server by running in your terminal:
This works fine but for a better development experience, we would like the server to restart automatically whenever we make changes. For that, we will make use of Nodemon which will automatically restart the application when file changes are detected in the directory.
To install nodemon
in your terminal, run the following command:
Then we can start the server by running:
Next, add the following scripts to your package.json
to ease the launch of the application for development and production as below:
Install Prisma
Prisma is a next-generation ORM for Node.js and TypeScript. It supports multiple databases such as PostgreSQL, MySQL, SQL Server, SQLite, and MongoDB. We will use Prisma to manage our schemas and query the database from our application.
Start by adding Prisma to your project using the following command:
Then initialize a fresh Prisma project by running:
This will create a new prisma
directory that contains a schema.prisma
file and a .env
and file in the project root.
The schema.prisma
file contains things like the Prisma client generator, the database connection, and the Prisma schema which will be used to define the database schema.
The .env
file contains the environment variables that will be put into the system environments. Prisma will then read and use these variables.
Edit the .env
file by replacing the DATABASE_URL
value with your Aiven database connection string.
The Prisma schema file contains the configuration of the Prisma setup:
Create a Prisma schema for the notes API
Our application will just have one model called Note
. To create the data model definition in the prisma/schema.prisma
file add the following:
Each field definition is composed of the following parts:
- The field name
- The field type
- Type modifiers (optional)
- Attributes, including native database type attributes (optional)
Our Note
model has a couple of fields:
id
: of typeInt
marked as the primary key using the@id
modifier and set to a default value which will be auto-incrementedtitle
: of typeString
and using the native database typevarchar
with a length of 255.content
: of typeString
but marked as optional by using?
and of native database typetext
createdAt
: of typeDateTime
with a default value set to the current time when a note is createdupdatedAt
: of typeDateTime
with a default value set to the time when the note is updated
Create your first Prisma migration
With the note model defined, we can now perform a Prisma migration to synchronize our database schema with our Prisma schema. To do so, run the following command in your terminal:
Once the migration is completed, your prisma
directory structure should now look as below:
While it’s totally fine to use migrate dev
to run migrations in a development environment, in production, or in your CI/CD pipeline, we need to make sure we apply any pending migrations and create the database if it does not exist using prisma migrate deploy
before running the application.
To make doing that straightforward, let’s add a build
script in the package.json
file:
Create seeds data
We are now ready to seed our database with some mock data using Prisma. Into the prisma
directory, create a new seed.js
file containing the following code:
The script uses the Prisma client to insert data into the database. You may notice that we are using the createMany()
function to insert multiple data at once.
Next, add a prisma
section in our package.json
file to be able to run the script using the Prisma CLI:
Then to seed the database, execute:
Building the Notes Koa API
With all the setup out of the way, let’s start building the API’s functionality. As mentioned earlier, the note API is going to contain basic CRUD operations. As seen briefly in the seed section above, we will be making use of the Prisma client to interact with our database and perform the necessary CRUD operation.
Add the code below inside the index.js
file containing our Koa application:
The code above adds the following routes to our Note application:
GET /notes
: retrieves all notes and uses the Prisma clientfindMany()
function to retrieve the notes.GET /notes/:id
: retrieves a single note from its ID and uses the PrismafindUnique()
function to retrieve the note. If the note is found the API responds with an HTTP code200
and404
otherwise.POST /notes
: creates a new note. It uses the Prismacreate()
function to create the note and returns a201
HTTP code when the note is created.PUT /notes/:id
: updates an existing note from its ID. It uses the Prismaupdate()
function to update the note and returns a200
HTTP code when the note is updated.DELETE /notes/:id
: deletes a note from its ID. This endpoint uses the Prismadelete()
function to delete the note and returns a204
HTTP code when the note is deleted.
Run the Notes API application
It's time to test out the API to ensure everything is working as expected.
First, launch the server by running:
The server will start and be accessible at http://localhost:8080
.
Then, let's play with the API using curl
to test the different endpoints:
Update the Prisma schema (optional)
Our application is now feature complete. But before we wrap up, let’s make a small refactor by adding status to notes. That way, we can have notes that are in draft and those published.
Let’s start by updating the Prisma schema. Since we want to have predetermined status (draft
and published
), we are going to create an enum and add a new field called status
set to the type of the Status
enum with a default value of draft
to the Note model.
Next, we need to create a new migration to synchronize our database schema with the Prisma schema by running:
When prompted for a name for the new migration, we’ll enter “add status”.
Once the migration is completed, the migrations
directory should look like below:
Last, update the application to use the freshly created status
field by editing the Koa application index.js
file:
We can now filter the notes based on their status when we call the /notes
endpoint and can also update the status of a note.
For instance to list all notes with the draft
status run:
Deploy the Notes application on Koyeb
We are now ready to deploy our note API on Koyeb.
Koyeb is a developer-friendly serverless platform to deploy apps globally. It supports deploying applications using pre-built Docker containers or native code using git. For the purpose of this tutorial, we will deploy our application using git-driven deployment.
Head over to GitHub to create a new repository and push the application code running:
On the Overview tab of the Koyeb control panel, click Create Web Service to begin:
- Select GitHub as the deployment method.
- In the repositories list, select the repository containing your Koa application.
- In the Environment variables section, click Add variable to create a
DATABASE_URL
variable set to your Aiven connection string in the form of:mysql://AIVEN_DB_USER:AIVEN_DB_PASSWORD@AIVEN_DB_HOST:AIVEN_PORT/AIVEN_DB_DATABASE_NAME?ssl-mode=REQUIRED
. - Choose a name for your App and Service, for example
koa-prisma-notes-api-on-koyeb
, and click Deploy.
There is no need to set the build and run commands, by default Koyeb detects if a build
and start
scripts are present in your package.json
file and execute them automatically.
The build
script will be run during the build stage and the start
script to launch the application once the build succeeded.
You land on the deployment page where you can follow the progress of your application's deployment. Once the build and deployment are completed, you can access your application by clicking the App URL ending with koyeb.app
in the Koyeb control panel.
Conclusion
That's it! In this tutorial, we looked at how to build a REST API with Koa, Prisma, and Aiven. We created a MySQL database using Aiven, created a new Koa application, and used Prisma to interact with our MySQL database from our application. Along the line, we covered how to run migration and seed our database with data using Prisma.
Finally, we deployed the application on Koyeb using git-driven deployment: all the changes you push to your repository will automatically trigger a new build and deployment on the Koyeb Serverless Platform. With the Koyeb continuous deployment feature, your changes will go live as soon as the deployment passes all necessary health checks. In case of a failure during deployment, the platform maintains the latest working deployment in production to ensure your application is always up and running.
You can access the complete application code on GitHub.