Repository navigation
Document the cache name argument of DBCC FREESYSTEMCACHE - #10468
Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
Conversation
The syntax only showed 'ALL', although the command accepts the name of a single cache, as listed in sys.dm_os_memory_cache_counters. The sentence about freeing caches individually sat under pool_name since a 2020 edit pointed to memory clerks there; the pool query was later corrected, which left the cache name undocumented.
|
Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Learn Build status updates of commit 6ccf712: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Umachandar Jayachandran (@uc-msft) Can you review the proposed changes? Important: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
There was a problem hiding this comment.
🟡 Changes recommended
The introduction omits the newly documented cache-specific behavior, and the new DMV query does not explain its separate permission requirements.
1 open issue
What changed in this PR
This pull request documents the cache_name form of DBCC FREESYSTEMCACHE, clarifying targeted cache clearing and its distinction from clearing all caches.
Changes:
- Adds
cache_nameto the syntax and arguments, including a query for listing valid cache names. - Limits the plan-cache remark to
DBCC FREESYSTEMCACHE ('ALL'). - Adds examples for clearing SQL Plans and cached temporary tables independently.
| File | Summary |
|---|---|
docs/t-sql/database-console-commands/dbcc-freesystemcache-transact-sql.md |
Documents individual cache clearing, updated behavior, and examples. Outstanding nit findings request updating the description and lead to mention specified caches, and documenting the DMV permissions required by the new cache-name query. |
Review effort: Lite
| ```syntaxsql | ||
| DBCC FREESYSTEMCACHE | ||
| ( 'ALL' [ , pool_name ] ) | ||
| ( { 'ALL' | 'cache_name' } [ , pool_name ] ) |
There was a problem hiding this comment.
Thanks. The front matter description and the introduction now mention the single-cache form as well.
|
Learn Build status updates of commit 4ee3cc6: ✅ Validation status: passed
For more details, please refer to the build report. |

What's wrong
The syntax shows only
( 'ALL' [ , pool_name ] ), butDBCC FREESYSTEMCACHEalso accepts the name of a single cache as its first argument, for exampleDBCC FREESYSTEMCACHE ('SQL Plans')orDBCC FREESYSTEMCACHE ('Temporary Tables & Table Variables'). No page in the docs documents this form, although it frees cached temporary tables intempdbwithout removing any plan from the plan cache.The sentence "Most, but not all, caches can be individually freed using this command" is a leftover from a 2020 edit (208b5e0) that placed it under
pool_name, together with a query onsys.dm_os_memory_clerks. That query was later corrected tosys.dm_resource_governor_resource_pools(140a87f), which is right forpool_name, so the cache name argument the sentence refers to is now undocumented.The Remarks say that running
DBCC FREESYSTEMCACHEclears the plan cache. That's true for'ALL'. With a cache name, only that cache is cleared:DBCC FREESYSTEMCACHE ('TokenAndPermUserStore')leaves the plan cache intact.Evidence
SQL Server 2025 CU7 (17.0.4065.4) and SQL Server 2022 CU26 (16.0.4265.3), Linux containers, Developer edition. Fresh database for each test, dropped afterward.
First argument: every name in
sys.dm_os_memory_cache_countersis accepted (112 of 112 on 2025, 87 of 87 on 2022). An unknown name returns Msg 2560 "Parameter 1 is incorrect".Second argument:
default,internal, and a newly created resource pool (afterALTER RESOURCE GOVERNOR RECONFIGURE) are accepted. Memory pool names fromsys.dm_os_memory_poolsreturn Msg 2560 "Parameter 2 is incorrect". The current query forpool_nameis correct.Plan cache, 20 ad hoc queries and one stored procedure, same results on both versions:
('SQL Plans', 'internal')('SQL Plans', 'default')('SQL Plans')('Object Plans')('ALL', 'internal')('ALL')('TokenAndPermUserStore'): 31 entries to 0, the 10 cached ad hoc plans stay.Temporary table caching, a procedure that creates
#t:Change
Adds
cache_nameto the syntax and arguments, with the query that lists cache names, and moves the "Most, but not all" sentence there. Limits the plan cache remark to'ALL'. Adds an example that frees a single cache, including cached temporary tables.Not tested: Azure SQL Database, Azure SQL Managed Instance, and SQL database in Fabric, which the page also covers.