Database

Polygent supports three database providers. SQLite is the default and requires zero configuration. Switch providers in appsettings.json and restart the API — schema migrations run automatically on startup.

Provider Selection

The active provider is set under the Database section in appsettings.json:

Database:Provider value	Provider
Sqlite	SQLite (default)
SqlServer	Microsoft SQL Server
PostgreSql	PostgreSQL

The shipped appsettings.json sets Provider to Sqlite. Always keep a valid Provider value (Sqlite, SqlServer, or PostgreSql) — leaving it blank or invalid stops the API from starting.

SQLite (Default)

Single-file database, ideal for trials, single-machine setups, and small teams.

{
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": null
  }
}

When ConnectionString is null the database file is created automatically inside StoragePath (so the resolved path is {StoragePath}/polygent.db). To override, set ConnectionString to a standard SQLite connection string:

{
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": "Data Source=/var/lib/polygent/polygent.db"
  }
}

Note: SQLite connection pooling is disabled internally. You do not need to configure this.

Limits: SQLite serializes writes — avoid for teams with many concurrent ticket pipelines, lots of bot conversations, or high-write automations. Move to PostgreSQL or SQL Server before this becomes a bottleneck.

PostgreSQL

Recommended for team production deployments.

{
  "Database": {
    "Provider": "PostgreSql",
    "ConnectionString": "Host=localhost;Port=5432;Database=polygent;Username=polygent;Password=your_password"
  }
}

Field	Notes
Host / Port	Use a VPC-private host where possible
Database	Create the database before first start; Polygent does not CREATE DATABASE
Username / Password	Grant the role CREATE/SELECT/INSERT/UPDATE/DELETE on the database (schema migrations create tables/indexes)
SSL Mode=Require	Recommended over public networks (append to the connection string)

SQL Server

For enterprise environments with existing SQL Server infrastructure.

{
  "Database": {
    "Provider": "SqlServer",
    "ConnectionString": "Server=localhost;Database=polygent;Trusted_Connection=true;TrustServerCertificate=true"
  }
}

Auth	Connection-string fragment
Windows / integrated auth	Trusted_Connection=true
SQL Server auth	User Id=polygent;Password=...
With certificate validation	Remove TrustServerCertificate=true and provide a trusted cert

The login must have permission to create tables and indexes in the target database (schema migrations create the schema on first start).

Switching Providers

Switching providers does not copy data — each provider holds its own schema. To migrate:

1. Provision the new database
2. Export your data from the old provider (manual SQL dump or your own script)
3. Update Database:Provider and Database:ConnectionString
4. Start the API once with an empty target database (let migrations run)
5. Import data into the new database

Plan around: signing keys (in StoragePath/signing-key.xml), worktrees (in StoragePath), and uploaded ticket attachments stay on the filesystem and are independent of the database provider.

Migrations

Migrations run automatically on startup in two stages:

1. Schema migrations — create or upgrade tables and indexes for the configured provider
2. Data migrations — sequential, transactional migrations that run after the schema is current

A new (empty) database is detected on first start and migrations are skipped — Polygent creates the schema directly. On subsequent starts, only outstanding migrations run.

If a critical migration fails, startup aborts; check the logs (see System Logs) for the specific failure. Non-critical migrations log a warning and continue.

Applied migrations are tracked in the database itself, so they never re-run.

Connection Pooling

Polygent uses EF Core's default connection pooling. For PostgreSQL and SQL Server you can tune the pool via the connection string (e.g., Maximum Pool Size=100). SQLite ignores pool settings (and Polygent disables SQLite's pool internally — see the SQLite section above).

Backups

Provider	Recommended approach
SQLite	Stop the API or use .backup (online backup); back up {StoragePath}/polygent.db
PostgreSQL	pg_dump on a schedule, or your managed-service snapshot feature
SQL Server	Native backup plans, or your managed-service snapshot feature

Always include StoragePath (signing keys, worktrees, attachments) in your backup plan along with the database — restoring just the database leaves the install partially recovered.

See Also

• Storage — StoragePath layout
• Environment Variables — overriding Database__ConnectionString
• System Logs — diagnosing migration failures