From 53fca61b8405a81c1560deb9d950e86321b55fa8 Mon Sep 17 00:00:00 2001 From: Rob Sewell Date: Sat, 29 Sep 2018 16:29:25 +0100 Subject: [PATCH] creating the documentation --- RELEASE.md | 80 ++++++++++++++ builddocs.ps1 | 38 +++++++ docs/index.md | 271 ++++++++++++++++++++++++++++++++++++++++++++++ header-mkdocs.yml | 8 ++ mkdocs.yml | 21 ++++ 5 files changed, 418 insertions(+) create mode 100644 RELEASE.md create mode 100644 builddocs.ps1 create mode 100644 docs/index.md create mode 100644 header-mkdocs.yml create mode 100644 mkdocs.yml diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000..11cab51c --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,80 @@ +## Date 07/09/2018 +Updated dbatools required module to 0.9.410 +Renamed all dbatools commands to new naming convention +Fixed Bug with JSON file naming +Improved Server Checks to remove Red and improve speed for none contactable servers +Altered all server checks to use assertions and added pester Tests +Removed left over ogv entry + +##Latest + +## Date 05/09/2018 +New Check for 2 digit cut off thanks @CláudioESSilva +https://claudioessilva.eu/2018/09/04/dont-cutoff-yourself-when-dealing-with-dates-in-t-sql-did-you-know/ +Fixed bug with adding NoneContactable Instances to variable +Improved error handling for HADR checks + +## Date 28/08/2018 +Added MaxBehind to SupportedBuild Tests - Thank you @LowlyDBA +Ensured the Database paramter checks only the specified Databases - Thank you @jpomfret +Updated Set-DbcConifg to allow Append to append arrays to arrays closes #535 +Altered json filename creation to avoid max characters error +Altered PowerBi to display information correctly with filename changes + +## Date 24/08/2017 +Fixed Error with using Credential and stopped changing path when runnign checks from custom repos - Thank you @sammyxx + +## Date 23/08/2017 +Update to the help message for clusters by @LowlyDBA +Potential Breaking Change - Removed Tags from names of json files so that PowerBi will correctly show Environment names + +## Date 15/08/2018 +Fixed issue 521 ExcludeDatabase parameter doesn't work - THANK YOU @jpomfret +THANK YOU @jpomfret - Issue 509 -Database should only check databases listed and exclude all others +Further update to Update-DbcPowerBiDataSource to allow Environment as well as specify filename +Improved performance of the Server checks +Improved performance of the Instance checks +Improved performance of the Database checks +Improved performance of the ErrorLog checks +Removed Send-DbcSendMailMessage until it can be re-coded + +## Date 13/08/2018 +Fixed #504 by enabling FileName parameter on Update-PowerBiDataSouce +Added in new function to begin to reduce the number of calls to each instance +Reduced required Pester version to 4.3.1 +Further PowerShell V4 improvements + +## Date 06/08/2018 +Added New Check for tempdb data file sizes to be the same - Thank you @garethnewman #512 +Altered Services Check so that clustered instances start mode is checked correctly thank you @kylejdoyle #516 +Skip PowerPlan test if no connection thanks @cl #490 +Fixed bug with XESession and PSv4 thank you @kylejdoyle #517 +Error silently on failing Service check (thanks Rob ;-) ) +Fixed dbatools command names +Fixed PSv4 support for importing the module also + +## Date 31/07/2018 + +Added check for Database Exists - Thanks @sqldbawithbeard +Added excluded databases config to each Database Check and wrote Pester Test for that #506 +Added msdb to exclusion fro duplicate index #506 +Fixed offline install bug #484 + +## Date 30/07/2018 + +Updated Required Module versions - Thank you @cl +Updated Agent Checks to fail a test on no connection rather than throw all the PowerShell errors - Thanks @sqldbawithbeard +Updated HADR Checks for PS4 compatability Issue #513 + +## Date 28/06/2018 + +Don't check versions before 2008 for AdHocWorkloads Thank you John McCall @LowlyDBA +More Spelling! Thank you John McCall @LowlyDBA +Updated required version and dbatools error log command name Thank you Our Glorious Chrissy @cl + +## Date 30/05/2018 +New Release Notes command added +Spelling + +## Date 29/05/2012 + diff --git a/builddocs.ps1 b/builddocs.ps1 new file mode 100644 index 00000000..77c06933 --- /dev/null +++ b/builddocs.ps1 @@ -0,0 +1,38 @@ +$ProjectRoot = Get-Location +$ModuleName = 'SQLDiagAPI' +$BuildDate = Get-Date -uFormat '%Y-%m-%d' +$ReleaseNotes = "$ProjectRoot\RELEASE.md" +$ChangeLog = "$ProjectRoot\docs\ChangeLog.md" + + +#Build YAMLText starting with the header +$YMLtext = (Get-Content "$ProjectRoot\header-mkdocs.yml") -join "`n" +$YMLtext = "$YMLtext`n" + +$parameters = @{ + Path = $ReleaseNotes + ErrorAction = 'SilentlyContinue' +} +$ReleaseText = (Get-Content @parameters) -join "`n" +if ($ReleaseText) { + $ReleaseText | Set-Content "$ProjectRoot\docs\RELEASE.md" + $YMLText = "$YMLtext - Release Notes: RELEASE.md`n" +} +if ((Test-Path -Path $ChangeLog)) { + $YMLText = "$YMLtext - Change Log: ChangeLog.md`n" +} +$YMLText = "$YMLtext - Functions:`n" + +$Params = @{ + Module = 'SQLDiagAPI' + Force = $true + OutputFolder = "$ProjectRoot\docs\functions" + NoMetadata = $true +} +New-MarkdownHelp @Params | foreach-object { + $Function = $_.Name -replace '\.md', '' + $Part = " - {0}: functions/{1}" -f $Function, $_.Name + $YMLText = "{0}{1}`n" -f $YMLText, $Part + $Part +} +$YMLtext | Set-Content -Path "$ProjectRoot\mkdocs.yml" \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4ce9fc0f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,271 @@ +# dbachecks + + + +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 crowdsource our checklists using [Pester](https://github.com/Pester/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 + +Have questions about development? Please visit our [Wiki](https://github.com/sqlcollaborative/dbachecks/wiki). **Anyone developing this module** should visit that Wiki page (after fully reading this readme) for a brief overview. + +## Build Status + + + + + + + + + + + + + + + +
Development Branch Build - Unit testing Click Here
Master Branch Build - Module version update and Code Signing Click Here
Master Branch Release - Release to PowerShell Gallery Click Here
+ +Want to know how our CD process works? Read this [blog post](https://sqldbawithabeard.com/2018/05/01/version-update-code-signing-and-publishing-to-the-powershell-gallery-with-vsts/) and see how the team manage it + +## Prerequisites +### Client requirements +* PowerShell 4+ is required. +* Automatic installation of the dependent modules will only be provided via the [PowerShell Gallery](https://www.powershellgallery.com). + +When you install from the Gallery, it'll auto-install: + +* dbatools +* Pester +* PSFramework + +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 + +![error](https://user-images.githubusercontent.com/6729780/35032185-dfe988a2-fb5d-11e7-83e3-6a41a9c89b81.png) + +Then you need to + +```` +Install-Module Pester -SkipPublisherCheck -Force +Import-Module Pester -Force +```` + +You may need to do the same thing for the PSFramework or dbatools modules also + +### SQL requirements + +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 adn disk space checks will not work against instances running on Linux as they are usin gWindows API calls. + +## Getting started + +Checks are performed using `Invoke-DbcCheck` which is basically a wrapper for [Invoke-Pester](https://github.com/pester/Pester/wiki/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**. + +![image](https://user-images.githubusercontent.com/8278033/34329332-57f40a1c-e8fc-11e7-8526-178c415b09bf.png) + +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. + +### Making server lists + +Similar to the [dbatools](https://dbatools.io) 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. + +```powershell +# 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 +``` +#### What it looks like + +![image](https://user-images.githubusercontent.com/8278033/34315954-431d0b16-e78a-11e7-8f6d-c87b40ed90b2.png) + +#### Other ways to execute checks against specific servers + +Additional `Invoke-DbcCheck` examples: + +```powershell +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, server2 +``` + +## Check and ExcludeCheck + +We 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. + +```powershell +Invoke-DbcCheck -Check Database -ExcludeCheck Backup -SqlInstance sql2016 -SqlCredential (Get-Credential sqladmin) +``` + +All valid [Pester](https://github.com/Pester/Pester) syntax is valid for dbachecks so if you'd like to know more, you can review their documentation. + +## Reporting on the data + +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. + +### Power BI Visualizations! + +We've also included a pre-built Power BI Desktop report! You can download Power BI Desktop from [here](https://powerbi.microsoft.com/en-us/downloads/) or it is now offered via the [Microsoft Store on Windows 10](https://www.microsoft.com/store/productId/9NTXR16HNW1T). + +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**. + +```powershell +# 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 +``` + +![image](https://user-images.githubusercontent.com/19521315/36527050-640d6c0a-17a8-11e8-9781-0aab0a8f8d48.png) + +The above report uses `Update-DbcPowerBiDataSource`'s `-Environment` parameter. + +```powershell +# Run checks and export its JSON +Invoke-DbcCheck -SqlInstance $prod -Checks LastBackup -Show Summary -PassThru | +Update-DbcPowerBiDataSource -Enviornment Prod +``` + +😍😍😍 + +### Sending mail + +We even included a command to make emailing the results easier! + +```powershell +Invoke-DbcCheck -SqlInstance sql2017 -Checks SuspectPage, LastBackup -OutputFormat NUnitXml -PassThru | +Send-DbcMailMessage -To clemaire@dbatools.io -From nobody@dbachecks.io -SmtpServer smtp.ad.local +``` + +![image](https://user-images.githubusercontent.com/8278033/34316816-cc157d04-e79e-11e7-971d-1cfee90b2e11.png) + +If you'd like to test locally, check out [PaperCut](https://github.com/ChangemakerStudios/Papercut/releases) 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! + +## Advanced usage + +### Skipping some internal tests + +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: + +```powershell +Get-DbcConfig *skip* +Set-DbcConfig -Name skip.dbcc.datapuritycheck -Value $true +``` + +Need to skip a whole test? Just use the `-ExcludeCheck` which is auto-populated with both Check names and Pester Tags. + +### Setting a global SQL Credential + +`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`: + +```powershell +Invoke-DbaCheck -SqlInstance sql2017 -SqlCredential (Get-Credential sqladmin) -Check MaxMemory +``` + +### Manipulating the underlying commands + +You can also modify the parameters of the actual command that's being executed: + +```powershell +Set-Variable -Name PSDefaultParameterValues -Value @{ 'Get-DbaDiskSpace:ExcludeDrive' = 'C:\' } -Scope Global +Invoke-DbcCheck -Check Storage +``` + +## Can I run tests not included the module? + +If 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. + +![image](https://user-images.githubusercontent.com/8278033/34320729-aeacb72a-e800-11e7-8278-a83de46afcc6.png) + +So first, add your repository + +```powershell +Set-DbcConfig -Name app.checkrepos -Value C:\temp\checks -Append +``` + +Then add additional checks. We recommend using the [development guidelines for dbachecks](https://github.com/potatoqualitee/dbachecks/wiki). + +![image](https://user-images.githubusercontent.com/8278033/34320819-07fe939c-e802-11e7-8203-a82740cc8f19.png) + +## I'd like to run my checks in SQL Server Agent + +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](https://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 + +![image](https://user-images.githubusercontent.com/8771143/35379174-878505fc-01b5-11e8-8731-41be4daff815.png) + +## I don't have access to the PowerShell Gallery, how can I download 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](https://docs.microsoft.com/en-us/powershell/gallery/psget/get_psget_module) installed and Save all the modules you need: + +```powershell +Save-Module -Name dbachecks, dbatools, PSFramework, Pester -Path C:\temp +``` + +Then move them to somewhere in your `$env:PSModulePath`, perhaps **Documents\WindowsPowerShell\Modules** or **C:\Program Files\WindowsPowerShell\Modules**. + +## Read more + +Read more about dbachecks from a number of our original contributors! + +* [Announcing dbachecks – Configurable PowerShell Validation For Your SQL Instances by Rob Sewell](https://sqldbawithabeard.com/2018/02/22/announcing-dbachecks-configurable-powershell-validation-for-your-sql-instances/) +* [introducing dbachecks - a new module from the dbatools team! by Chrissy LeMaire](https://dbachecks.io/introducing) +* [install dbachecks by Chrissy LeMaire](https://dbachecks.io/install) +* [dbachecks commands by Chrissy LeMaire](https://dbachecks.io/commands) +* [dbachecks – Using Power BI dashboards to analyse results by Cláudio Silva](http://claudioessilva.eu/2018/02/22/dbachecks-using-power-bi-dashboards-to-analyse-results/) +* [My wrapper for dbachecks by Tony Wilhelm](https://v-roddba.blogspot.com/2018/02/wrapper-for-dbachecks.html) +* [Checking backups with dbachecks by Jess Promfret](http://jesspomfret.com/checking-backups-with-dbachecks/) +* [dbachecks please! by Garry Bargsley](http://blog.garrybargsley.com/dbachecks-please) +* [dbachecks – Configuration Deep Dive by Rob Sewell](https://sqldbawithabeard.com/2018/02/22/dbachecks-configuration-deep-dive/) +* [Test Log Shipping with dbachecks by Sander Stad](https://www.sqlstad.nl/powershell/test-log-shipping-with-dbachecks/) +* [Checking your backup strategy with dbachecks by Joshua Corrick](https://corrick.io/blog/checking-your-backup-strategy-with-dbachecks) +* [Enterprise-level reporting with dbachecks by Jason Squires](http://www.sqlnotnull.com/2018/02/20/enterprise-level-reporting-with-dbachecks-from-the-makers-of-dbatools) +* [Adding your own checks to dbachecks by Shane O'Neill](http://nocolumnname.blog/2018/02/22/adding-your-own-checks-to-dbachecks) +* [dbachecks - A different approach for an in-progress and incremental validation by Cláudio Silva](http://claudioessilva.eu/2018/02/22/dbachecks-a-different-approach-for-a-in-progress-and-incremental-validation/) +* [dbachecks - Improved Descriptions by Rob Sewell](https://sqldbawithabeard.com/2018/05/19/dbachecks-improved-descriptions/) +* [DBACHECKS – SQL SERVER COMPLIANCE TESTING WITH SIMPLE CONFIGURATION MANAGEMENT by Stuart Moore](https://stuart-moore.com/dbachecks-sql-server-compliance-testing-simple-configuration-management/) +* [dbachecks – Which Configuration Item For Which Check ? by Rob Sewell](https://sqldbawithabeard.com/2018/05/15/dbachecks-which-configuration-item-for-which-check/) +*[https://sqldbawithabeard.com/2018/04/08/checking-availability-groups-with-dbachecks/ by Rob Sewell](https://sqldbawithabeard.com/2018/04/08/checking-availability-groups-with-dbachecks/) + +Know of any more blog posts about dbachecks? - Please add them here. + +## Party + +Nice work! diff --git a/header-mkdocs.yml b/header-mkdocs.yml new file mode 100644 index 00000000..c337c0b7 --- /dev/null +++ b/header-mkdocs.yml @@ -0,0 +1,8 @@ +site_name: dbachecks +repo_url: https://github.com/sqlcollaborative/dbachecks +site_author: The Beard +edit_uri: edit/master/docs/ +theme: readthedocs +copyright: "dbachecks is licensed under the MIT license" +pages: + - Home: index.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..dd1bb9ba --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,21 @@ +site_name: dbachecks +repo_url: https://github.com/sqlcollaborative/dbachecks +site_author: The Beard +edit_uri: edit/master/docs/ +theme: readthedocs +copyright: "dbachecks is licensed under the MIT license" +pages: + - Home: index.md + - Functions: + - Get-SQLDiagAnalysis: functions/Get-SQLDiagAnalysis.md + - Get-SQLDiagAnalysisHistory: functions/Get-SQLDiagAnalysisHistory.md + - Get-SQLDiagDumpFile: functions/Get-SQLDiagDumpFile.md + - Get-SQLDiagFeature: functions/Get-SQLDiagFeature.md + - Get-SQLDiagFix: functions/Get-SQLDiagFix.md + - Get-SQLDiagLatestAnalysis: functions/Get-SQLDiagLatestAnalysis.md + - Get-SQLDiagLatestCU: functions/Get-SQLDiagLatestCU.md + - Get-SQLDiagProduct: functions/Get-SQLDiagProduct.md + - Get-SQLDiagRecommendations: functions/Get-SQLDiagRecommendations.md + - Get-SQLDiagSupportedRegions: functions/Get-SQLDiagSupportedRegions.md + - Invoke-SQLDiagDumpAnalysis: functions/Invoke-SQLDiagDumpAnalysis.md +