Skip to content

PostgreSQL, EF Core Migrations, And The New Deployment Baseline

Database support is not usually the headline feature in an identity platform. It becomes important when the platform team has to operate it for years. ProAuth v3 changes that operational baseline in a few concrete ways....

Migration guide7 min readmarc-mueller
Back to blog

Database support is not usually the headline feature in an identity platform. It becomes important when the platform team has to operate it for years.

ProAuth v3 changes that operational baseline in a few concrete ways. It supports SQL Server and PostgreSQL, moves schema deployment from the older SSDT/DACPAC model to EF Core migrations, stores ProAuth and UserStore objects in dedicated schemas, and standardizes the Helm chart model around new secret groups, resource names, and Kubernetes labels.

That combination is good news for new deployments and a real planning item for existing ones. The right question is not only “which database do we prefer?” It is “which upgrade path are we actually on?”

The release-level scope is covered in the ProAuth 3.0.0 release notes. The exact upgrade sequence, bridge command, and mapping tables belong in the ProAuth migration guide. This post focuses on the operational shape of the change.

flowchart TD
    start["Deployment planning"]
    fresh["Fresh ProAuth v3 installation"]
    existing["Existing ProAuth 2.x installation"]

    fresh --> provider["Choose one provider<br/>SqlServer or PostgreSql"]
    provider --> schemas["Deploy v3 schemas<br/>proauth and userstore"]
    schemas --> helmFresh["Run Helm initializer<br/>EF Core migrations for selected provider"]

    existing --> latest2["Update to latest ProAuth 2.x"]
    latest2 --> backup["Take verified backups<br/>ProAuth and every UserStore database"]
    backup --> bridge["Planned downtime<br/>Run SQL Server v2-to-v3 bridge"]
    bridge --> helmExisting["Deploy ProAuth v3 with Helm<br/>Provider remains SqlServer"]

    helmFresh --> selectors["Update operational baseline<br/>Secrets, names, selectors, monitoring"]
    helmExisting --> selectors
    selectors --> verify["Verify EF history, login, AdminApp, workers, alerts"]

    classDef path fill:#eef6ff,stroke:#2563eb,color:#10233f
    classDef action fill:#ffffff,stroke:#94a3b8,color:#172033
    classDef stop fill:#fff7ed,stroke:#ea580c,color:#431407
    class fresh,existing path
    class start,provider,schemas,helmFresh,latest2,backup,helmExisting,selectors,verify action
    class bridge stop

SQL Server and PostgreSQL are both v3 providers

ProAuth v3 supports SQL Server and PostgreSQL. The provider is selected globally with Data:DefaultConnection:Provider, or Data__DefaultConnection__Provider when supplied as an environment variable. The supported values are SqlServer and PostgreSql.

That setting applies to the whole ProAuth installation. The ProAuth database and all UserStore databases use the same provider. UserStore connection strings can still use aliases, but those aliases do not define a separate database provider.

For fresh ProAuth v3 installations, this makes PostgreSQL a first-class option alongside SQL Server. It also means the database choice should be made at the environment level, not independently per UserStore instance. Once the deployment baseline is set, the Helm initializer and database deployment worker follow that provider model.

The Helm chart documentation and root configuration documentation describe the provider setting and the startup sequence.

EF Core migrations replace SSDT and DACPAC deployment

The database deployment model also changes. ProAuth v3 uses EF Core migrations for schema deployment instead of the previous SSDT or DACPAC flow.

When ProAuth is deployed through the Helm chart, an initializer job runs before the ProAuth deployment starts. That initializer uses EF Core migrations for the configured provider. It creates or updates the ProAuth database schema, then scans for existing UserStore instances by looking for UserStore connection strings in the options. When UserStore instances are found, their schemas are migrated as well.

That sequencing matters. Schema deployment is no longer a separate artifact operation outside the application package. It is part of the Helm-controlled startup path, and the application starts only after the initializer has completed successfully.

For existing 2.x environments, the bridge migration prepares the database for that new flow. After a successful bridge migration, the regular Helm initializer should find the stamped InitialV3 EF Core migration and apply only later EF Core migrations when they exist.

The schemas are now explicit

ProAuth 2.x installations used SQL Server databases in the dbo schema. ProAuth v3 uses schema-local objects:

  • ProAuth objects are stored in the proauth schema.
  • UserStore objects are stored in the userstore schema.

The default deployment still uses separate databases for ProAuth and UserStores, but the schema separation also allows both sets of objects to exist in the same physical database when the configured connection strings point there.

This is more than a naming preference. Dedicated schemas make ownership easier to reason about, especially when the database deployment worker creates UserStore databases and assigns read/write and schema-deployment permissions. For SQL Server, created UserStore database users use userstore as the default schema. For PostgreSQL, created roles are granted access to the userstore schema.

The operational check is simple: scripts, backup verification, database grants, and monitoring queries that assumed dbo need to be reviewed before they are reused against v3 databases.

The 2.x bridge migration has boundaries

The standard upgrade path for existing ProAuth 2.x installations is intentionally narrower than the fresh-installation provider story.

