[Linux] Upgrade SQL Server considerations (#36043)

Author: rwestMSFT

docs/linux/includes/cgroup-support.md

@@ -1,15 +1,17 @@
 ---
 author: rwestMSFT
 ms.author: randolphwest
-ms.date: 09/05/2025
+ms.reviewer: amitkh, atsingh
+ms.date: 04/20/2026
 ms.service: sql
 ms.topic: include
 ms.custom:
   - linux-related-content
+ai-usage: ai-assisted
 ---
-Starting with [!INCLUDE [sssql25-md](../../includes/sssql25-md.md)] and [!INCLUDE [sssql22-md](../../includes/sssql22-md.md)] CU 20, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] detects and honors control group (cgroup) v2 constraints, improving performance stability and resource isolation across Docker, Kubernetes, and OpenShift environments. Control groups enable fine-grained control in the Linux kernel over system resources such as CPU and memory.
+[!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] detects and honors control group (cgroup) v2 constraints, starting with [!INCLUDE [sssql25-md](../../includes/sssql25-md.md)] and [!INCLUDE [sssql22-md](../../includes/sssql22-md.md)] Cumulative Update (CU) 20. These constraints provide fine-grained control in the Linux kernel over CPU and memory resources, and improve resource isolation in Docker, Kubernetes, and OpenShift environments.
 
-With cgroup v2 support, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] mitigates out of memory (OOM) errors previously observed in containerized deployments, particularly on Kubernetes clusters (for example, AKS v1.25+), where memory limits defined in container specifications weren't enforced.
+In earlier versions, containerized deployments on Kubernetes clusters (for example, Azure Kubernetes Service v1.25+) could experience out of memory (OOM) errors because [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] didn't enforce memory limits defined in container specifications. Support for cgroup v2 addresses this problem.
 
 ### Check cgroup version
 
@@ -21,27 +23,74 @@ The results are as follows:
 
 | Result | Description |
 | --- | --- |
-| `cgroup2fs` | You're using cgroup v2 |
-| `cgroup` | You're using cgroup v1 |
+| `cgroup2fs` | You use cgroup v2 |
+| `cgroup` | You use cgroup v1 |
 
 ### Switch to cgroup v2
 
 The easiest path is choosing a distribution that supports cgroup v2 out of the box.
 
-If you need to switch manually, add the following line to your GRUB configuration:
+If you need to switch manually, add the following parameter to your GRUB configuration:
 
 ```text
 systemd.unified_cgroup_hierarchy=1
 ```
 
-Then, run the following command to update GRUB:
+Then update GRUB. For example, on Ubuntu, run:
 
 ```bash
 sudo update-grub
 ```
 
