Skip to content

Document the cache name argument of DBCC FREESYSTEMCACHE - #10468

Open
Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
MicrosoftDocs:livefrom
rudi-bruchez:fix/freesystemcache-cache-name
Open

Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
MicrosoftDocs:livefrom
rudi-bruchez:fix/freesystemcache-cache-name

Conversation

@rudi-bruchez

@rudi-bruchez Rudi Bruchez (rudi-bruchez) commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What's wrong

The syntax shows only ( 'ALL' [ , pool_name ] ), but DBCC FREESYSTEMCACHE also accepts the name of a single cache as its first argument, for example DBCC FREESYSTEMCACHE ('SQL Plans') or DBCC FREESYSTEMCACHE ('Temporary Tables & Table Variables'). No page in the docs documents this form, although it frees cached temporary tables in tempdb without 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 on sys.dm_os_memory_clerks. That query was later corrected to sys.dm_resource_governor_resource_pools (140a87f), which is right for pool_name, so the cache name argument the sentence refers to is now undocumented.

The Remarks say that running DBCC FREESYSTEMCACHE clears 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_counters is 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 (after ALTER RESOURCE GOVERNOR RECONFIGURE) are accepted. Memory pool names from sys.dm_os_memory_pools return Msg 2560 "Parameter 2 is incorrect". The current query for pool_name is correct.

Plan cache, 20 ad hoc queries and one stored procedure, same results on both versions:

Statement Ad hoc plans Procedure plan
(loaded) 20 1
('SQL Plans', 'internal') 20 1
('SQL Plans', 'default') 0 1
('SQL Plans') 0 1
('Object Plans') 0 0
('ALL', 'internal') 20 1
('ALL') 0 0

('TokenAndPermUserStore'): 31 entries to 0, the 10 cached ad hoc plans stay.

Temporary table caching, a procedure that creates #t:

CREATE PROCEDURE dbo.t AS BEGIN CREATE TABLE #t (id int); INSERT #t VALUES (1); END;
GO
EXEC dbo.t;   -- one cached #XXXXXXXX table in tempdb.sys.tables, one cached plan
DBCC FREESYSTEMCACHE ('Temporary Tables & Table Variables');
WAITFOR DELAY '00:00:12';
-- zero cached temporary tables, the procedure plan is still cached

Change

Adds cache_name to 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.

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.
@prmerger-automator

Copy link
Copy Markdown
Contributor

Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 6ccf712:

✅ Validation status: passed

File Status Preview URL Details
docs/t-sql/database-console-commands/dbcc-freesystemcache-transact-sql.md ✅Succeeded

For more details, please refer to the build report.

@v-dirichards

Copy link
Copy Markdown
Contributor

Umachandar Jayachandran (@uc-msft)

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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_name to 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 ] )

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. The front matter description and the introduction now mention the single-cache form as well.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 4ee3cc6:

✅ Validation status: passed

File Status Preview URL Details
docs/t-sql/database-console-commands/dbcc-freesystemcache-transact-sql.md ✅Succeeded

For more details, please refer to the build report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants