Configuration

Platformatic DB can be configured with a configuration file in the different file formats below. The DB also support the use of environment variables as setting values with environment variable placeholders.

Configuration Files

The Platformatic CLI will automatically detect and load configuration files found in the current working directory with the file names listed here.

Alternatively, a --config option specify a configuration file path for most platformatic db CLI commands. The configuration examples in this reference use the JSON format.

Supported File Formats

For detailed information on supported file formats and extensions, please visit our Supported File Formats and Extensions page.

Configuration Settings

Configuration file settings are grouped as follows:

• basePath (required): Configures the basePath.
• server (required): Configures the server settings
• composer: Specific settings for Platformatic Composer, such as service management and API composition.
• metrics: Monitors and records performance metrics.
• plugins: Manages additional functionality through plugins.
• telemetry: Handles telemetry data reporting.
• watch: Observes file changes for dynamic updates.
• clients: Configures client-specific settings.

Sensitive data within these settings should use configuration placeholders to ensure security.

db

A required object with the following settings:

• connectionString (required, string) — Specifies the URL for database connection.

Example

postgres://user:password@my-database:5432/db-name

• schema (array of string) - Defines the database schemas, only supported for PostgreSQL. Defaults to 'public' if unspecified.

Example Object

  "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 GraphQL API interface.

  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.

  Enables OpenAPI

  Example Object

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

  Enables OpenAPI using the enabled option

  Example Object

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

  Enables OpenAPI with prefix

  Example Object

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

  Enables OpenAPI with options

  Example Object

  {
    "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. We're adding a Bearer token in the form of a JWT in the code block below:

  Example Object

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

  You can selectively ignore entities:

  Example Object

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

  Selectively ignore fields:

  Example Object

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

  You can explicitly identify tables to build an entity, however all other tables will be ignored:

  Example Object

  {
    "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.

  Example Object

  {
    "db": {
      ...
      "limit": {
        "default": 10,
        "max": 1000
      }
    }
  }

• ignore (object) — Key/value object that defines which database tables should not be mapped as API entities.

  Example Object

  {
    "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.

  Example Object

  {
    "db": {
      ...
      "include": {
        "version": true
      }
    }
  }

• events (boolean or object, default: true) — Controls the support for events published by the SQL mapping layer.

  • enabled: Set to true to activate event publishing, which support for GraphQL Subscription over WebSocket using an in-process message broker.
  • Custom Broker: To use an external message broker, such as Valkey, provide the connection string as shown in the example below.
  Example Object

  {
    "db": {
      ...
      "events": {
        ...
        "enabled": true,
         "connectionString": "valkey://:[email protected]:6380/"
      }
    }
  }

• schemalock (boolean or object, default: false) — Controls the caching of the database schema on disk. Enabling this feature (true) saves the database schema metadata in a schema.lock file, ensuring faster startup times and consistent schema enforcement across sessions. You can also customize the storage location of the schema.lock file by providing a specific file path:

  Example Object

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

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

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.
• table (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.

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
• rolePath (string): The name of the dot-separated path 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 or object): 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 or object): 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.

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": [
       ...
    ]
  }
}

Setting and Using ENV placeholders

Environment variable placeholders are used to securely inject runtime configurations. Learn how to set and use environment variable placeholders documentation.

PLT_ROOT

The PLT_ROOT variable is used to configure relative path and is set to the directory containing the Service configuration file.

Sample Configuration

The example below is a basic setup for Platformatic DB using a local SQLite database. It includes support for OpenAPI, GraphQL, and the GraphiQL interface.

The server is configured to listen on 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
  }
}

Issues

If you run into a bug or have a suggestion for improvement, please raise an issue on GitHub or join our Discord feedback channel.