Migrating to RDS / Aurora

Because WebStream talks standard PostgreSQL over standard connection strings, moving from the bundled local instance to Amazon RDS for PostgreSQL or Aurora PostgreSQL is a configuration change plus a data copy — no application changes, no schema scripts. It is the natural step when you move to a multi-instance topology or want managed backups and multi-AZ resilience.

Why migrate

Multi-instance consistency. Once more than one host needs the IAM database (multiple gateways, or a standalone Access Management service), the database must live off-instance. This is the databases-as-a-service leg of deployment patterns 3 and 4.
Resilience. RDS Multi-AZ or an Aurora cluster survives an instance or AZ failure; the bundled single-node PostgreSQL does not.
Operations. Managed automated backups, point-in-time recovery, patching, and storage scaling replace manual pg_dump schedules.
Independent scaling. Database capacity scales separately from session-host compute, and AMIs for session hosts stay stateless.

What changes (and what does not)

Item	Before (bundled)	After (RDS/Aurora)
Connection host	`Host=127.0.0.1;Port=5432`	`Host=<cluster-endpoint>.rds.amazonaws.com;Port=5432`
Databases & roles	`webstream_iam`, `webstream_metrics`, `webstream_activity` with per-database users	Unchanged — recreate the same names and roles.
Password storage	`passwordRef` = `dpapi:<base64>` (host-bound)	`passwordRef` = `env:<VARNAME>` populated from AWS Secrets Manager, or a fresh `dpapi:` token per host.
Transport	Loopback, no TLS	Add `SSL Mode=Require` to each connection string.
Schema	Unchanged — services create and migrate their own tables at startup. Ensure the `citext` extension can be created (it is available on RDS/Aurora; the IAM service runs `CREATE EXTENSION IF NOT EXISTS citext`).
Application code	Unchanged.

Migration steps

Provision the instance. Create an RDS for PostgreSQL instance (Multi-AZ recommended) or an Aurora PostgreSQL cluster in the same VPC as your WebStream hosts. Match or exceed the bundled PostgreSQL major version.
Create databases and roles. Connect as the master user and create webstream_iam, webstream_metrics, and webstream_activity, each owned by a matching login role. Store the passwords in AWS Secrets Manager.
Open the network path. Add a security group rule allowing port 5432 from the WebStream hosts' security group only. The database should never be publicly accessible.
Stop WebStream services and take backups. On the current host run webstream.exe -db-backup -out C:\backups to produce pg_dump custom-format archives of all three databases.
Restore into RDS. Restore each archive with pg_restore against the new endpoint (for example pg_restore -h <endpoint> -U <master> -d webstream_iam <dump>), then confirm ownership/grants for the per-database roles.
Repoint the configuration. On every host that opens a database connection — gateway / Access Management for webstream_iam, the Metrics Engine host for the other two — update the <connectionString> host, add SSL Mode=Require, and update <passwordRef>.
Verify and cut over. Run webstream.exe -db-status on each host to probe connectivity, start the services, and sign in to the admin console to confirm IAM data is intact.
Retire the bundled instance. Stop and disable the local Webstream-Postgres Windows service so nothing silently writes to the old data directory.

Operational considerations

Topic	Guidance
Connection pooling	Each service holds its own Npgsql pool (`Maximum Pool Size` / `maxPoolSize`, defaults 10–20). Sum the pools across all hosts and keep the total under the instance's `max_connections`; size the RDS instance class accordingly.
Latency	Keep the database in the same region and VPC as the gateway/IAM and Metrics Engine hosts. Entitlement resolution sits on the login path, so cross-region database calls are noticeable.
Aurora endpoints	Point all WebStream connection strings at the writer (cluster) endpoint. Every service writes to its database, so reader endpoints are only useful for external reporting tools.
Backups & PITR	Enable automated backups and point-in-time recovery on the instance; `-db-backup` remains useful for pre-upgrade snapshots and copying data between environments.
Retention vs storage	Raw metrics volume is bounded by `metricsEngine.database.retentionDays` (default 10). Activity and metering records are retained indefinitely — budget storage growth for the activity database if metering for billing.
Maintenance windows	RDS minor-version patching restarts the database. Services reconnect automatically, but schedule maintenance windows outside peak session hours to avoid login blips.

Note

Session hosts and streamers require no changes at any point in this migration — they never connect to a database. Only hosts running the Gateway/Access Management and Metrics Engine services carry connection strings.