As you may have noticed, we release a 0.9.x update with bug fixes and new features almost daily, so why haven’t we released 1.0 yet?

Shifting from “a bag of functions” to a proper module

We love new functionality, of course, but we must take a step back from new development and consolidate what we have in a properly usable module.

Most of the contributors are damn good SQL Server Pros, a few are damn good PowerShell programmers, with the majority of “casual” developers being able to successfully publish a new function in less than a week time. But what we aren’t so good at is advertising our needs. We recently updated our contributing.md to be more on par with the latest months of developing. Stay tuned there, as the few TODOs left are coming, but the path is mostly set.

We need your help

We’re looking for contributors to help us finally reach version 1.0. Currently, we are on par with Gmail’s beta schedule: a whopping 4 years. But, we’re almost there and need your help finalizing our changes. If you’re interested in helping us bring 1.0 alive, we identified four areas with 5 primary contacts on the SQL Server Community Slack:

• Standardize param names (@wsmelton)
• Create tests for existing functions (@cl and @niphlod)
• Review existing function documentation (@alevyinroc or @gbargsley)
• Prepare for 1.0 with “code style” (Bill of Health, more on that later)

As you can see, a few of us are the main reference (on GitHub and Slack, mostly) for each area.

Bill of Health

As dbatools is full of sooo many features, it’s hard to tackle everything in one sweep. That’s why we made the Bill of Health available. That’s for you, and us, to track progress towards 1.0. It includes every single activity that will bring us closer to 1.0.

Data will be refreshed once or twice a week (you can see the trend on top with the details), giving everybody a good understanding on what’s the pace of development. For details on each column, click on the Legend details, you’ll be able to see what they mean.

Basically, we gave each function a scorecard, composed by checks that need to be tackled before 1.0.

Becoming a core developer

Some of the checks are “reserved for core-devs”, but that doesn’t mean you shouldn’t tackle those, it’s just you need to read on how we want the code to look like (we’ll eventually group everything in a more consolidated guide, ranging from the simpler to the “most complex”):

• do and do not
• Style Guide
• The Messaging System
• Sign-offs

It may scare PowerShell newbies, but trust us, to get the gist of it and be a successful “core-dev”, all you need is one week of coding. Most of us learned from Slack and Pull Request Code reviews. Sqlcollaborative is a wonderful place to learn coding in PowerShell! Checks for core-devs, despite being numerous, are a minority of the total.

Getting started

The most important things you can fix even without being a skilled developer: ScriptAnalyzer and Coverage. ScriptAnalyzer checks are the de-facto standard for any Powershell module and some are really, really easy to fix.

Coverage is a “higher level” metric: it tells you how much code is tested. It builds up on having tests written. We can’t (and won’t) stress enough on this point: if it’s tested, tests describe the way the function behaves, so the more coverage a function has, the more stable it is. This means you can build up your scripts  being sure there won’t be regressions (i.e. the code that “worked before” continues to work as expected).

Having a strong suite of tests also help the casual developer contributing code, being sure it doesn’t break existing functionality. It’s only a recommendation, but I feel like most of the “devs” should spend most of their time writing tests, because it’s the single best wealth indicator for any module.

For dbatools in particular: if you factor all the things dbatools supports (think PS versions times SQL releases times editions times Azure/cloud envs times x86/x64 times remote/local times functions times … ).

We’ve made it easy

You can copy and paste from our templates for a starting point, or dive right in to an existing tests.
Improving existing tests is an easy first step to “dip your toes” into coverage.

Want to help?

Right now there are more than 500 tasks ready to be tackled by everyone and more than 1300 for intermediate developers. To make sure everyone doesn’t jump on the same activity, you’re invited to see if there’s an issue opened on GitHub by someone else. If nothing pops up, open an “issue” , stating that you want to work the issue.

You can then issue a PR, there will be a swift review of the changes, and the code will be committed. A few hundred PR’s later (hopefully it’ll take just three or four by yourself), 1.0 will be shipped. And just wait to see what we have in mind for 2.0!

Got any questions? Hit me up on Slack. I’m @niphlod.

Ciao!
Simone

defining code coverage

Coupled with tests, code coverage is a metric that measures how much of the code is tested.

This is helpful to realize the test written is really covering for all the “features” of the code. A function with a test is a good thing. A function with a test that covers the 10% of the lines definitely helps, but tells you that a lot of the code involved may not be failproof.

While reaching 100% is not entirely possible due to Powershell limitations, it should be the goal for everyone. The more code coverage we reach:

