Stravia Docs

Databases

Server setup supports SQLite in the Server data directory or PostgreSQL for configuration and history. Choose the backend before creating the administrator; a configured but unreachable database prevents normal Server startup rather than silently falling back to SQLite.

Prerequisites

Use the Server's first-run setup before creating the sole administrator. If you choose PostgreSQL, provision its database, network access, and credentials first; SQLite is stored under the selected Server data root.

Choose a backend

  • SQLite uses the Server data root at <data-dir>/db/gateway.db. Its location is managed by Stravia; do not assume an arbitrary SQLite file path is supported.
  • PostgreSQL uses a connection URL in the Server configuration and optional pool settings. Provision the database and credentials before entering them in setup; Stravia's migration work is not a substitute for creating the database service or account.

Configure during Server setup

  1. Open the Server /setup page and claim the current process's one-time token.
  2. Select SQLite or PostgreSQL.
  3. For PostgreSQL, enter the URL and any required connection-pool values.
  4. Choose Test connection and wait for success before creating the Server administrator.

The database connection is persisted in server.toml, by default under the data directory. If the file specifies PostgreSQL and that connection later fails, Stravia does not silently switch to an empty SQLite database.

Verify and protect the backend

After setup, confirm Server can restart with the same data directory and configured database. Restrict access to the database credentials and include the database in the backup plan. PostgreSQL does not contain local files such as artifacts and imported plugins; plan those separately.

If the database cannot be opened

Check the server.toml database backend, URL, credentials, connectivity, and database availability. Older data layouts or incompatible schemas require the supported migration procedure; do not delete the existing database to make the Server start.

Next steps

For local and S3 artifact storage see Storage . For recovery scope see Backup and restore .