Database

The database stores all platform state — users, workspaces, sessions, tickets, and history. Polygent supports three providers; SQLite is the default and needs no setup. Switch providers in appsettings.json and restart the API — schema migrations run automatically on startup.

Provider Selection

One provider is active per installation. 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)

SQLite is a single-file database suited to 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

PostgreSQL is 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 creates it only if the login is allowed to, which is not recommended
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

SQL Server suits environments with existing SQL Server infrastructure and DBA practices.

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

Moving to another provider is a data migration performed by your DBA. 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 upgrade the database automatically when a new release starts.

1. Schema migrations — create or upgrade tables and indexes for the configured provider. They always run before the API accepts requests; on a new database they create the full schema.
2. Data migrations — upgrade existing data after the schema is current. Most run during startup; a few long-running ones continue in the background after the API is available. On a new database, data migrations that only convert old data are skipped.

If a startup migration fails, the API does not start; check crash.log in the install folder and the system logs for the failure. A failed background migration is logged as an error while the API keeps running; send the error to Support. Applied migrations are tracked in the database, so they never re-run.

Back up the database before every upgrade: migrations are forward-only and cannot be rolled back by installing the previous release.

Troubleshooting

These are the database problems operators most often hit.

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 (large installations 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

Connection pooling is managed per provider. 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

Back up the database and StoragePath together as one recovery set.

Provider	Recommended approach
SQLite	Stop the API, or use the SQLite .backup command for an online copy of {StoragePath}/polygent.db; never copy the live file alone
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, data-protection keys, settings.json, attachments) and the harness data directory in the same backup set — restoring only the database leaves the install partially recovered. See Storage → Backup.

See Also

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