Skip to main content
Version: Next

Quick Start Guide

In this guide you'll learn how to create and run your first API with Platformatic DB. Let's get started!

info

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:

Create a new API project

Automatic CLI

Run this command in your terminal to start the Platformatic creator wizard:

npm 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:

- What kind of project do you want to create?   => Application
- Where would you like to create your project? => quick-start
- Which kind of project do you want to create? => DB
- What is the name of the service? => (generated-randomly), e.g. legal-soup
- What is the connection string? => sqlite://./db.sqlite
- Do you want to create default migrations? => Yes
- Do you want to create another service? => No
- Do you want to use TypeScript? => No
- What port do you want to use? => 3042
- Do you want to init the git repository? => No

Once the wizard is complete, you'll have a Platformatic app project in the folder quick-start, with example migration files, plugin script, routes, and tests inside your service directory under services/

info

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 service directory - inside services/ folder under the 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.

migrations/001.do.sql
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 service directory (under the services/ folder in the project directory), check the Platformatic configuration file named platformatic.json The environment file named .env in your project directory(quick-start), provides the values for environment variable placeholders.

This generated configuration tells Platformatic to:

  • Run an API server on http://0.0.0.0:3042/
  • Connect to an SQLite database stored in a file named db.sqlite
  • Look for database migration files in the migrations directory
  • Auto-apply the migrations
  • Load the plugin file named plugin.js and automatically generate types
tip

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 init --yes

npm install platformatic

Add a database schema

In your project directory (quick-start), create a file for your sqlite 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:

migrations/001.do.sql
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.

tip

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:

platformatic.db.json
{
"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
tip

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"}]
tip

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
}
}
tip

Learn more about your API's GraphQL interface in the GraphQL API reference.