+On Red Hat Enterprise Linux (RHEL), run:
+
+```bash
+sudo grub2-mkconfig -o /boot/grub2/grub.cfg
+```
+
+### CPU limit reporting with cgroup v2
+
+When you configure CPU limits using cgroup v2, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] doesn't show the configured CPU core count in the error log. Instead, it continues to report the total number of host CPUs.
+
+To align [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] scheduler and query plans (for example, parallelism decisions) with the intended CPU count defined in cgroup v2, apply the following configuration.
+
+#### Configure processor affinity
+
+Explicitly set [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] processor affinity to match the cgroup execution quota. In the following example, the cgroup quota is four CPUs on an eight-core host:
+
+```sql
+ALTER SERVER CONFIGURATION
+SET PROCESS AFFINITY CPU = 0 TO 3;
+```
+
+This configuration ensures that [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] creates schedulers only for the intended number of CPUs. For more information, see [ALTER SERVER CONFIGURATION](../../t-sql/statements/alter-server-configuration-transact-sql.md) and [Use PROCESS AFFINITY for Node and/or CPUs](../sql-server-linux-performance-best-practices.md#use-process-affinity-for-node-andor-cpus).
+
+#### Enable trace flag 8002 (recommended)
+
+Enable trace flag 8002 to use soft affinity at the SQLPAL layer:
+
+```bash
+sudo /opt/mssql/bin/mssql-conf traceflag 8002 on
+```
+
+By default, schedulers are bound to specific CPUs defined in the affinity mask. Trace flag 8002 allows schedulers to move across CPUs instead, which generally improves performance while still respecting affinity and cgroup constraints. For more information, see [DBCC TRACEON - Trace Flags](../../t-sql/database-console-commands/dbcc-traceon-trace-flags-transact-sql.md#tf8002).
+
+Restart [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] after enabling the trace flag.
+
+#### Expected behavior
+
+After restart:
+
+- [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] creates only the number of schedulers defined by the affinity setting (for example, four schedulers).
+
+- The Linux kernel continues to enforce the cgroup v2 CPU execution quota.
+
+- Query optimization and parallelism decisions are based on the intended CPU count, rather than the total host CPUs.
+
+> [!NOTE]  
+> The [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] error log might continue to display the total host CPU count. This logging and display behavior doesn't affect actual CPU usage, scheduler creation, or CPU enforcement by cgroup v2 or processor affinity.
+
 For more information, see the following resources:
 
 - [Quickstart: Deploy a SQL Server Linux container to Kubernetes using Helm charts](../sql-server-linux-containers-deploy-helm-charts-kubernetes.md)
-- [Linux Kernel cgroup v2 documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html)
-- [Control Group v2](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html)
+- [Control Group v2 (Linux Kernel documentation)](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html)

docs/linux/install-upgrade/upgrade-considerations.md

@@ -0,0 +1,133 @@
+---
+title: Considerations for Upgrading SQL Server on Linux
+description: Learn about the different options for upgrading SQL Server on Linux, including in-place upgrades and migration to a new instance.
+author: rwestMSFT
+ms.author: randolphwest
+ms.reviewer: amitkh, atsingh
+ms.date: 04/19/2026
+ms.service: sql
+ms.subservice: linux
+ms.topic: upgrade-and-migration-article
+ms.custom:
+  - linux-related-content
+---
+
+# Considerations for upgrading SQL Server on Linux
+
+To minimize downtime and risk, you should consider several approaches when planning to upgrade the [!INCLUDE [ssdenoversion-md](../../includes/ssdenoversion-md.md)] from an earlier release of [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] on Linux.
+
+| Upgrade approach | Downtime estimate | Recommended |
+| --- | --- | --- |
+| [Upgrade in place](#upgrade-in-place) | Minutes or hours | No |
+| [Migrate to a new instance](#migrate-to-a-new-instance) | Seconds or minutes (cutover only) | Yes |
+
+The amount of downtime depends on the size of your database and the speed of your I/O subsystem. Upgrading a database with memory-optimized tables can take extra time. For more information, see [Plan and test the Database Engine upgrade plan on Windows](../../database-engine/install-windows/plan-and-test-the-database-engine-upgrade-plan.md).
+
+> [!NOTE]  
+> The downtime estimate for migration refers to the cutover window when you redirect users to the new instance. The total elapsed time for building and preparing the new environment is longer.
+
+Make sure that your high availability and disaster recovery (HADR) strategy includes a fallback scenario. The complexity of your environment and your organization's service-level agreement (SLA) dictates which process to follow, and the associated risks.
+
+[!INCLUDE [editions-supported-features-linux](../../includes/editions-supported-features-linux.md)]
+
+## Considerations
+
+If you perform an in-place upgrade, the previous [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance is overwritten and no longer exists on your computer. If you migrate to a new instance, the previous instance remains intact until you decommission it. Regardless of which approach you choose, back up your [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] databases and other objects associated with the previous [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance before you begin.
+
+> [!NOTE]  
+> Refer to your vendor documentation to stay up to date about operating system security, networking, clustering, monitoring, and any other components and dependencies.
+
+### Security
+
+- **Operating system security**: If you installed [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] as a *confined service* on a Security-Enhanced Linux (SELinux) distribution, back up this configuration. For more information, see [Get started with SQL Server on SELinux](../sql-server-linux-security-selinux.md).
+
+- **Certificates**: Back up certificates for transparent data encryption (TDE), Always On availability groups and failover cluster instances, linked servers, replication, log shipping, Database Mail, PolyBase, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] Agent, Service Broker, and applications (including Always Encrypted). For more information, see [TDS 8.0](../../relational-databases/security/networking/tds-8.md) and [TLS 1.3 support](../../relational-databases/security/networking/tls-1-3.md).
+
+- **Credentials**: Most [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] credentials are stored in `master`, but you should back up service master keys, database master keys, column master keys, and connection information for linked servers, Azure Key Vault, hardware security modules, Active Directory / Kerberos, and Microsoft Entra ID. For more information, see [Get started with Database Engine permissions](../../relational-databases/security/authentication-access/getting-started-with-database-engine-permissions.md) and [Securables](../../relational-databases/security/securables.md).
+
+- **Firewall**: By default, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] requires TCP port 1433 for client access. Back up any firewall rules in place for your environment.
+
+### Configuration
+
+- **mssql-conf**: Use the **mssql-conf** tool to configure the [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance. It stores settings in the `mssql.conf` file. For information on where this file is located, see [Configure SQL Server on Linux with the mssql-conf tool](../sql-server-linux-configure-mssql-conf.md).
+
+  > [!NOTE]  
+  > The SQL Server platform abstraction layer (SQLPAL) doesn't store any user accessible configuration. You don't need to back it up.
+
+- **cgroups**: If you use cgroups to manage resource utilization for your environment, back up your configuration.
+
+- **Network**: Back up your network configuration, including host files, DNS, connection strings, load balancers, and so on.
+
+- **SQL Server Agent**: Script out and check all [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] Agent jobs, including database and server maintenance tasks. For example, if you change your host name, or your file system access changes, it can cause jobs to fail, behave unexpectedly, or possibly overwrite existing database backups.
+
+- **Monitoring**: Check for any monitoring agents you installed, including the Azure Connected Machine agent.
+
+- **Clustering**: Back up any cluster resource management configuration, such as Pacemaker and Corosync.
+
+## No setup program
+
+Unlike [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] on Windows, [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] on Linux doesn't have a setup program. Instead, it's distributed in packages for each component. To install or upgrade the database engine and other components, use the package manager included with your Linux distribution. For installation steps, see [Installation guidance for SQL Server on Linux](../sql-server-linux-setup.md). For information about configuring package repositories, see [Configure repositories for installing and upgrading SQL Server on Linux](../sql-server-linux-change-repo.md).
+
+## Upgrade in place
+
+With this approach, the package manager removes the binaries for the previous version of [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] and replaces them with the new binaries. Your configuration stays in place.
+
+> [!NOTE]  
+> If the upgrade requires any external dependencies, such as newer versions of packages like Python or OpenSSL, the package manager resolves these dependencies and installs them before updating [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] packages.
+
+When [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] starts up the first time, it runs several scripts to upgrade each of the system and user databases.
+
+While the in-place upgrade approach is easiest, it requires some amount of downtime. If the process fails, the server might be left in an inconsistent state.
+
+Use this approach in the following scenarios:
+
+- A development environment without a high-availability (HA) configuration.
+
+- A non-mission critical production environment that can tolerate downtime and that's running on recent hardware and software.
+
+## Migrate to a new instance
+
+Migrating to a new environment (also known as *side-by-side*) minimizes downtime and provides an opportunity to fail back to the source server if something goes wrong. By using this approach, you keep the current environment while you build a new [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] environment, frequently on new hardware or a new virtual machine, and with a new version of the operating system.
+
+Use this approach to upgrade:
+
+- An installation of [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] on an unsupported operating system.
+- [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] running on a Windows Server that you want to migrate to Red Hat Enterprise Linux or Ubuntu.
+- [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] to new hardware, a new virtual machine, and/or a new version of the operating system.
+- [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] with server consolidation.
+
+1. [Migrate system configuration](#migrate-system-configuration)
+1. [Migrate system objects](#migrate-system-objects)
+1. [Migrate user databases](#migrate-user-databases)
+1. [Point to the new instance](#point-to-the-new-instance)
+
+### Migrate system configuration
+
+Set up your new environment, referencing the [Security](#security) and [Configuration](#configuration) settings you backed up previously. Follow the [installation guidance](../sql-server-linux-setup.md) to install and configure [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] on Linux.
+
+### Migrate system objects
+
+Some applications depend on information, entities, and objects that are outside of the scope of a single user database.
+
+Typically, an application has dependencies on the `master` and `msdb` databases, and also on the user database. The destination server instance needs to have available anything stored outside of a user database required for the correct functioning of that database.
+
+For example, application logins are stored as metadata in the `master` database, and you must recreate them on the destination server. If an application or database maintenance plan depends on [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] Agent jobs, whose metadata is stored in the `msdb` database, you must recreate those jobs on the destination server instance. Similarly, the metadata for a server-level trigger is stored in `master`.
+
+When you move the database for an application to another server instance, you must recreate the metadata of the dependent entities and objects in `master` and `msdb` on the destination server instance. For example, if a database application uses server-level triggers, just attaching or restoring the database on the new instance isn't enough. The database doesn't work as expected unless you manually recreate the metadata for those triggers in the `master` database. For detailed information, see [Manage Metadata When Making a Database Available on Another Server](../../relational-databases/databases/manage-metadata-when-making-a-database-available-on-another-server.md).
+
+### Migrate user databases
+
+After you recreate the system objects on the new [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] environment, migrate the user databases from the existing system to the new [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance in a way that minimizes downtime on the existing system. You can accomplish the database migration either by using backup and restore, or by repointing LUNs if you're in a SAN environment.
+
+For more information about using backup and restore on Linux, see [Back up and restore SQL Server databases on Linux](../sql-server-linux-backup-and-restore-database.md).
+
+### Point to the new instance
+
+After migrating user databases, point new users to the new [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance using one of several methods (for example, renaming the server, using a DNS entry, and modifying connection strings). Compared to an in-place upgrade, migrating to a new instance reduces risk and downtime, and gives you an opportunity to upgrade hardware and the operating system at the same time.
+
+## Related content
+
+- [Migrate databases and structured data to SQL Server on Linux](../sql-server-linux-migrate-overview.md)
+- [Migrate a SQL Server database from Windows to Linux using backup and restore](../sql-server-linux-migrate-restore-database.md)
+- [Back up and restore SQL Server databases on Linux](../sql-server-linux-backup-and-restore-database.md)
+- [Create and configure an availability group for SQL Server on Linux](../sql-server-linux-create-availability-group.md)

docs/linux/sql-server-linux-docker-container-configure.md

@@ -1,9 +1,9 @@
 ---
 title: Configure and Customize SQL Server Docker Containers
 description: Understand the different ways to customize SQL Server Docker Containers and how you can configure it based on your requirements.
-author: amitkh-msft
-ms.author: amitkh
-ms.reviewer: vanto, randolphwest
+author: rwestMSFT
+ms.author: randolphwest
+ms.reviewer: amitkh, atsingh
 ms.date: 09/05/2025
 ms.service: sql
 ms.subservice: linux
@@ -892,7 +892,7 @@ For examples of custom Docker containers, see <https://github.com/microsoft/mssq
 
 For information on how to build and run Docker containers using Dockerfiles, see the [ML Services samples](https://github.com/microsoft/mssql-docker/tree/master/linux/preview/examples/mssql-mlservices) on GitHub.
 
-## Configure memory limits with control group (cgroup) v2
+## Control group (cgroup) v2 support
 
 [!INCLUDE [cgroup-support](includes/cgroup-support.md)]
 

docs/linux/sql-server-linux-editions-and-components-2022.md

@@ -3,7 +3,7 @@ title: "Editions and Supported Features of SQL Server 2022 - Linux"
 description: This article describes editions, features, and components supported by the various editions of SQL Server 2022 on Linux.
 author: rwestMSFT
 ms.author: randolphwest
-ms.reviewer: amitkh, vanto
+ms.reviewer: amitkh, atsingh
 ms.date: 11/27/2025
 ms.service: sql
 ms.subservice: linux
@@ -215,7 +215,7 @@ For info about the Integration Services (SSIS) features supported by the edition
 | Advanced spatial libraries | Yes | Yes | Yes | Yes |
 | Import/export of industry-standard spatial data formats | Yes | Yes | Yes | Yes |
 
-## Configure memory limits with control group (cgroup) v2
+## Control group (cgroup) v2 support
 
 [!INCLUDE [cgroup-support](includes/cgroup-support.md)]
 

docs/linux/sql-server-linux-editions-and-components-2025.md

@@ -4,7 +4,7 @@ titleSuffix: SQL Server 2025 on Linux
 description: This article describes editions, features, and components supported by the various editions of SQL Server 2025 on Linux.
 author: rwestMSFT
 ms.author: randolphwest
-ms.reviewer: amitkh, vanto
+ms.reviewer: amitkh, atsingh
 ms.date: 01/08/2026
 ms.service: sql
 ms.subservice: linux
@@ -284,7 +284,7 @@ For info about the Integration Services (SSIS) features supported by the edition
 | Advanced spatial libraries | Yes | Yes | Yes |
 | Import/export of industry-standard spatial data formats | Yes | Yes | Yes |
 
-## Configure memory limits with control group (cgroup) v2
+## Control group (cgroup) v2 support
 
 [!INCLUDE [cgroup-support](includes/cgroup-support.md)]