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"
  }
}

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. Use a tested, database-admin-led migration that preserves schema constraints and application data; generic table dumps are not a supported conversion procedure.

1. Back up the source database and StoragePath, then test both backups.
2. Stop Polygent to prevent writes.
3. Provision an empty target database with the required migration permissions.
4. Convert and validate the data with your approved database migration tooling in a staging environment.
5. Set Database:Provider and Database:ConnectionString, then start Polygent against the validated target.
6. Verify users, workspaces, sessions, tickets, settings, attachments, and protected credentials before reopening access.

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.

Troubleshooting

SQLite: startup hangs during schema migration

Symptom: On a SQLite install, the API logs that it initialized storage, then stops with no further output and no error — it never finishes starting. This typically happens on the first start after an upgrade, when a schema migration needs to run.

Cause: A previous start was killed (crash, forced service stop, or terminated upgrade) while the database was mid-write. A leftover lock from the killed process blocks the migration from acquiring write access, so startup waits indefinitely.

Fix:

1. Stop the API service so nothing is using the database.
2. Confirm no Polygent process is still running.
3. Delete the two sidecar files next to polygent.db:
   • {StoragePath}/polygent.db-wal
   • {StoragePath}/polygent.db-shm
   • Do not delete polygent.db itself — that is your data.
4. Start the API again. The migration completes and startup proceeds normally.

Before deleting: if the sidecar files are actively growing in size from second to second, a long-running migration is still in progress (a large Messages table can take several minutes to upgrade) — let it finish rather than deleting. Only remove the sidecar files when their size is static and no Polygent process is running.

This applies to SQLite only; PostgreSQL and SQL Server do not use -wal/-shm files.

Connection Pooling

Polygent disables SQLite connection pooling so an interrupted query cannot affect a later operation through a recycled connection. Custom SQLite connection strings are always normalized to Pooling=False, including strings that specify Pooling=True; omit the setting or specify Pooling=False to keep the configured intent clear.

PostgreSQL and SQL Server retain their provider-default pooling behavior. Tune those pools through their connection strings when required (for example, Maximum Pool Size=100).

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