Configuration
Platformatic DB is configured with a configuration file. It supports the use of environment variables as setting values with configuration 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
orplatformatic.db.yaml
platformatic.db.tml
orplatformatic.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
Format | Extensions |
---|---|
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:
server
(required)db
(required)metrics
migrations
plugins
authorization
telemetry
watch
clients
Sensitive configuration settings, such as a database connection URL that contains a password, should be set using configuration 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
- Example:
schema
(array ofstring
) - Currently supported only for postgres, schemas used tolook for entities. If not provided, the defaultpublic
schema is used.Examples
"db": {
"connectionString": "(...)",
"schema": [
"schema1", "schema2"
],
...
},
Platformatic DB supports MySQL, MariaDB, PostgreSQL and SQLite.
graphql
(boolean
orobject
, default:true
) — Controls the GraphQL API interface, with optional GraphiQL UI.Examples
Enables GraphQL support
{
"db": {
...
"graphql": true
}
}Enables GraphQL support with GraphiQL
{
"db": {
...
"graphql": {
"graphiql": true
}
}
}It's possible to selectively ignore entites:
{
"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
orobject
, 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 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 entites:
{
"db": {
...
"openapi": {
"ignore": {
"categories": true
}
}
}
}It's possible to selectively ignore fields:
{
"db": {
...
"openapi": {
"ignore": {
"categories": {
"name": true
}
}
}
}
}- If value is an object, all OpenAPI v3 allowed properties can be passed. Also a
autoTimestamp
(boolean
orobject
) - Generate timestamp automatically when inserting/updating records.poolSize
(number
, default:10
) — Maximum number of connections in the connection pool.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
}
}
}events
(boolean
orobject
, 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
{
"db": {
...
"events": {
"connectionString": "redis://:password@redishost.com:6380/"
}
}
}schemalock
(boolean
orobject
, default:false
) — Controls the caching of the database schema on disk. If set totrue
the database schema metadata is stored inside aschema.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.
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 anx-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.secret
(required,string
orobject
): The secret key that the JWT was signed with. See the@fastify/jwt
documentation for accepted string and object values. Use an environment variable placeholder to securely provide the value for this setting.jwks
(boolean
orobject
): Configure authorization with JSON Web Key Sets (JWKS). See the JWKS documentation.namespace
(string
): Configure a JWT Custom Claim Namespace to avoid name collisions.
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.
If an authorization
object is present, but no rules are specified, no CRUD
operations are allowed unless adminSecret
is passed.
Example
{
"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.
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
}
}