Quick Start Guide
In this guide you'll learn how to create and run your first API with Platformatic DB. Let's get started!
This guide uses SQLite for the database, but Platformatic DB also supports PostgreSQL, MySQL and MariaDB databases.
Prerequisites
Platformatic supports macOS, Linux and Windows (WSL recommended).
To follow along with this guide you'll need to have these things installed:
- Node.js >= v18.8.0 or >= v20.6.0
- npm v7 or later
- A code editor, for example Visual Studio Code
Create a new API project
Automatic CLI
Run this command in your terminal to start the Platformatic creator wizard:
- npm
- yarn
- pnpm
npm create platformatic@latest
yarn create platformatic
pnpm create platformatic@latest
This interactive command-line tool will ask you some questions about how you'd like to set up your new Platformatic project. For this guide, select these options:
- Which kind of project do you want to create? => DB
- Where would you like to create your project? => quick-start
- Do you want to create default migrations? => Yes
- Do you want to create a plugin? => Yes
- Do you want to use TypeScript? => No
- Do you want to install dependencies? => Yes (this can take a while)
- Do you want to apply the migrations? => Yes
- Do you want to generate types? => Yes
- Do you want to create the github action to deploy this application to Platformatic Cloud dynamic workspace? => No
- Do you want to create the github action to deploy this application to Platformatic Cloud static workspace? => No
Once the wizard is complete, you'll have a Platformatic app project in the
folder quick-start
, with example migration files and a plugin script.
Make sure you run the npm/yarn/pnpm command install
command manually if you
don't ask the wizard to do it for you.
Start your API server
In your project directory, run this command to start your API server:
npm start
Your Platformatic API is now up and running! 🌟
This command will:
- Automatically map your SQL database to REST and GraphQL API interfaces.
- Start the Platformatic API server.
You can jump down to Next steps or read on to learn more about the project files that the wizard has created for you.
Check the database schema
In your project directory (quick-start
), open the migrations
directory that can store your database migration files that will contain both the 001.do.sql
and 001.undo.sql
files. The 001.do.sql
file contains the SQL statements to create the database objects, while the 001.undo.sql
file contains the SQL statements to drop them.
CREATE TABLE IF NOT EXISTS movies (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL
);
Note that this migration has been already applied by Platformatic creator.
Check your API configuration
In your project directory, check the Platformatic configuration file named
platformatic.db.json
and the environment file named .env
:
The created configuration tells Platformatic to:
- Run an API server on
http://127.0.0.1:3042/
- Connect to an SQLite database stored in a file named
db.sqlite
- Look for database migration files in the
migrations
directory - Load the plugin file named
plugin.js
and automatically generate types
The Configuration reference explains all of the supported configuration options.
Manual setup
Create a directory for your new API project:
mkdir quick-start
cd quick-start
Then create a package.json
file and install the platformatic
CLI as a project dependency:
- npm
- yarn
- pnpm
npm init --yes
npm install platformatic
yarn init --yes
yarn add platformatic
pnpm init
pnpm add platformatic
Add a database schema
In your project directory (quick-start
), create a file for your sqlite3 database and also, a migrations
directory to
store your database migration files:
touch db.sqlite
mkdir migrations
Then create a new migration file named 001.do.sql
in the migrations
directory.
Copy and paste this SQL query into the migration file:
CREATE TABLE movies (
id INTEGER PRIMARY KEY,
title VARCHAR(255) NOT NULL
);
When it's run by Platformatic, this query will create a new database table
named movies
.
You can check syntax for SQL queries on the Database.Guide SQL Reference.
Configure your API
In your project directory, create a new Platformatic configuration file named
platformatic.db.json
.
Copy and paste in this configuration:
{
"server": {
"hostname": "127.0.0.1",
"port": "3042"
},
"db": {
"connectionString": "sqlite://./db.sqlite"
},
"migrations": {
"dir": "./migrations",
"autoApply": "true"
}
}
This configuration tells Platformatic to:
- Run an API server on
http://127.0.0.1:3042/
- Connect to an SQLite database stored in a file named
db.sqlite
- Look for, and apply the database migrations specified in the
migrations
directory
The Configuration reference explains all of the supported configuration options.
Start your API server
In your project directory, use the Platformatic CLI to start your API server:
npx platformatic db start
This will:
- Automatically map your SQL database to REST and GraphQL API interfaces.
- Start the Platformatic API server.
Your Platformatic API is now up and running! 🌟
Next steps
Use the REST API interface
You can use cURL to make requests to the REST interface of your API, for example:
Create a new movie
curl -X POST -H "Content-Type: application/json" \
-d "{ \"title\": \"Hello Platformatic DB\" }" \
http://localhost:3042/movies
You should receive a response from your API like this:
{"id":1,"title":"Hello Platformatic DB"}
Get all movies
curl http://localhost:3042/movies
You should receive a response from your API like this, with an array containing all the movies in your database:
[{"id":1,"title":"Hello Platformatic DB"}]
If you would like to know more about what routes are automatically available, take a look at the REST API reference for an overview of the REST interface that the generated API provides.
Swagger OpenAPI documentation
You can explore the OpenAPI documentation for your REST API in the Swagger UI at http://localhost:3042/documentation
Use the GraphQL API interface
Open http://localhost:3042/graphiql in your web browser to explore the GraphQL interface of your API.
Try out this GraphQL query to retrieve all movies from your API:
query {
movies {
id
title
}
}
Learn more about your API's GraphQL interface in the GraphQL API reference.