Please note - development on v2 has stopped and all efforts are focused on the v3 improvements to use Pester v5 and improve performance.
You are welcome to help by picking something from the project https://github.com/orgs/dataplat/projects/2 or by contacting @SQLDBAWithABeard @jpomfret @ClaudioESSilva or @shaneis
dbachecks is a framework created by and for SQL Server pros who need to validate their environments. Basically, we all share similar checklists and mostly just the server names and RPO/RTO/etc change.
This open source module allows us to crowd-source our checklists using Pester tests. Such checks include:
- Backups are being performed
- Identity columns are not about to max out
- Servers have access to backup paths
- Database integrity checks are being performed and corruption does not exist
- Disk space is not about to run out
- All enabled jobs have succeeded
You can find a set of interactive PowerShell Notebooks which will introduce you to all of the core concepts in Robs GitHub. There is a set of .NET interactive Jupyter Notebooks
and a set of Jupyter Notebooks that will run in Azure Data Studio
Both will use a docker container to show you how dbachecks works.
There is a zip file containing the Notebooks here
Have questions about development? Please visit our Wiki. Anyone developing this module should visit that Wiki page (after fully reading this readme) for a brief overview.
| Development Branch Build - Unit testing Click Here | |
| Main Branch Build - Module version update and Code Signing Click Here | |
| Main Branch Release - Release to PowerShell Gallery Click Here |
Want to know how our CD process works? Read this blog post and see how the team manage it
- PowerShell 5 + is required.
- Automatic installation of the dependent modules will only be provided via the PowerShell Gallery.
When you install from the Gallery, it'll auto-install:
- dbatools
- PSFramework
You will also need to manually install the Pester module at version 4.10.0, this is due to inconsistencies between dbachecks and Pester v5. If you have Pester v5 installed it is recommended to remove this and use Pester 4.10.0 or force an import of 4.10.0 when running dbachecks
Install-Module Pester -SkipPublisherCheck -Force -RequiredVersion 4.10.0
Import-Module Pester -Force -RequiredVersion 4.10.0
When you import, it'll auto-import
- dbatools
- Pester
- PSFramework
If you have already installed the module and you update it, you may be required to update the Pester or the PSFramework modules before it will import. If you see a message like
Then you need to
Install-Module Pester -SkipPublisherCheck -Force -RequiredVersion 4.10.0
Import-Module Pester -Force -RequiredVersion 4.10.0
You may need to do the same thing for the PSFramework or dbatools modules also
dbachecks uses dbatools for most of it's data gathering so it supports SQL Versions from SQL 2000 to SQL vNext including SQL running on Linux. (dbachecks will not install on PowerShell Core yet so can not be run on a Linux client) Obviously some of the Services and disk space checks will not work against instances running on Linux as they are using gWindows API calls.
Checks are performed using Invoke-DbcCheck which is basically a wrapper for Invoke-Pester. This means that supported Invoke-Pester parameters work against Invoke-DbcCheck.
In this module, a "Check" is synonymous with a "Tag" in Pester. So you can Invoke-DbcCheck and specify a Check that you want to run. You can see a list of the available Checks with Get-DbcCheck.
Once you've decided on the Check(s) you want to run, it's time to ensure you have a list of servers to run the checks against.
Similar to the dbatools module, dbachecks accepts -SqlInstance and -ComputerName parameters.
Invoke-DbcCheck -SqlInstance $servers -Checks SuspectPage, LastBackup
If you have a simplified (single) environment, however, you can set a permanent list of servers. "Servers" include both SQL Server instances and Windows servers. Checks that access Windows Server (e.g. disk space checks) will utilize -ComputerName parameter. A pure SQL Server command(s) (such as the backup check) utilizes the -SqlInstance parameter.
# Set the servers you'll be working with
Set-DbcConfig -Name app.sqlinstance -Value sql2016, sql2017, sql2008, sql2008\express
Set-DbcConfig -Name app.computername -Value sql2016, sql2017, sql2008
# Look at the current configs
Get-DbcConfig
# Invoke a few tests
Invoke-DbcCheck -Checks SuspectPage, LastBackup
Additional Invoke-DbcCheck examples:
Invoke-DbcCheck -Check Backup -SqlInstance sql2016
Invoke-DbcCheck -Check RecoveryModel -SqlInstance sql2017, sqlcluster
$sqlinstance = Get-DbaRegisteredServer -SqlInstance sql2017 -Group Express
Invoke-DbcCheck -Check Backup -SqlInstance $sqlinstance
Invoke-DbcCheck -Check Storage -ComputerName server1, server2We tag each of our Checks using singular descriptions such as Backup, Database or Storage. You can see all the Pester related Tags using Get-DbcTagCollection or Get-DbcCheck.
Each Check generally has a few Tags but at least one Tag is unique. This allows us to essentially name a Check and using these Tags, you can either include (-Check) or Exclude (-ExcludeCheck) in your results. The Exclude will always take precedence.
For example, the Database Tag runs a number of Checks including Backup Checks. The command below will run all Database Checks except for the Backup Checks.
Invoke-DbcCheck -Check Database -ExcludeCheck Backup -SqlInstance sql2016 -SqlCredential (Get-Credential sqladmin)All valid Pester syntax is valid for dbachecks so if you'd like to know more, you can review their documentation.
Since this is just PowerShell and Pester, results can be exported then easily converted to pretty reports. We've provided two options: Power BI and SMTP mail.
We've also included a pre-built Power BI Desktop report! You can download Power BI Desktop from here or it is now offered via the Microsoft Store on Windows 10.
Note: We strongly recommend that you keep your PowerBI Desktop updated since we can add brand-new stuff that appears on the most recent releases.
To use the Power BI report, pipe the results of Invoke-DbcCheck to Update-DbcPowerBiDataSource (defaults to C:\Windows\temp\dbachecks), then launch the included dbachecks.pbix file using Start-DbcPowerBi. Once the Power BI report is open, just hit refresh.
# Run checks and export its JSON
Invoke-DbcCheck -SqlInstance sql2017 -Checks SuspectPage, LastBackup -Show Summary -PassThru | Update-DbcPowerBiDataSource
# Launch Power BI then hit refresh
Start-DbcPowerBi
The above report uses Update-DbcPowerBiDataSource's -Environment parameter.
# Run checks and export its JSON
Invoke-DbcCheck -SqlInstance $prod -Checks LastBackup -Show Summary -PassThru |
Update-DbcPowerBiDataSource -Environment Prod😍😍😍
We even included a command to make emailing the results easier!
$outputDirectory = (Get-DbcConfigValue -Name app.maildirectory)
$filename = $outputDirectory + '\file.xml'
Invoke-Dbccheck -OutputFile $fileName -OutputFormat NunitXML
$outputpath = $outputDirectory + "\index.html"
$reportunit = "ModulePath\bin\ReportUnit.exe"
& $reportunit $outputDirectory
$htmlbody = Get-Content -Path $outputpath -ErrorAction SilentlyContinue | Out-String
Send-MailMessage -To clemaire@dbatools.io -From nobody@dbachecks.io -SMTP smtp.ad.local -BodyAsHtml $htmlbody
If you'd like to test locally, check out PaperCut which is just a quick email viewer that happens to have a built-in SMTP server. It provides awesome, built-in functionality so you can send the reports!
The Check LastGoodCheckDb includes a test for data purity. You may be in an environment that can't support data purity. If this check needs to be skipped, you can do the following:
Get-DbcConfig *skip*
Set-DbcConfig -Name skip.dbcc.datapuritycheck -Value $trueNeed to skip a whole test? Just use the -ExcludeCheck which is auto-populated with both Check names and Pester Tags.
Set-DbcConfig persists the values. If you Set-DbcConfig -Name app.sqlcredential -Value (Get-Credential sa) it will set the SqlCredential for the whole module, but not your local console! So cool.
You can also manually change the SqlCredential or Credential by specifying it in Invoke-DbaCheck:
Invoke-DbaCheck -SqlInstance sql2017 -SqlCredential (Get-Credential sqladmin) -Check MaxMemoryYou can also modify the parameters of the actual command that's being executed:
Set-Variable -Name PSDefaultParameterValues -Value @{ 'Get-DbaDiskSpace:ExcludeDrive' = 'C:\' } -Scope Global
Invoke-DbcCheck -Check StorageIf you have super specialized checks to run, you can add a new repository, update the app.checkrepos config and this will make all of your tests available to Invoke-DbcCheck. From here, you can pipe to Send-DbcMailMessage, Update-DbcPowerBiDataSource or parse however you would parse Pester results.
So first, add your repository
Set-DbcConfig -Name app.checkrepos -Value C:\temp\checks -AppendThen add additional checks. We recommend using the development guidelines for dbachecks.
Great idea! Remember that this module requires PowerShell version 4.0, which doesn't always mesh with SQL Server's PowerShell Job Step. To run dbachecks, we recommend you use CmdExec. You can read more at dbatools.io/agent.
If you do choose to use the PowerShell step, don't forget to Set-Location somewhere outside of SQLSERVER:, otherwise, you'll get errors similar to this
This module has a number of dependencies which makes creating a GitHub-centric installer a bit of a pain. We suggest you use a machine with PowerShellGet installed and Save all the modules you need:
Save-Module -Name dbachecks, dbatools, PSFramework, Pester -Path C:\tempThen move them to somewhere in your $env:PSModulePath, perhaps Documents\WindowsPowerShell\Modules or C:\Program Files\WindowsPowerShell\Modules.
Read more about dbachecks from a number of our original contributors!
- Announcing dbachecks – Configurable PowerShell Validation For Your SQL Instances by Rob Sewell
- introducing dbachecks - a new module from the dbatools team! by Chrissy LeMaire
- install dbachecks by Chrissy LeMaire
- dbachecks commands by Chrissy LeMaire
- dbachecks – Using Power BI dashboards to analyse results by Cláudio Silva
- My wrapper for dbachecks by Tony Wilhelm
- Checking backups with dbachecks by Jess Pomfret
- dbachecks please! by Garry Bargsley
- dbachecks – Configuration Deep Dive by Rob Sewell
- Test Log Shipping with dbachecks by Sander Stad
- Checking your backup strategy with dbachecks by Joshua Corrick
- Enterprise-level reporting with dbachecks by Jason Squires
- Adding your own checks to dbachecks by Shane O'Neill
- dbachecks - A different approach for an in-progress and incremental validation by Cláudio Silva
- dbachecks - Improved Descriptions by Rob Sewell
- DBACHECKS – SQL SERVER COMPLIANCE TESTING WITH SIMPLE CONFIGURATION MANAGEMENT by Stuart Moore
- dbachecks – Which Configuration Item For Which Check ? by Rob Sewell *https://sqldbawithabeard.com/2018/04/08/checking-availability-groups-with-dbachecks/ by Rob Sewell
Know of any more blog posts about dbachecks? - Please add them here.
Nice work!
We welcome contributions to the project. You can fork the repository, make changes and create a Pull Request. Rob has written a guide here