Find-DbaBackup

Synopsis

Searches filesystem directories for SQL Server backup files based on age and extension criteria.

Description

Recursively scans specified directories to locate SQL Server backup files (.bak, .trn, .dif, etc.) older than your defined retention period. Returns file objects that can be piped to removal commands or processed for cleanup workflows.

This function replaces manual directory searches when managing backup retention policies. You can filter results to only include files that have been archived (using the Archive bit check) to ensure backups are safely stored elsewhere before cleanup.

Commonly used in automated maintenance scripts to identify backup files ready for deletion based on your organization’s retention requirements.

Syntax

Find-DbaBackup
    [-Path] <String>
    [-BackupFileExtension] <String>
    [-RetentionPeriod] <String>
    [-CheckArchiveBit]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Find-DbaBackup -Path 'C:\MSSQL\SQL Backup\' -BackupFileExtension trn -RetentionPeriod 48h

Searches for all trn files in C:\MSSQL\SQL Backup\ and all subdirectories that are more than 48 hours old will be included.

Example: 2

PS C:\> Find-DbaBackup -Path 'C:\MSSQL\Backup\' -BackupFileExtension bak -RetentionPeriod 7d -CheckArchiveBit

Searches for all bak files in C:\MSSQL\Backup\ and all subdirectories that are more than 7 days old will be included, but only if the files have been backed up to another location as verified by
checking the Archive bit.

Example: 3

PS C:\> Find-DbaBackup -Path '\\SQL2014\Backup\' -BackupFileExtension bak -RetentionPeriod 24h | Remove-Item -Verbose

Searches for all bak files in \SQL2014\Backup\ and all subdirectories that are more than 24 hours old and deletes only those files with verbose message.

Required Parameters

-Path

Specifies the root directory path to recursively search for backup files. Searches all subdirectories within this path.
Use this to target specific backup locations like dedicated backup drives or network shares where your SQL Server backups are stored.

-BackupFileExtension

Specifies the file extension to search for without the period (e.g., ‘bak’, ’trn’, ‘dif’, ’log’).
Use ‘bak’ for full backups, ’trn’ or ’log’ for transaction log backups, or ‘dif’ for differential backups depending on which backup type you need to manage.

-RetentionPeriod

Specifies how old backup files must be before they’re included in results, using format like ‘7d’ or ‘48h’.
Files older than this period will be returned, making this essential for backup cleanup operations based on your retention policy.
Valid units: h (hours), d (days), w (weeks), m (months). Examples: ‘48h’, ‘7d’, ‘4w’, ‘1m’.

Optional Parameters

-CheckArchiveBit

Only includes backup files that have been archived to another location (Archive bit is not set).
Use this safety feature to ensure backups have been copied to tape, cloud storage, or other backup systems before cleanup to prevent accidental data loss.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.