--- title: "Get-DbaBackupInformation" description: "Scans backup files and reads their headers to create structured backup history objects for restore operations" url: "https://dbatools.io/Get-DbaBackupInformation/" availability: "Windows, Linux, macOS" tags: ["DisasterRecovery", "Backup", "Restore"] author: "Chrissy LeMaire (@cl) | Stuart Moore (@napalmgram)" source: "https://github.com/dataplat/dbatools/blob/master/public/Get-DbaBackupInformation.ps1" last_updated: "2024-01-01" --- # Get-DbaBackupInformation ## Synopsis Scans backup files and reads their headers to create structured backup history objects for restore operations ## Description Reads the headers of SQL Server backup files to extract metadata and creates BackupHistory objects compatible with Restore-DbaDatabase. This eliminates the need to manually track backup chains and file locations when planning database restores. The function identifies valid SQL Server backup files from a given path, reads their headers using the SQL Server instance, and organizes them into backup sets. It handles full, differential, and log backups, automatically determining backup types, LSN chains, and file dependencies. By default, the function uses xp_dirtree to scan remote paths accessible to the SQL Server instance. This means paths must be accessible from the SQL Server service account. The -NoXpDirTree switch allows scanning local files instead. Special support is included for Ola Hallengren maintenance solution backup folder structures, which can significantly speed up scanning of organized backup directories. ## Syntax ```powershell Get-DbaBackupInformation -Path -SqlInstance [-SqlCredential ] [-DatabaseName ] [-SourceInstance ] [-NoXpDirTree] [-NoXpDirRecurse] [-DirectoryRecurse] [-EnableException] [-MaintenanceSolution] [-IgnoreLogBackup] [-IgnoreDiffBackup] [-ExportPath ] [-StorageCredential ] [-Anonymise] [-NoClobber] [-PassThru] [] Get-DbaBackupInformation -Path [-DatabaseName ] [-SourceInstance ] [-EnableException] [-MaintenanceSolution] [-IgnoreLogBackup] [-IgnoreDiffBackup] [-ExportPath ] [-StorageCredential ] [-Import] [-Anonymise] [-NoClobber] [-PassThru] [] ``` ## Examples ### Example 1: Will use the Server1 instance to recursively read all backup files under c:\backups, and return a dbatools... ```powershell PS C:\> Get-DbaBackupInformation -SqlInstance Server1 -Path c:\backups\ -DirectoryRecurse ``` Will use the Server1 instance to recursively read all backup files under c:\backups, and return a dbatools BackupHistory object ### Example 2: This example creates backup history output from server1 and copies the file to the remote machine in order to... ```powershell PS C:\> Get-DbaBackupInformation -SqlInstance Server1 -Path c:\backups\ -DirectoryRecurse -ExportPath c:\store\BackupHistory.xml PS C:\> robocopy c:\store\ \\remoteMachine\C$\store\ BackupHistory.xml PS C:\> Get-DbaBackupInformation -Import -Path c:\store\BackupHistory.xml | Restore-DbaDatabase -SqlInstance Server2 -TrustDbBackupHistory ``` This example creates backup history output from server1 and copies the file to the remote machine in order to preserve backup history. It is then used to restore the databases onto server2. ### Example 3: -TrustDbBackupHistory In this example we gather backup information, export it to an xml file, and then pass... ```powershell PS C:\> Get-DbaBackupInformation -SqlInstance Server1 -Path c:\backups\ -DirectoryRecurse -ExportPath C:\store\BackupHistory.xml -PassThru | Restore-DbaDatabase -SqlInstance Server2 ``` -TrustDbBackupHistory In this example we gather backup information, export it to an xml file, and then pass it on through to Restore-DbaDatabase. This allows us to repeat the restore without having to scan all the backup files again ### Example 4: -ExportPath C:\backupHistory.xml This lets you keep a record of all backup history from the last month on... ```powershell PS C:\> Get-ChildItem c:\backups\ -recurse -files | Where-Object {$_.extension -in ('.bak','.trn') -and $_.LastWriteTime -gt (get-date).AddMonths(-1)} | Get-DbaBackupInformation -SqlInstance Server1 ``` -ExportPath C:\backupHistory.xml This lets you keep a record of all backup history from the last month on hand to speed up refreshes ### Example 5: Scan the unc folder \\network\backups with Server1, and then scan the C:\backups folder on Server2 not using... ```powershell PS C:\> $Backups = Get-DbaBackupInformation -SqlInstance Server1 -Path \\network\backups PS C:\> $Backups += Get-DbaBackupInformation -SqlInstance Server2 -NoXpDirTree -Path c:\backups ``` Scan the unc folder \\network\backups with Server1, and then scan the C:\backups folder on Server2 not using xp_dirtree, adding the results to the first set. ### Example 6: When MaintenanceSolution is indicated we know we are dealing with the output from Ola Hallengren backup... ```powershell PS C:\> $Backups = Get-DbaBackupInformation -SqlInstance Server1 -Path \\network\backups -MaintenanceSolution ``` When MaintenanceSolution is indicated we know we are dealing with the output from Ola Hallengren backup scripts. So we make sure that a FULL folder exists in the first level of Path, if not we shortcut scanning all the files as we have nothing to work with ### Example 7: As we know we are dealing with an Ola Hallengren style backup folder from the MaintenanceSolution switch... ```powershell PS C:\> $Backups = Get-DbaBackupInformation -SqlInstance Server1 -Path \\network\backups -MaintenanceSolution -IgnoreLogBackup ``` As we know we are dealing with an Ola Hallengren style backup folder from the MaintenanceSolution switch, when IgnoreLogBackup is also included we can ignore the LOG folder to skip any scanning of log backups. Note this also means they WON'T be restored ### Example 8: Gets backup information from an S3-compatible object storage location ```powershell PS C:\> $Backups = Get-DbaBackupInformation -SqlInstance sql2022 -Path s3://s3.us-west-2.amazonaws.com/mybucket/backups/mydb.bak -StorageCredential MyS3Credential ``` Gets backup information from an S3-compatible object storage location. Requires SQL Server 2022 or higher. The credential must be configured with Identity = 'S3 Access Key' and Secret containing the access key and secret key. ### Required Parameters ##### -Path Path to SQL Server backup files. Paths passed in as strings will be scanned using the desired method, default is a non recursive folder scan Accepts multiple paths separated by ',' Or it can consist of FileInfo objects, such as the output of Get-ChildItem or Get-Item. This allows you to work with your own file structures as needed | Property | Value | | --- | --- | | Alias | | | Required | True | | Pipeline | true (ByValue) | | Default Value | | ##### -SqlInstance The SQL Server instance to be used to read the headers of the backup files | Property | Value | | --- | --- | | Alias | | | Required | True | | Pipeline | false | | Default Value | | ### Optional Parameters ##### -SqlCredential Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential). Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported. For MFA support, please use Connect-DbaInstance. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | | ##### -DatabaseName An array of Database Names to filter by. If empty all databases are returned. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | | ##### -SourceInstance If provided only backup originating from this destination will be returned. This SQL instance will not be connected to or involved in this work | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | | ##### -NoXpDirTree If specified, this switch will cause the files to be parsed as local files to the SQL Server Instance provided. Errors may be observed when the SQL Server Instance cannot access the files being parsed. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -NoXpDirRecurse If specified, this switch changes xp_dirtree behavior to not recurse the folder structure. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -DirectoryRecurse If specified the provided path/directory will be traversed (only applies if not using XpDirTree) | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -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. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -MaintenanceSolution This switch tells the function that the folder is the root of a Ola Hallengren backup folder | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -IgnoreLogBackup This switch only works with the MaintenanceSolution switch. With an Ola Hallengren style backup we can be sure that the LOG folder contains only log backups and skip it. For all other scenarios we need to read the file headers to be sure. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -IgnoreDiffBackup This switch only works with the MaintenanceSolution switch. With an Ola Hallengren style backup we can be sure that the DIFF folder contains only differential backups and skip it. For all other scenarios we need to read the file headers to be sure. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -ExportPath If specified the output will export via CliXml format to the specified file. This allows you to store the backup history object for later usage, or move it between computers | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | | ##### -StorageCredential The name of the SQL Server credential to be used if restoring from cloud storage (Azure Blob Storage or S3-compatible object storage). For Azure, this is typically a credential with access to the storage account. For S3, this should be a credential created with Identity 'S3 Access Key' matching the S3 URL path. | Property | Value | | --- | --- | | Alias | AzureCredential,S3Credential | | Required | False | | Pipeline | false | | Default Value | | ##### -Import When specified along with a path the command will import a previously exported BackupHistory object from an xml file. | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -Anonymise If specified we will output the results with ComputerName, InstanceName, Database, UserName, Paths, and Logical and Physical Names hashed out This options is mainly for use if we need you to submit details for fault finding to the dbatools team | Property | Value | | --- | --- | | Alias | Anonymize | | Required | False | | Pipeline | false | | Default Value | False | ##### -NoClobber If specified will stop Export from overwriting an existing file, the default is to overwrite | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ##### -PassThru When data is exported the cmdlet will return no other output, this switch means it will also return the normal output which can be then piped into another command | Property | Value | | --- | --- | | Alias | | | Required | False | | Pipeline | false | | Default Value | False | ## Outputs **Dataplat.Dbatools.Database.BackupHistory** Returns one BackupHistory object per backup set (group of files from the same backup operation). This object contains all necessary information to restore databases using Restore-DbaDatabase and supports being piped directly into that command. **The object includes the following properties:** - ComputerName: The computer name where the backup originated from (SQL Server host) - InstanceName: The SQL Server instance name where the backup was taken - SqlInstance: The full SQL Server instance name (ComputerName\InstanceName) - Database: The name of the database that was backed up - UserName: The Windows/SQL login that performed the backup - Start: DateTime of when the backup started - End: DateTime of when the backup finished - Duration: TimeSpan representing the duration of the backup operation - Type: String indicating the backup type (Full, Differential, or Log) - Path: String array of file paths containing the backup files - FullName: Array of backup file paths (same as Path) - FileList: Array of PSCustomObjects containing backup file details with properties: Type (MDF/LDF/NDF), LogicalName, PhysicalName, Size - TotalSize: Total size of the backup in bytes - CompressedBackupSize: Size of the compressed backup in bytes - BackupSetId: GUID uniquely identifying this backup set - Position: Position of the backup within the device - DeviceType: The type of backup device (typically 'Disk') - FirstLsn: BigInt representing the first log sequence number in the backup - DatabaseBackupLsn: BigInt representing the database backup LSN for log backups - CheckpointLSN: BigInt representing the checkpoint LSN - LastLsn: BigInt representing the last log sequence number in the backup - SoftwareVersionMajor: Major version of SQL Server that created the backup - RecoveryModel: The recovery model of the database (Simple, Full, or BulkLogged) - IsCopyOnly: Boolean indicating if this is a copy-only backup When -Anonymise is specified, the following properties are hashed: ComputerName, InstanceName, SqlInstance, Database, UserName, Path, FullName, and file logical/physical names in FileList. When -Import is specified, the BackupHistory object is deserialized from the exported CliXml file, preserving all properties for later use with Restore-DbaDatabase. --- Part of [dbatools](https://dbatools.io/), a free and open source PowerShell module for SQL Server administration. Full command index: https://dbatools.io/commands/