Dry-run xp_delete_file Before Actually Deleting Files?

xp_delete_file doesn’t really have a built-in dry-run option to preview which files it would remove. But there’s a simple workaround, and that’s exactly what this post will cover.  

We know that we can use the undocumented extneded stored procedure master.dbo.xp_delete_file to delete files, specifically the backup files, even the SQL Server maintenance plans commonly use it to delete old backup files based on their age. Here is a link to a blog post that I think neatly and succinctly explains the xp_delete_file:

https://www.sqlservercentral.com/blogs/using-xp_delete_file

Now as mentioned above, it is not possible to natively list the files that will be deleted by master.dbo.xp_delete_file before running the deletion. It simply deletes backup or report files matching the criteria without returning the list of targeted files.

However, you can work around this limitation by querying the filesystem, by some other ways, to see which files meet the deletion criteria before calling xp_delete_file. One of such approaches involves using the DMF sys.dm_os_enumerate_filesystem (available in SQL Server 2017 and later versions) to enumerate the files:  

• Use DMF sys.dm_os_enumerate_filesystem to list files in a folder filtered by extension.

• Filtering files further based on their last modified date compared to the cutoff date you intend to use with xp_delete_file.

• Reviewing the list to verify which files would be deleted.

The sys.dm_os_enumerate_filesystem DMF takes two required parameters:

• @initial_directory (nvarchar(255)): Your starting directory as an absolute path, like N'O:\MSSQL\Backup\'.

No, it won't dig into subdirectories, stays flat in that initial folder. Need recursion? Try xp_dirtree (with depth > 0) or xp_cmdshell with dir /s.

• @search_pattern (nvarchar(255)): A wildcard pattern like *, *.bak, or Log??.trn to filter files and folders.

For example, to list .bak files in a folder and see their last modified dates:

SELECT *    

