Skip to main content
Version: 1.23.0

Configuration

Platformatic DB is configured with a configuration file. It supports the use of environment variables as setting values with environment variable placeholders.

Configuration file

If the Platformatic CLI finds a file in the current working directory matching one of these filenames, it will automatically load it:

  • platformatic.db.json
  • platformatic.db.json5
  • platformatic.db.yml or platformatic.db.yaml
  • platformatic.db.tml or platformatic.db.toml

Alternatively, a --config option with a configuration filepath can be passed to most platformatic db CLI commands.

The configuration examples in this reference use JSON.

Supported formats

FormatExtensions
JSON.json
JSON5.json5
YAML.yml, .yaml
TOML.tml

Comments are supported by the JSON5, YAML and TOML file formats.

Settings

Configuration settings are organised into the following groups:

Sensitive configuration settings, such as a database connection URL that contains a password, should be set using environment variable placeholders.

server

See Platformatic Service server for more details.

db

A required object with the following settings:

  • connectionString (required, string) — Database connection URL.

    • Example: postgres://user:password@my-database:5432/db-name
  • ** schema** (array of string) - Currently supported only for postgres, schemas used to look for entities. If not provided, the default public schema is used.

Examples

  "db": {
"connectionString": "(...)",
"schema": [
"schema1", "schema2"
],
...

},

  • Platformatic DB supports MySQL, MariaDB, PostgreSQL and SQLite.

  • graphql (boolean or object, default: true) — Controls the GraphQL API interface, with optional GraphiQL UI.

    Examples

    Enables GraphQL support

    {
    "db": {
    ...
    "graphql": true
    }
    }

    Enables GraphQL support with the enabled option

    {
    "db": {
    ...
    "graphql": {
    ...
    "enabled": true
    }
    }
    }

    Enables GraphQL support with GraphiQL

    {
    "db": {
    ...
    "graphql": {
    "graphiql": true
    }
    }
    }

    It's possible to selectively ignore entities:

    {
    "db": {
    ...
    "graphql": {
    "ignore": {
    "categories": true
    }
    }
    }
    }

    It's possible to selectively ignore fields:

    {
    "db": {
    ...
    "graphql": {
    "ignore": {
    "categories": {
    "name": true
    }
    }
    }
    }
    }

    It's possible to add a custom GraphQL schema during the startup:

    {
    "db": {
    ...
    "graphql": {
    "schemaPath": "path/to/schema.graphql"
    }
    }
    }
    }
  • openapi (boolean or object, default: true) — Enables OpenAPI REST support.

    • If value is an object, all OpenAPI v3 allowed properties can be passed. Also a prefix property can be passed to set the OpenAPI prefix.
    • Platformatic DB uses @fastify/swagger under the hood to manage this configuration.

    Examples

    Enables OpenAPI

    {
    "db": {
    ...
    "openapi": true
    }
    }

    Enables OpenAPI using the enabled option

    {
    "db": {
    ...
    "openapi": {
    ...
    "enabled": true
    }
    }
    }

    Enables OpenAPI with prefix

    {
    "db": {
    ...
    "openapi": {
    "prefix": "/api"
    }
    }
    }

    Enables OpenAPI with options

    {
    "db": {
    ...
    "openapi": {
    "info": {
    "title": "Platformatic DB",
    "description": "Exposing a SQL database as REST"
    }
    }
    }
    }

    You can for example add the security section, so that Swagger will allow you to add the authentication header to your requests. In the following code snippet, we're adding a Bearer token in the form of a JWT:

    {
    "db": {
    ...
    "openapi": {
    ...
    "security": [{ "bearerAuth": [] }],
    "components": {
    "securitySchemes": {
    "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
    }
    }
    }
    }
    }
    }

    It's possible to selectively ignore entities:

    {
    "db": {
    ...
    "openapi": {
    "ignore": {
    "categories": true
    }
    }
    }
    }

    It's possible to selectively ignore fields:

    {
    "db": {
    ...
    "openapi": {
    "ignore": {
    "categories": {
    "name": true
    }
    }
    }
    }
    }

    It's possible to explicitly identify tables for which you like to build an entity: Note: all other tables will be ignored.

    {
    "db": {
    ...
    "openapi": {
    "include": {
    "categories": true
    }
    }
    }
    }
  • autoTimestamp (boolean or object) - Generate timestamp automatically when inserting/updating records.

  • allowPrimaryKeysInInput (boolean) - Allow the user to set the primary keys when creating new entities.

  • poolSize (number, default: 10) — Maximum number of connections in the connection pool.

  • idleTimeoutMilliseconds (number, default: 30000) - Max milliseconds a client can go unused before it is removed from the pool and destroyed.

  • queueTimeoutMilliseconds (number, default: 60000) - Number of milliseconds to wait for a connection from the connection pool before throwing a timeout error.

  • acquireLockTimeoutMilliseconds (number, default: 60000) - Number of milliseconds to wait for a lock on a connection/transaction.

  • limit (object) - Set the default and max limit for pagination. Default is 10, max is 1000.

    Examples

    {
    "db": {
    ...
    "limit": {
    "default": 10,
    "max": 1000
    }
    }
    }
  • ignore (object) — Key/value object that defines which database tables should not be mapped as API entities.

    Examples

    {
    "db": {
    ...
    "ignore": {
    "versions": true // "versions" table will be not mapped with GraphQL/REST APIs
    }
    }
    }
  • include (object) — Key/value object that defines which entities should be exposed.

    Examples

    {
    "db": {
    ...
    "include": {
    "version": true
    }
    }
    }
  • events (boolean or object, default: true) — Controls the support for events published by the SQL mapping layer. If enabled, this option add support for GraphQL Subscription over WebSocket. By default it uses an in-process message broker. It's possible to configure it to use Redis instead.

    Examples

    Enable events using the enabled option.

    {
    "db": {
    ...
    "events": {
    ...
    "enabled": true
    }
    }
    }
    {
    "db": {
    ...
    "events": {
    "connectionString": "redis://:password@redishost.com:6380/"
    }
    }
    }
  • schemalock (boolean or object, default: false) — Controls the caching of the database schema on disk. If set to true the database schema metadata is stored inside a schema.lock file. It's also possible to configure the location of that file by specifying a path, like so:

    Examples

    {
    "db": {
    ...
    "schemalock": {
    "path": "./dbmetadata"
    }
    }
    }

    Starting Platformatic DB or running a migration will automatically create the schemalock file.