Before upgrading, existing installations should first move to the latest ProAuth 2.x release. Then the ProAuth 3.x CLI bridge migration moves the SQL Server databases from the 2.x layout to the v3 layout. This is a planned downtime step. The migration guide says to take verified backups of the ProAuth database and every UserStore database, and to stop ProAuth 2.x or otherwise block writes while the migration and Helm upgrade are running.

The bridge migration creates the proauth and userstore schemas, moves existing tables from dbo into those schemas without copying table data, applies v3 schema changes, rewrites legacy label content paths, removes the old _MigrationScriptsHistory table after success, and stamps the schema-local EF Core migration history table with InitialV3.

There is an important database-provider boundary: the v2-to-v3 bridge migration supports SQL Server source and SQL Server target databases. A direct migration from SQL Server 2.x databases to PostgreSQL 3.x databases is not part of the standard upgrade path.

PostgreSQL is available for fresh ProAuth v3 installations, or for a separate customer-specific data migration project. It should not be folded into a routine 2.x-to-3.x upgrade window unless that separate migration has been designed, rehearsed, and owned as its own project.

Helm secrets and resources changed too

The database model is not the only operational change. ProAuth v3 also changes the Helm secret structure for the ProAuth Core chart and the ProAuth Admin App chart.

The new model keeps confidential values in Kubernetes Secrets and uses direct .NET configuration environment variable names as secret keys. Non-secret values, such as the provider, command timeout, host URL, email sender address, forwarded-header settings, known proxies, and deployment environment, should be supplied through Helm values or externalConfig.

For ProAuth Core, the v3 secret groups include runtime, crypto, dbSchemaDeployment, dbWorkerSqlserver, dbWorkerAzuresql, and dbWorkerPostgresql. For the Admin App, the equivalent model uses groups such as runtime, resourceDeployment, and crypto.

Installations that pre-create Kubernetes Secrets and enable externalSecrets need to create the v3 Secrets before upgrading the Helm release. The v3 chart does not read the old Secret group names or old lowercase keys. This is the kind of change that should be caught by a rendered-chart comparison, not discovered during the maintenance window.

Resource names and labels changed as well. The ProAuth v3 charts use the standard Helm and Kubernetes application label set, including app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/version, app.kubernetes.io/managed-by, app.kubernetes.io/part-of, and app.kubernetes.io/component.

That affects more than kubectl habits. Update scripts, dashboards, NetworkPolicies, ServiceMonitors, PodMonitors, alert rules, and custom wait logic that selected objects through legacy labels such as app=proauth, app=proauthadminapp, or release=<release>.

The common v3 selectors are explicit:

  • ProAuth runtime pods: app.kubernetes.io/name=proauth,app.kubernetes.io/component=identity-server
  • ProAuth database deployment worker pods: app.kubernetes.io/name=proauth,app.kubernetes.io/component=db-deployment-worker
  • ProAuth Admin App pods: app.kubernetes.io/name=proauthadminapp,app.kubernetes.io/component=admin-app

The Admin App chart also waits for ProAuth Core using the Core identity-server selector. If your environment has custom readiness checks around chart ordering, include that in the selector review.

No zero-downtime promise for existing 2.x upgrades

For existing ProAuth 2.x installations, the documented database bridge is a maintenance-window operation. It is not a zero-downtime upgrade promise.

That distinction is important for security infrastructure. During the transition, the platform is changing schema layout, migration history, Helm secret names, resource names, and selectors. The responsible plan is to rehearse the bridge migration, verify backups, block writes during the window, deploy the v3 charts with the updated provider and secret model, and validate the application before reopening normal traffic.

Fresh v3 installations have a cleaner path because they start directly on the new baseline. Existing estates get there safely by respecting the boundary between “upgrade the SQL Server 2.x estate to v3” and “choose PostgreSQL for a new v3 deployment or a separate migration project.”

A practical operations checklist

For platform teams, the work usually falls into a small number of workstreams:

  1. Decide whether the environment is a fresh ProAuth v3 installation or an existing ProAuth 2.x upgrade.
  2. For fresh installations, choose SqlServer or PostgreSql as the global provider and prepare database-worker credentials for that provider.
  3. For existing 2.x installations, update to the latest 2.x release, take verified backups, and rehearse the SQL Server v2-to-v3 bridge migration.
  4. Prepare v3 Helm values and Secrets using the new secret groups and direct environment variable keys.
  5. Review scripts, dashboards, ServiceMonitors, PodMonitors, NetworkPolicies, alerts, and wait logic for old resource names and labels.
  6. Confirm that database monitoring, grants, and queries use proauth and userstore schemas rather than assuming dbo.
  7. During the production maintenance window, block writes, run the bridge migration where applicable, deploy the v3 Helm release, and verify EF Core migration history, login, Admin App access, UserStore connectivity, database worker behavior, and monitoring.

The new baseline is a cleaner one: more database choice for v3, provider-specific EF Core migrations, clearer schemas, and a Kubernetes model that follows standard labels more consistently. The tradeoff is that existing 2.x environments need a careful, explicit move. Treat it as infrastructure work, not only an application update.

For exact commands and mapping tables, use the ProAuth migration guide. For installation settings, provider selection, database worker configuration, and Helm values, use the Helm chart documentation and root configuration documentation.