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.

Requirements

Platformatic supports macOS, Linux and Windows (WSL recommended).

To follow along with this guide you'll need to have these things installed:

• Node.js v16 or v18 (latest of the series)
• npm v7 or later
• A code editor, for example Visual Studio Code
• Python and a compiler toolchain is recommended to experience the hot-reloading capabilities; Check the requirements for Unix, macOS or Windows)

In case the compiler toolchain is missing, there is a fallback that supports only commonjs modules. ESM support is available only via the native addon.

Create a new API project

Create a directory for your new API project:

mkdir quick-start

cd quick-start

Then create a package.json file with the npm default values:

npm init --yes

And install the platformatic CLI as a project dependency:

npm install platformatic

Add a database schema

In your project directory (quick-start), create a migrations directory to store your database migration files:

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 pages (
  id INTEGER PRIMARY KEY,
  title VARCHAR(255) NOT NULL
);

When it's run by Platformatic, this query will create a new database table named pages.

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 db.json.

Copy and paste in this configuration:

{
  "server": {
    "logger": {
      "level": "info"
    },
    "hostname": "127.0.0.1",
    "port": "3042"
  },
  "core": {
    "connectionString": "sqlite://pages.db",
    "graphiql": true
  },
  "migrations": {
    "dir": "./migrations"
  }
}

This configuration tells Platformatic to:

• Run an API server on http://127.0.0.1:3042/
• Configure the API server to log messages with an info level or above
• Connect to an SQLite database stored in a file named pages.db
• Enable the GraphiQL web UI
• Look for database migration files 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:

1. Run your SQL migration file and create a pages table in the SQLite database.
2. Automatically map your SQL database to REST and GraphQL API interfaces.
3. Start the Platformatic API server.

Your Platformatic API is now up and running!

tip

You can display human-readable logs in development by using pino-pretty:

npm install --save-dev pino-pretty

npx platformatic db start | npx pino-pretty

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 page

curl -X POST -H "Content-Type: application/json" \
  -d "{ \"title\": \"Hello Platformatic DB\" }" \
    http://localhost:3042/pages

You should receive a response from your API like this:

{"id":1,"title":"Hello Platformatic DB"}

Get all pages

curl http://localhost:3042/pages

You should receive a response from your API like this, with an array containing all the pages in your database:

[{"id":1,"title":"Hello Platformatic DB"}]

tip

Take a look at the REST API reference for a complete overview of the REST interface that your API provides.

OpenAPI documentation

You can explore the OpenAPI documentation for your REST API 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 pages from your API:

{
  pages {
    id
    title
  }
}

tip

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