metrics

See Platformatic Service metrics for more details.

migrations

Configures Postgrator to run migrations against the database.

An optional object with the following settings:

  • dir (required, string): Relative path to the migrations directory.
  • autoApply (boolean, default: false): Automatically apply migrations when Platformatic DB server starts.
  • migrationsTable (string, default: versions): Table created to track schema version
  • validateChecksums (boolean): Validates checksum of existing SQL migration files already run prior to executing migrations. Unused for JS migrations.
  • newline (string): Force line ending on file when generating checksum. Value should be either CRLF (windows) or LF (unix/mac).
  • currentSchema (string): For Postgres and MS SQL Server(will ignore for another DBs). Specifies schema to look to when validating versions table columns. For Postgres, run SET search_path = currentSchema prior to running queries against db.

plugins

See Platformatic Service plugins for more details.

watch

See Platformatic Service watch for more details.

authorization

An optional object with the following settings:

  • adminSecret (string): A secret that should be sent in an x-platformatic-admin-secret HTTP header when performing GraphQL/REST API calls. Use an environment variable placeholder to securely provide the value for this setting.
  • roleKey (string, default: X-PLATFORMATIC-ROLE): The name of the key in user metadata that is used to store the user's roles. See Role configuration.
  • anonymousRole (string, default: anonymous): The name of the anonymous role. See Role configuration.
  • jwt (object): Configuration for the JWT authorization strategy. Any option accepted by @fastify/jwt can be passed in this object.
  • webhook (object): Configuration for the Webhook authorization strategy.
    • url (required, string): Webhook URL that Platformatic DB will make a POST request to.
  • rules (array): Authorization rules that describe the CRUD actions that users are allowed to perform against entities. See Rules documentation.
note

If an authorization object is present, but no rules are specified, no CRUD operations are allowed unless adminSecret is passed.

Example

platformatic.db.json
{
"authorization": {
"jwt": {
"secret": "{PLT_AUTHORIZATION_JWT_SECRET}"
},
"rules": [
...
]
}
}

telemetry

See Platformatic Service telemetry for more details.

watch

See Platformatic Service watch for more details.

clients

See Platformatic Service clients for more details.

Environment variable placeholders

See Environment variable placeholders for more details.

Setting environment variables

See Setting environment variables for more details.

Allowed placeholder names

See Allowed placeholder names for more details.

PLT_ROOT

The {PLT_ROOT} placeholder is automatically set to the directory containing the configuration file, so it can be used to configure relative paths.

Sample Configuration

This is a bare minimum configuration for Platformatic DB. Uses a local ./db.sqlite SQLite database, with OpenAPI and GraphQL support.

Server will listen to http://127.0.0.1:3042

{
"server": {
"hostname": "127.0.0.1",
"port": "3042"
},
"db": {
"connectionString": "sqlite://./db.sqlite",
"graphiql": true,
"openapi": true,
"graphql": true
}
}