Version, Edition & Topology Changes

The operator supports in-place changes that preserve data on the existing PersistentVolumeClaims: upgrading the SQL Server version, raising the SQL Server edition on a running resource, and migrating a standalone MSSQLInstance to a MSSQLAvailabilityGroup.

note

This page is about changing an existing SQL Server deployment (its version, edition or topology). It is not about upgrading the operator itself — for that, see Installation.

Version upgrade

Change spec.image to a newer SQL Server image, either a cumulative update (2022-CU26-… → 2022-CU27-…) or a new major release (2022-… → 2025-…). SQL Server upgrades the databases when it first opens them on the new release.

spec:
  image: mcr.microsoft.com/mssql/server:2025-CU9-ubuntu-24.04   # was: 2022-CU27-ubuntu-22.04

• Standalone instances roll each pod onto the new image.
• Availability Groups follow SQL Server's rolling-upgrade order (since v0.1.11): secondaries first, then a planned failover to an upgraded secondary, then the former primary. The StatefulSet rolls pods from the highest ordinal down, so before the rollout starts the operator moves the primary to pod-0 with a planned (zero-data-loss) failover when it sits elsewhere and pod-0 is a healthy synchronous secondary. pod-0 is then upgraded last and its preStop hook fails over to an already-upgraded secondary.

tip

Pin images to a cumulative-update tag (for example 2022-CU27-ubuntu-22.04) rather than a floating -latest tag, so a pod restart never pulls a different build behind your back.

Downgrades are rejected

Databases upgraded by a newer release cannot be opened by an older one, so the admission webhook rejects lowering the release encoded in the image tag (for example 2025-… → 2022-…). Images whose tag does not start with a release year (custom registries or tags) are not judged. To move to an older release, restore a backup into a new resource.

Edition upgrade

Change spec.edition on a MSSQLInstance or MSSQLAvailabilityGroup to move to a higher edition. The operator passes the new value to the SQL Server container as MSSQL_PID and rolls the pod(s); the databases survive on the reused PVC. Microsoft ships a single image for all editions, so no image change is involved (see the MSSQL_PID mechanics in cr-reference.md).

spec:
  edition: Standard   # was: Express

Allowed paths

SQL Server can raise an edition on existing data but cannot lower it (a downgrade fails at engine startup). The admission webhook enforces this, so an unsupported change is rejected when the CR is applied:

From	Allowed to
Express	Developer, Standard, Enterprise, EnterpriseCore
Developer	Standard, Enterprise, EnterpriseCore
Standard	Enterprise, EnterpriseCore
Enterprise	EnterpriseCore
EnterpriseCore	Enterprise

• Setting the same edition is always allowed; an empty value defaults to Developer.
• Enterprise ⇄ EnterpriseCore is permitted in both directions (they differ only in licensing model).
• Downgrades are forbidden. To move to a lower edition, restore into a new resource.
• Express is rejected on MSSQLAvailabilityGroup (no Always-On support), so it cannot be the target edition of an AG.

Topology change (standalone → Availability Group)

MSSQLInstance and MSSQLAvailabilityGroup are separate CRDs — there is no in-place toggle on a single resource. To convert a standalone instance to an AG while keeping its data, bring up a MSSQLAvailabilityGroup on the reused PVCs of the standalone instance with adoptExistingDatabases enabled:

apiVersion: mssql.solanica.io/v1alpha1
kind: MSSQLAvailabilityGroup
metadata:
  name: my-mssql            # StatefulSet name; reuses the standalone PVCs
spec:
  size: 3                   # AG requires >= 2 replicas
  acceptEULA: true
  saPasswordSecret: my-mssql-secret
  edition: Developer        # any non-Express edition
  availabilityGroup:
    availabilityMode: synchronous
    adoptExistingDatabases: true

With adoptExistingDatabases: true, the operator adds any user database already present on the primary to the Availability Group — not just those listed in availabilityGroup.databases. Databases carried over on the reused PVC are joined to the AG on the primary and automatically seeded to the secondaries. Adoption is idempotent: databases already in the AG are skipped, so it is safe on every reconcile.

Requirements

• The MSSQLAvailabilityGroup must reuse the standalone instance's PVCs (same StatefulSet/resource name), so the previous MSSQLInstance must be removed first to avoid two controllers owning the same StatefulSet.
• At least 2 replicas (size >= 2).
• A non-Express edition (Developer, Standard, Enterprise, or EnterpriseCore) — Express does not support Always-On.

See availability-groups.md for full AG configuration.