FROM sys.dm_os_enumerate_filesystem('O:\MSSQL\Backup\', '*.bak')
WHERE last_write_time < DATEADD(WEEK, -1, GETDATE());

You can then compare this list with your parameters for xp_delete_file (e.g. backup files older than one week) and confidently run the delete operation knowing which files will be removed.

Please note that the DMF sys.dm_os_enumerate_filesystem is mostly undocumented, or more accurately, not officially documented. While it is enabled by default, it can be disabled by executing the following TSQL: 

exec sp_configure 'show advanced options', 1; 
exec sp_configure 'SMO and DMO XPs', 0;  
reconfigure;

Disable or enable a few new DMVs and DMFs

In case you are wondering or curious, there is no such direct configuration option to disable xp_delete_file specifically.

---

Next, combine sys.dm_os_enumerate_filesystem (to list files) and xp_delete_file (to delete files) in a safe scripted approach. This way, you first log the files that meet your deletion criteria into a SQL table, review them if needed, and then delete them by iterating over the logged list.

Step 1: Log Files Older than the Cutoff Date into a table

We use the dynamic management function sys.dm_os_enumerate_filesystem to enumerate files in your backup directory filtered by the .bak extension and older than a specified date (e.g., 7 days ago). Insert those into the logging table:

    
-- Drop table if needed
-- DROP TABLE dbo.DemoFilesToDelete;

-- Create the log table if it doesn't already exist
IF OBJECT_ID('dbo.DemoFilesToDelete') IS NULL
BEGIN
    CREATE TABLE dbo.DemoFilesToDelete
    (
        full_filesystem_path NVARCHAR(512),
        last_write_time      DATETIME2,
        size_in_bytes        BIGINT,
        is_deleted           BIT DEFAULT 0,
        deletion_time        DATETIME2
    );
END;
GO

-- Define variables
DECLARE @BackupPath NVARCHAR(512) = N'O:\MSSQL\Backup\';  -- Backup folder path
DECLARE @CutoffDate INT = -7;                             -- Negative value for days back
DECLARE @FileExt NVARCHAR(50) = '*BAK';                   -- Filename filter pattern

INSERT INTO dbo.DemoFilesToDelete
SELECT 
    full_filesystem_path,
    last_write_time,
    size_in_bytes,
    0 AS is_deleted,
    null deleation_time
FROM sys.dm_os_enumerate_filesystem(@BackupPath, @FileExt)
WHERE last_write_time < DATEADD(DAY, @CutoffDate, GETDATE())
  AND full_filesystem_path NOT IN (SELECT full_filesystem_path FROM dbo.DemoFilesToDelete)
  AND is_directory = 0
  AND is_system = 0;

-- SELECT * FROM dbo.DemoFilesToDelete;
GO

Step 2: Review the Files to Be Deleted

At this point, you can query the DemoFilesToDelete table to review which files are planned for deletion:

SELECT * FROM dbo.DemoFilesToDelete WHERE is_deleted = 0;

Step 3: Delete the Files One-by-One Using xp_delete_file

Now, iterate through each file in the list and call xp_delete_file to delete it. Since xp_delete_file requires a folder path and file extension or filename (depending on your SQL Server version), here is an example approach to delete each file individually using T-SQL with dynamic SQL:

/*

Here's how this works: it grabs file names from the table 
dbo.DemoFilesToDelete we populated in step 1, each with a 
little flag showing if it's been deleted yet 
(0 means nope, still there). It loops through  just those 
undeleted ones, zapping each file off the disk one by one with 
xp_delete_file, then flips the flag to mark it done. That way, 
it skips anything already handled, keeps a full history in case 
the same backup filename gets reused later, and avoids any messy 

repeat attempts.

*/

-- Declare variable to hold the file path to be deleted
DECLARE @file_to_be_deleted NVARCHAR(400);

-- Declare cursor to iterate over files not yet deleted
DECLARE DeleteCursor CURSOR LOCAL FAST_FORWARD FOR
    SELECT full_filesystem_path 
    FROM dbo.DemoFilesToDelete 
    WHERE is_deleted = 0;

OPEN DeleteCursor;

FETCH NEXT FROM DeleteCursor INTO @file_to_be_deleted;

DECLARE @count INT = 0;

-- Loop while fetch is successful
WHILE @@FETCH_STATUS = 0
BEGIN
    
    SET @count = @count + 1;
    RAISERROR('Deleting file: %s', 10, 1, @file_to_be_deleted);


    -- Uncomment this next line to actually delete the file
    -- EXEC master.dbo.xp_delete_file 0, @file_to_be_deleted;

    -- Mark the file as deleted in tracking table and record deletion time
    UPDATE dbo.DemoFilesToDelete
    SET 
        is_deleted = 1,
        deletion_time = GETDATE()
    WHERE 
        full_filesystem_path = @file_to_be_deleted
        AND is_deleted = 0;

    FETCH NEXT FROM DeleteCursor INTO @file_to_be_deleted;
END;

-- Close and deallocate cursor
CLOSE DeleteCursor;
DEALLOCATE DeleteCursor;

IF @count = 0
RAISERROR('** THERE WAS NOTHING TO DELETE **', 10, 1);

Notes and Best Practices

• xp_delete_file requires sysadmin permissions

• sys.dm_os_enumerate_filesystem requires VIEW SERVER STATE permission.

• xp_delete_file is an undocumented extended stored procedure and so is sys.dm_os_enumerate_filesystem; use them cautiously, preferably in test environments first.

• Ensure SQL Server service account has proper permissions on the files and folder to delete files 

• In production, wrap this in a TRY/CATCH block for proper error checking and handling

• For large numbers of files, consider batch deletes and proper error handling.

• You can use this method to other file types like .trn or maintenance plan reports by adjusting file extensions and parameters.

Writing Better Dynamic SQL

This updated and "sort" of a style guide is for SQL developers and, to some extent, DBAs, essentially anyone daring (and sometimes foolish) enough to wrestle with dynamic SQL without losing their mind. Whether you’re writing the code or cleaning up after it, these tips might save you some sleepless nights and a few colorful words. No promises, but at least you’ll have done your best to make someone’s life, and maybe your own, a little less miserable in the future.

---

Writing code that actually works, runs fast, and doesn’t explode with bugs is great, we all want that. But let's be honest, writing code that you (or anyone else) can still understand six months later is just as important. 

Now, let’s talk about dynamic SQL. Or rather, let’s not. Bring it up in some circles, and you might get the same reaction as announcing you still use tabs instead of spaces (developer humor). And many people (mainly DBAs) will tell you to avoid it like the plague, and they’re not entirely wrong, for two very good reasons:  

1. Security - hello, SQL injection!  
2. Performance - or lack thereof.

Think about the last time you had to fix someone else’s “clever” code. Even well-documented scripts can be confusing enough. Add dynamic SQL to the mix, and it starts feeling like a book that keeps shuffling its chapters every time you read it. Back in my younger, supposedly dazzling days, someone once described my dynamic SQL code as “very eloquent.” I took it as a compliment at the time, though, looking back, I’m not entirely sure it was.

So, here are few tips or best practices for writing dynamic SQL, because if we’re going to do something risky, we might as well do it semi-responsibly.

1. Document for Maintainability  

Add some comments around your dynamic SQL masterpiece. Explain why you built it this way, what the parameters are doing, and what sort of cosmic alignment was required for it to work. Dynamic SQL debugging is already a joy, no need to make it a full-blown treasure hunt.

/* EXAMPLE ***************
  Stored procedure to safely query Object ID by Name using dynamic SQL.

  Design considerations:
  - Uses sp_executesql for parameterization to prevent SQL injection.
  - Accepts user input as a parameter rather than string concatenation.
  - Uses QUOTENAME if needing to inject object names to avoid SQL injection.
  - Prints the constructed SQL string for debugging purposes.
*/

IF OBJECT_ID('tempdb..#GetObjectID') IS NOT NULL DROP PROCEDURE #GetObjectID 
GO
CREATE PROCEDURE #GetObjectID
  @ObjectName NVARCHAR(50)
AS
BEGIN
  -- Declare variable to hold dynamic SQL
  DECLARE @SqlCommand NVARCHAR(MAX);

  -- Build parameterized SQL query to select Object ID, filtering by Object Name
  SET @SqlCommand = N'
    SELECT object_id
    FROM sys.objects 
    WHERE name = @NameParam;
  ';
  -- Debug print of the SQL command string
  PRINT 'Executing SQL: ' + @SqlCommand;

  -- Execute dynamic SQL with parameter safely passed in
  EXEC sp_executesql @SqlCommand,
    N'@NameParam NVARCHAR(50)',
    @NameParam = @ObjectName;
END;

GO

-- Test
EXEC #GetObjectID 'sysdbfiles'

​

2. Prefer Parameterized Execution  

Great advise, but how? 

When executing dynamic SQL, always use sp_executesql with parameters instead of EXEC. It lowers your SQL injection risk, makes SQL Server actually reuse execution plans, and lets you have nice things like output variables.  

This example fetches a record from the sys.objects table using proper parameters, which is just a fancy way of saying “without inviting disaster.”

DECLARE @SqlCommand NVARCHAR(MAX) = N'SELECT * FROM sys.objects WHERE name = @ObjectName;';
DECLARE @ObjectName NVARCHAR(50) = 'sysdbfiles';
EXEC sp_executesql @SqlCommand, N'@ObjectName NVARCHAR(50)', @ObjectName;

This next example qualifies as a public service announcement on what *not* to do:

-- BAD - DO NOT USE **************

DECLARE @ObjectName NVARCHAR(50) = 'sysdbfiles';
DECLARE @SqlCommand NVARCHAR(MAX) = N'SELECT * FROM sys.objects WHERE Name = ''' + @ObjectName + N'''';
EXEC(@SqlCommand);

3. Avoid Unnecessary Dynamic SQL  

• Treat dynamic SQL like hot sauce: a little goes a long way, and too much will set everything on fire. Only use it when table, column, or object names actually require it, not just because typing EXEC is too convenient and powerful.   

• For filters and conditions, stick with parameterized T‑SQL or stored procedures. They may be boring, but “boring and secure” beats “exciting and hacked” any day.

4. Manage String Handling Carefully  

• When working with command strings, use NVARCHAR(MAX). Otherwise, enjoy the mystery of why half your query disappears into thin air.  

• Watch out for NULLs in concatenation, ISNULL, COALESCE, or CONCAT are your friends here. Pretend you care now, or you’ll definitely care later when your query returns nothing and you have no idea why.  

• And yes, use the built-in string functions (LTRIM, RTRIM, TRIM, CHARINDEX, STUFF, REPLACE, TRANSLATE, SUBSTRING, REPLICATE, REVERSE). They exist for a reason — mostly to save you from yourself.  

The following example shows how to handle strings properly in dynamic SQL, avoiding truncation, NULL chaos, and other developer regrets. It follows best practices for managing strings safely and cleanly in dynamic SQL construction.

/*
  Example: Building a dynamic query with safe string handling.
  - Uses NVARCHAR(MAX) to avoid truncation.
  - Handles NULL variables safely with ISNULL/COALESCE.
  - Demonstrates concatenation with CONCAT and "+" operator.
  - Uses sp_executesql to parameterize input safely.
*/

DECLARE @schema NVARCHAR(50) = NULL;
DECLARE @table NVARCHAR(50) = 'sysfiles';
DECLARE @column NVARCHAR(50) = 'name';
DECLARE @value NVARCHAR(50) = 'master';

-- Demonstrate concatenation with NULLs handled explicitly
DECLARE @sql1 NVARCHAR(MAX);
SET @sql1 = 'SELECT * FROM ' 
    + ISNULL(@schema + '.', '')  -- Prevent NULL schema from breaking string
    + @table
    + ' WHERE ' + @column + ' = @filterValue';

-- Alternative using CONCAT which treats NULL as empty string
DECLARE @sql2 NVARCHAR(MAX);
SET @sql2 = CONCAT(
    'SELECT * FROM ',
    COALESCE(@schema + '.', ''),  -- COALESCE also protects NULL
    @table,
    ' WHERE ', @column, ' = @filterValue'
);

-- Use sp_executesql with parameter to avoid injection and ensure plan reuse
EXEC sp_executesql @sql1,
   N'@filterValue NVARCHAR(50)',
   @filterValue = @value;

-- Output both SQL strings for debugging
PRINT 'SQL using ISNULL concat: ' + @sql1;
PRINT 'SQL using CONCAT: ' + @sql2;

Key Takeaways:

• Use NVARCHAR(MAX) for large dynamic strings. Otherwise, enjoy the thrill of wondering why half your SQL command just vanished mid‑execution.  

• Use ISNULL or COALESCE to keep one pesky NULL from turning your entire concatenated string into nothingness, because apparently, NULL doesn’t believe in teamwork.  

• Use CONCAT to make concatenation cleaner and to automatically treat NULLs like the empty shells they are. Fewer headaches, more functioning code.  

• Parameterize values with sp_executesql. It keeps your code secure, faster, and less likely to turn into a free‑for‑all SQL injection party.  

• Add some debug prints of your constructed SQL. It’s the developer equivalent of talking to yourself, slightly weird, but surprisingly effective when things stop making sense.

5. Debug Effectively  

• Print your dynamic command strings while developing, it’s the SQL equivalent of talking to yourself, but at least this version occasionally answers back.  

• If your dynamic statements are going get longer than a toddler’s bedtime story, bump up the text output limit in SQL Server Management Studio (Tools > Options > Query Results > Results to Text). Otherwise, you’ll get half a query and twice the confusion.

6. Object Naming and Injection Safety  

When injecting object names inside dynamic SQL, wrap them with QUOTENAME, because “trusting input” is not a security strategy.

• Always wrap dynamic object names with QUOTENAME to keep both syntax errors and unwelcome surprises out of your SQL.  

• Avoid injecting raw table or column names directly, it’s faster to validate them against an allow‑list than to explain later why production went down during peak usage.  

The example below shows how to manage object naming and user input in dynamic SQL the right way, efficient, secure, and refreshingly uneventful.

/*
  Example: Dynamic SQL with safe object naming and injection protection.
  - Uses QUOTENAME to safely delimit schema, table, and column names.
  - Prevents SQL injection via object names with QUOTENAME.
  - Uses sp_executesql with parameters for user inputs.
*/

DECLARE @SchemaName SYSNAME = 'dbo';
DECLARE @TableName SYSNAME = 'sysfiles';
DECLARE @ColumnName SYSNAME = 'name';
DECLARE @FilterValue NVARCHAR(50) = 'master';

DECLARE @Sql NVARCHAR(MAX);

-- Build dynamic SQL with safely quoted object names
SET @Sql = N'SELECT * FROM ' 
    + QUOTENAME(@SchemaName) + N'.' + QUOTENAME(@TableName) 
    + N' WHERE ' + QUOTENAME(@ColumnName) + N' = @Dept';

-- Execute with parameter to avoid injection on values
EXEC sp_executesql @Sql, N'@Dept NVARCHAR(50)', @Dept = @FilterValue;

-- Optional: Print SQL string for debugging
PRINT @Sql;



Remember:  

• QUOTENAME() wraps object names in delimiters ([]) to prevent injection and syntax errors caused by spaces, special characters, or reserved keywords.

• Never directly concatenate user input into object names without validation and quoting.

• Continue using parameterized queries (sp_executesql) to safeguard user-supplied data.

• Always explicitly specify schema names for clarity and security.

7. Handle Single Quotes Properly  

• If there’s one thing dynamic SQL loves, it’s breaking because of a single missing quote.  Even to this day this happens to be almost every time I write dynamic SQL.  

• Make sure to double up single quotes inside your SQL literals, yes, two of them. No, not sometimes. Always.  

• Print your command strings often while debugging; it’s the only way to spot those sneaky quoting errors before they ruin your day (again).  

The example below shows how to do it right, written by someone who learned this lesson the hard way, repeatedly.

/*
  Example: Handling single quotes dynamic SQL by doubling single quotes.
  - Uses REPLACE to escape single quotes by replacing each single quote with two.
  - Prevents syntax errors caused by unescaped single quotes.
  - Uses sp_executesql with parameters for safer execution when possible.
*/

-- Create O'mighty O'sql table if doesn't already exist
IF OBJECT_ID('O''mighty O''sql') IS NOT NULL DROP TABLE [O'mighty O'sql] ;
GO
CREATE TABLE [O'mighty O'sql] (id int);
GO


DECLARE @UserInput NVARCHAR(50) = 'O''mighty O''sql';  -- Input with single quotes

-- Unsafe dynamic SQL by direct concatenation (not recommended):
DECLARE @SqlUnsafe NVARCHAR(MAX);
SET @SqlUnsafe = 'SELECT * FROM sys.objects WHERE name = ''' 
    + REPLACE(@UserInput, '''', '''''') + '''';  -- Double single quotes to escape

PRINT 'Unsafe SQL: ' + @SqlUnsafe;
EXEC(@SqlUnsafe);

-- Better: Use sp_executesql with parameters to avoid manual escaping:
DECLARE @SqlSafe NVARCHAR(MAX) = 'SELECT * FROM sys.objects WHERE name = @ObjectName';
PRINT 'Safe SQL: ' + @SqlSafe;
EXEC sp_executesql @SqlSafe, N'@ObjectName NVARCHAR(50)', @ObjectName = @UserInput;

GO

-- Drop table O'mighty O'sql 
IF OBJECT_ID('O''mighty O''sql') IS NOT NULL DROP TABLE [O'mighty O'sql] ;

Remember:  

• When you’re dynamically concatenating strings that contain single quotes, use REPLACE(value, '''', '''''') to double them up. Yes, it looks ridiculous, and yes, it’s necessary, because SQL doesn’t share your sense of humor.  

• Better yet, use sp_executesql with parameters and skip the manual quote juggling altogether. It’s cleaner, safer, and saves you from explaining to your team why your code exploded over one punctuation mark.  

• Print out your SQL command as you go; it’s like holding up a mirror to your mistakes before they hit production.  

This approach keeps single quotes from wrecking your dynamic SQL and, more importantly, keeps you from accidentally inventing new injection vectors in the name of “quick testing.”

---

Summary & Conclusion

Dynamic SQL is a powerful tool that can be incredibly helpful, until it gives you headaches you didn’t ask for. Treat it with respect: comment generously, use parameters, quote your object names properly, and debug like your sanity depends on it (because it probably does). Most disasters you hear about with dynamic SQL probably happened because someone, likely yourself, ignored these rules. So code defensively, document liberally, and maybe keep a stress ball handy. 

Resources

---

Microsoft Article on sp_executesql

EXEC and sp_executesql – how are they different

Gotchas to Avoid for Better Dynamic SQL

Why sp_prepare Isn’t as “Good” as sp_executesql for Performance