Repository navigation
Correct the database scope of plan cache removal for ALTER DATABASE - #10502
Open
Rudi Bruchez (rudi-bruchez) wants to merge 1 commit into
Open
Rudi Bruchez (rudi-bruchez) wants to merge 1 commit into
Rudi Bruchez (rudi-bruchez) wants to merge 1 commit into
Conversation
Changes to a database remove its cached plans while preserving plans in other databases. Describe the affected database and its subsequent compilations instead of an instance-wide cache-store flush.
Contributor
|
Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
Contributor
|
Learn Build status updates of commit b8223fb: ✅ Validation status: passed
For more details, please refer to the build report. |
Contributor
|
Umachandar Jayachandran (@uc-msft) Can you review the proposed changes? Due to the upcoming conference, all merging and publishing is on hold until the morning of November 17. Important: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's wrong
The SQL Server Remarks sections of
ALTER DATABASEandALTER DATABASE SET optionsdescribe changes to individual databases as clearing the plan cache for the instance. The tested changes remove plans associated with the affected database while preserving the same plan handles in other databases.Both pages also attach the cache-store flush error-log explanation to these database operations. The proposed wording describes compilation of affected queries after cached plans are removed, without implying an instance-wide store flush.
The published
ALTER DATABASE SET optionspage already contains an introductory note describing invalidation for the affected database; the instance-wide statement in Remarks contradicts that note. The Remarks wording is present in the March 2017 migration commitc8e798979d0and remains on Learn as of November 15, 2026.Sources:
Evidence
Tested on fresh Linux containers, Developer editions:
Each container was limited to 3 GB with
MSSQL_MEMORY_LIMIT_MB=2560andmax server memory (MB)=2048. The script creates two fresh databases with AUTO_CLOSE off, Query Store off, and optimize for ad hoc workloads off. It caches one ad hoc plan, one prepared plan and one procedure plan in each database and inmaster. Before every operation it asserts that all nine sentinel plans exist; afterward it compares their exact plan handles. Configuration andDBCC USEROPTIONSare included in the output.All three versions produce the same results:
The script additionally checks that the rename back, return from OFFLINE to ONLINE, and restore after DROP preserve the unrelated sentinel handles. ONLINE is checked after OFFLINE; the affected database has no cached plans at that point.
There are 14 cases and 129 result rows per version, including the snapshot's three plans and its source database's three plans (387 rows across three versions), plus the cleanup scope checks. Assertions cover plan counts, target-plan removal, unrelated-handle retention and the positive control. The script drops its databases, snapshot and procedure created in
master.The test uses disposable instances and sysadmin permissions, with
sqlcmd -b -I -C. It performs database detach/attach, restore and drop operations; the names and file paths below are reserved to this reproduction. Use the accompanying runner for an isolated environment.Change
The Remarks sections say that the listed options can remove cached plans for the affected database. They describe the compilation impact on subsequent executions of affected queries. The list uses the valid
MODIFY NAMEspelling, and PAGE_VERIFY replaces ONLINE in the SET-options list to match the measured changes and the existing ALTER DATABASE list.The general operation lists say that the operations can remove cached plans, without claiming an instance-wide flush. The transaction-log rebuild scenario remains in those lists, but was not tested and no scope-specific claim is added for it. Azure SQL Managed Instance and Azure SQL Database sections are unchanged; those products were not tested.
The separate AUTO_CLOSE paragraph is covered by PR #10431: #10431. This proposal does not duplicate its rewrite.