Persistence Layer — PostgreSQL

All WebStream state lives in PostgreSQL, organised as three logical databases with clear ownership: the IAM control plane owns webstream_iam, and the Metrics Engine owns webstream_metrics and webstream_activity. A single-server deployment runs a bundled local PostgreSQL; scaled deployments point the same connection strings at a shared or managed cluster such as RDS/Aurora.

The three databases

Database	Owner (writer)	Also read by	Contents
`webstream_iam`	Access Management (standalone, or built into the Gateway)	Gateway, session hosts (auth routes), CLI commands, Metrics Engine (licence resolution at startup)	Organizations, users, groups, applications, workspaces, policies, credentials, tokens, leases, IAM audit trail.
`webstream_metrics`	Metrics Engine (sole writer)	Admin console via the query API	Node registry and time-series performance data.
`webstream_activity`	Metrics Engine (sole writer)	Admin console reports; billing rollup service	User activity audit trail and usage-metering records.

Streamers, session hosts, and gateways never write metrics or activity data directly — they POST JSON to the Metrics Engine, which buffers and persists it. This keeps database credentials off the app tier and means the database can be moved or upgraded without touching any streamer.

Schema overview

`webstream_iam`

Area	Tables
Tenancy & directory	`organisations`, `users`, `groups`, `user_group_memberships`
Publishing & entitlements	`applications`, `workspaces`, `workspace_apps`, `workspace_rights`, `policy_sets`
Authentication	`auth_users`, `auth_tokens`, `password_history`, `password_reset_tokens`, `sso_sessions`
Sessions & limits	`user_workspace_leases`, `workspace_session_limits`, `recording_settings`
Audit & system	`activity_log` (IAM admin audit), `system_settings`
Session persistence	`user_registry_hive`, `user_filesystem_hive`, `user_filesystem_hive_blob`
Auto-scaling	`ami_catalog`, `org_ami_assignments`, `managed_instances`, `backend_tag_overrides`

`webstream_metrics`

Table	Purpose
`nodes`	Every streamer/gateway/backend node that has reported in.
`metrics_raw`	Time-series performance snapshots: FPS, latency, CPU, bandwidth, session context.
`events`	Aggregated event counts by type.
`workspace_sessions`	One row per session with the IAM/workspace context captured at start.

`webstream_activity`

Table	Purpose
`session_activity_log`	Session lifecycle and file/print events (the end-user audit trail).
`input_activity_blocks`	10-second batched input activity blocks.
`clipboard_activity_log`	Copy/paste audit records.
`meter_slice`, `meter_hour_rollup`, `meter_submit_log`	15-minute billing slices, hourly rollups, and billing submission audit.

Note

Two similarly named tables serve different purposes: activity_log in the IAM database is the administrative audit (who changed which org/user/policy), while session_activity_log in the activity database is end-user session telemetry.

Connections and credentials

Each database section in app.config.xml carries a connection string without a password, plus a <passwordRef> resolved at runtime — passwords are never stored in plaintext:

Config section	Default connection
`accessManagement.database`	`Host=127.0.0.1;Port=5432;Database=webstream_iam;Username=webstream_iam;Pooling=true`
`metricsEngine.database.metrics`	`Host=127.0.0.1;Port=5432;Database=webstream_metrics;Username=webstream_metrics;Pooling=true`
`metricsEngine.database.activity`	`Host=127.0.0.1;Port=5432;Database=webstream_activity;Username=webstream_activity;Pooling=true`

passwordRef supports two schemes: dpapi:<base64> (Windows DPAPI ciphertext that decrypts only on that host — the installer's default) and env:<VARNAME> (an environment variable, useful with a secrets manager). Pool sizes are capped per section with maxPoolSize.

Schema management, backup and restore

Automatic schema. Every service creates and upgrades its own tables at startup (CREATE TABLE IF NOT EXISTS plus additive column migrations), coordinated across processes with a PostgreSQL advisory lock. There are no manual migration scripts to run.
Seeding. First start creates the default organization, the built-in notrust policy, and the initial admin user.
Backup / restore CLI. webstream.exe -db-status probes all three databases; -db-backup [-out <dir>] takes pg_dump custom-format backups of each; -db-restore -file <dump> -target iam|metrics|activity restores one. See the CLI Scripting Guide.
Retention. Raw metrics are pruned after metricsEngine.database.retentionDays (default 10); rollups preserve long-term trends.

Upgrading from earlier versions

Configurations from pre-PostgreSQL releases may still show SQLite paths such as ./data/iam.db or ./metrics/metrics.db. Those settings are ignored by current releases — the <connectionString>/<passwordRef> blocks shown above are authoritative, and built-in authentication now lives in webstream_iam rather than a separate users database.