• the more stable the module.
• the more “situations” are being checked and handled correctly
• the more tests will be complete, documenting what to expect from the function
• the more documentation about how a function needs to behave, the more users can fiddle with the code and add features being sure they don’t break anything in the process

We run a suite of tests at each commit via appveyor. The service we chose for code coverage is codecov. We chose them mostly due to the fact that their support is great and we needed their exclusive feature of “merge report” because we run different test suites for each build (even some C# code). Also, its interface is as good as a code coverage report can be, you can see the full source code and line-by-line coverage.

dbatools coverage

For public consumption, our development branch shows the most current coverage report for the whole project.

Now that the project is open about coverage metrics, you can contribute to the project writing more complete tests for all functions which are not 100% covered.

Let’s see a practical example.

A few days ago, on 2017-11-13, the development branch showed Get-DbaDbRecoveryModel.ps1 with a 90% coverage. Codecov’s urls are prettier but for the sake of this blogpost, which must point to specific commits, they’ll be lengthy and ugly.

Clicking on the function itself, you can see that only one line is specifically not covered

Line 87 basically is about the possibility to specify a specific recovery model as a filter to retrieve only matching databases.

If you run Get-Help Get-DbaDbRecoveryModel you’ll see this parameter

-RecoveryModel <String[]>
        Filters the output based on Recovery Model. Valid options are Simple, Full and BulkLogged
        Details about the recovery models can be found here:
        https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/recovery-models-sql-server

If you inspect the relevant test you’ll see there is nothing relative to that specific parameter.

Unfortunately, this means that if someone makes a modification to the function in the future, there won’t be any assurance that parameter continues to work as expected. We want to extend that test to include that too, so that the behaviour will always be the same.

giving more coverage

First, we need to create a database to test against the new case. Remembering that dbatoolsci_ is the default prefix for any resource created, let’s go with dbatoolsci_getrecoverymodel.

Cannibalizing a recurrent pattern seen in most tests, let’s add a new Context with a BeforeAll and an AfterAll stanzas to keep everything clean

Context "RecoveryModel parameter works" {
    BeforeAll {
        $server = Connect-DbaInstance -SqlInstance $script:instance2
        $dbname = "dbatoolsci_getrecoverymodel"
        Get-DbaDatabase -SqlInstance $server -Database $dbname | Remove-DbaDatabase -Confirm:$false
        $server.Query("CREATE DATABASE $dbname; ALTER DATABASE $dbname SET RECOVERY BULK_LOGGED WITH NO_WAIT;")
    }
    AfterAll {
        Get-DbaDatabase -SqlInstance $script:instance2 -Database $dbname | Remove-DbaDatabase -Confirm:$false
    }
}

Summing up, BeforeAll runs before ANY test within the upper-level stanza (in our case, the brand new Context), while AfterAll runs after, no matter the results (keeping things clean is a priority, so cleanup needs to run no matter what)

You’ll see the BeforeAll checks and removes any preexisting dbatoolsci_getrecoverymodel database, it then proceeds to create a new one with BULK_LOGGED. The AfterAll instead just removes the database we created. Then, we create the real test case:

It "gets the newly created database with the correct recovery model" {
    $results = Get-DbaDbRecoveryModel -SqlInstance $script:instance2 -Database $dbname
    $results.RecoveryModel -eq 'BulkLogged' | Should Be $true
}
It "honors the RecoveryModel parameter filter" {
    $results = Get-DbaDbRecoveryModel -SqlInstance $script:instance2 -RecoveryModel BulkLogged
    $results.Name -contains $dbname | Should Be $true
}

Now, let’s run the test locally, before submitting our changes. Create a C:\Temp\constants.ps1 or a .\tests\local.constants.ps1 that points to a live instance (in my case, the simplest of them all, localhost, results in this)

PS C:\dbatools-dev\tests> get-content .\constants.local.ps1
$script:instance1 = "localhost"
$script:instance2 = "localhost"
$script:instance1_detailed = "localhost,1433"
$script:appveyorlabrepo = "C:\github\appveyor-lab"
$instances = @($script:instance1, $script:instance2)
$ssisserver = "localhost"

Then, let’s launch the test

.\manual.pester.ps1 -path .\Get-DbaDbRecoveryModel.Tests.ps1 -TestIntegration

manual test run

merging to the dbatools repository

Now that we’ve confirmed that everything checks out, let’s create the pull request (PR).

First, we open a proper feature branch spawned from development

git checkout development
git checkout -b tests/Get-DbaRecoveryModel

add the relevant commits, then push the new branch

git push origin tests/Get-DbaRecoveryModel

wait a few seconds, go on github and create the PR

open a PR

change the base branch to development

change base branch

Once you filled out the details, you’ll have written something like this PR

Now, we just wait for the build to complete (impatient ones, watch appveyor’s dbatools “homepage” to monitor the status in real-time)

inspecting the results

Once the build has done, the list of recent opened PRs on codecov is at dbatools.io/coverage

If you inspect the one I created with this blogpost, which is #2646 , when you browse to the functions folder to see what happened with the coverage of Get-DbaRecoveryModel.ps1 … voilà

coverage increase

You can click further to see the details: you can see that the line which wasn’t covered is now green.

coverage increase line by line

Enjoyed this post? Come join the Pester-lovers on Slack’s #dbatools-pester to improve current tests!

Ciao!
Simone

the problem

Even the accidental DBA has to manage those pesky SQL Server Updates. Be it a bug fix, a security fix, a “new features” release, well… it needs to be installed.

• Put auditor in the mix: what build are you on ?
• Put your bosses’ boss in the mix: is the farm still officially supported by MS ?
• Put a developer in the mix: do we have that bug fixed, or that shiny new feature ?
• Put every DBA in the mix: we manage a fleet of SQL Servers and we want them to be updated regularly, with all of the versions on par of what it has been carefully tested on a non-production instance.

A quick search on google sends you – probably – to the most famous “build list” : sqlserverbuilds.blogspot.com
If you’re managing other MS product, you’d have this bookmarked already : buildnumbers.wordpress.com

If you’re subscribed to sqlservercentral (and you haven’t missed the post), you know about  sqlbuilds.ekelmans.com
If you follow Brent Ozar, you’ll know about sqlserverupdates.com
If you’re a technet addict, you’ll end up on technet.microsoft.com/library/ff803383

If someone comes up with “are you still on an officially supported version?” question, you’ll go on to search support.microsoft.com/lifecycle/search?alpha=sql+server.

And I’m totally sure I’m missing a few.

All of the above sites/lists are maintained by a different set of people (kudos to everyone), who helped DBAs, but all for different “angles”; every time you need a complete set of information, you need to go on more than one of those lists. And every time you need to get what version your instance is, well, you need to go fetch it.

the solutions

Enter the JSON-based dbatools commmand, Get-DbaBuildReference, and accompanying build website! Back in March, dbatools released a shiny new command, which will save you a lot of time in the “inventory” part of the deal.

the command

You get back on a jiffy:
– the Build
– the Major Release
– the Service Pack
– the Cumulative Update
– the KB related to that version
– when the support for that version ends
– if all of the above are matching a verified build
– if a warning is shown, you passed a bad build or the JSON must be updated

How can it do that? We needed to compose yet another source of information, coming from all of the information we could get our hands on.

It’s been a crafty work, but we just couldn’t fetch that info programmatically while being sure it was correct (or speedy). If you dabble in Powershell, you can execute the following and note an -Update switch.

Get-Help Get-DbaBuildReference

If you are more curious , you can check out the source.

You’ll see that information comes from a json file, which is shipped with the module, and that the -Update switch fetches a publicly available json file from https://sqlcollaborative.github.io/assets/dbatools-buildref-index.json.

omg the website

Our PowerShell command is easy to use but some just won’t dabble in Powershell. For everyone’s delight (hopefully), we crafted a page that builds a nice table containing all the build information, and it just does that based on that json file. So the same JSON file that powers Get-DbaBuildReference is being used to power this super easy to use site.

Hell, you can even fetch the source and host it yourself.

Need the info? Bookmark dbatools.io/builds, hit it, enter your build number in the search box and have all the info back. I’m not a fast clicker and had this done in less than 2 seconds.

Are you a spreadsheet fan? Presto! Press on “Copy” or “Excel” and lookup (or VLOOKUP) all the way.

open source means even faster updates

The website, the command and the json are all publicly available and editable. The website is hosted on gh-pages, and dbatools is on GitHub.

Moreover, dbatools welcome any type of contributors, even casual ones (there’s more than 900 people in Slack). This means that anyone, even drive-by contributors, can help keep the build reference updated. If you know of a missing build, you can hit us up on Slack, Twitter, open a GitHub issue, send a mail, send pigeons… The index will be updated, and everyone will benefit.

Join us, help every other person tracking builds effectively!

Ciao!
Simone