Test-DbaBackupInformation

Want to see the source code for this command? Check out Test-DbaBackupInformation on GitHub.
Want to see the Bill Of Health for this command? Check out Test-DbaBackupInformation.

Synopsis

Validates backup history objects to ensure successful database restoration

Description

Performs comprehensive pre-restore validation on backup history objects to prevent restore failures before they occur. Input is typically from Format-DbaBackupInformation and gets parsed to verify restore readiness.

This function runs critical validation tests including LSN chain integrity for transaction log backups, backup file accessibility by the SQL Server service account, database existence conflicts, and file path availability. It also creates necessary target directories and prevents file conflicts with existing databases.

Use this before running Restore-DbaDatabase to catch configuration issues early, saving time during maintenance windows or disaster recovery scenarios. Validated backup sets are marked with IsVerified = $True so you can easily filter successful candidates for restoration.

Tests performed include:

• Checking unbroken LSN chain for transaction log backups
• Verifying target database doesn't exist unless WithReplace is specified
• Ensuring backup files exist and are accessible by SQL Server service account
• Validating no file conflicts with existing databases
• Creating required target directories for database files
• Confirming backup files can be read from the specified locations

Syntax

Test-DbaBackupInformation
    [-BackupHistory] <Object[]>
    [[-SqlInstance] <DbaInstanceParameter>]
    [[-SqlCredential] <PSCredential>]
    [-WithReplace]
    [-Continue]
    [-VerifyOnly]
    [-OutputScriptOnly]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> $BackupHistory | Test-DbaBackupInformation -SqlInstance MyInstance
PS C:\> $PassedDbs = $BackupHistory | Where-Object {$_.IsVerified -eq $True}
PS C:\> $FailedDbs = $BackupHistory | Where-Object {$_.IsVerified -ne $True}

Pass in a BackupHistory object to be tested against MyInstance.
Those records that pass are marked as verified. We can then use the IsVerified property to divide the failures and successes

Required Parameters

-BackupHistory

Backup history objects containing restore chain information, typically generated by Format-DbaBackupInformation. Each object represents a backup file with metadata needed for validation including
database name, backup type, LSN values, and file paths.
Pass the output from Format-DbaBackupInformation to validate the entire restore sequence before attempting restoration.

Optional Parameters

-SqlInstance

The Sql Server instance that wil be performing the restore

-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.

-WithReplace

Allows restoration over an existing database with the same name. Without this switch, validation fails if the target database already exists on the destination instance.
Use this when performing disaster recovery or refresh scenarios where you need to replace the current database with backup data.

-Continue

Indicates this is a continuation of an existing restore operation, typically used when applying additional transaction log backups. Skips LSN chain validation and allows restoration to databases that
already exist in RESTORING state.
Use this when performing point-in-time recovery scenarios where you're applying additional log backups after an initial restore.

-VerifyOnly

Performs limited validation focusing only on backup file accessibility and readability. Skips database existence checks, file path conflicts, and directory creation since no actual restore will occur.
Use this when you only need to verify that backup files are valid and accessible without testing restore feasibility to the target instance.

-OutputScriptOnly

Prevents automatic creation of missing target directories during validation. Missing paths generate warnings instead of being created automatically.
Use this for testing restore scenarios without making changes to the file system, or when you need to verify permissions before allowing directory creation.

-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.

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

-Confirm

Prompts you for confirmation before running the cmdlet.