Summary: SQL Server MVP, Kendal Van ***, talks about using Windows PowerShell to discover, diagnose, and document all your computers running SQL Server.
Microsoft Scripting Guy, Ed Wilson, is here. Kendal Van *** is with us today to wrap up SQL Server Week.
Kendal Van *** is a practiced IT professional with over a decade of experience in SQL Server development and administration. Kendal is currently a principal consultant with UpSearch SQL, where he helps companies keep their SQL Servers running in high gear. Kendal is also a Microsoft MVP for SQL Server and president of the PASS chapter MagicPASS in Orlando, FL.
Company website: UpSearch
Blog: http://www.kendalvandyke.com/
Twitter: @SQLDBA
And now, here’s Kendal…
Documentation is the bane of every DBA's existence. We all know we should do it but it's time consuming; by the time you're finally done, it's probably out of date. Throw in the new servers you just found out about last week and keeping documentation up-to-date can turn into a full time job. And with everything we have to do in our day, who has time for that?
There are plenty of tools that produce documentation in multiple formats to help get you started but for everything they do…well, they have their drawbacks. They cost money, most are GUI based (that is, highly interactive), and they tend to focus on databases rather than capturing an entire instance’s configuration or details about the operating system the instance is running on. We need a way to work smarter, not harder, and automate documentation.
As a consultant, I frequently find myself needing to get up to speed with a client’s environment quickly, and that means I need to know more than what these tools tell me. I need the ability to discover SQL Server instances on a network and document everything about them—and while I’m at it, I want to check for common issues that might make life difficult without any intervention. And of course, since I’m a Windows PowerShell junkie, I want it all automated via scripts.
SQL Power Doc
With that in mind, I set out to write my own SQL and Windows documentation tool to do all those things that existing tools didn’t. The result is SQL Power Doc, a project I released to CodePlex in early April 2013. For more information, see SQL Server & Windows Documentation Using Windows PowerShell.
The goal of SQL Power Doc is to make it dirt simple for IT admins, DBAs, and everyone in-between to discover, document, and diagnose their servers. SQL Power Doc works with all versions of SQL Server from SQL Server 2000 through SQL Server 2012, and all versions of Windows Server and consumer Windows operating systems, from Windows 2000 Server and Windows XP through Windows Server 2012 and Windows 8. SQL Power Doc also is capable of documenting Windows Azure SQL databases.
If you’re not a Windows PowerShell expert (or if you’ve never even touched Windows PowerShell before), I’ve written The SQL Guide for PowerShell Beginners, which walks through every step of using the scripts, from beginning to end. Advanced users can start with the included scripts, but I’m hoping you’ll also find interesting things to do with the modules that the scripts use that I haven’t thought about.
The project is called SQL Power Doc, but because it collects details about Windows, it can be used as a standalone tool for documenting machines running Windows. Bonus! (I also wrote a guide called Using SQL Power Doc to Perform a Windows Inventory if you don’t care about the SQL Server part.)
Whether you’re using SQL Power Doc to document Windows operating systems or SQL Server, there are two steps to complete an inventory:
- Discover servers and collect an inventory
- Generate documentation
Discover servers and collect an inventory
The first step is to discover servers and collect an inventory. I recommend that you do this on a machine on the same physical network as the machines you’re gathering information from because SQL Power Doc collects a lot of information. (For a comprehensive list, see What's Documented on CodePlex.)
There are three ways to discover servers on your network:
- Query Active Directory DNS for a list of hosts
- Scan a subnet
- Use machine names
When collecting information from SQL Servers database objects (such as tables, procedures, and functions), object-level permissions are not included by default, but there are switch parameters you can provide to include them.
This step can take anywhere from a few minutes to over an hour to run, depending on how many servers you’re including. The time also depends on if you’re collecting database object information so status updates of what it’s doing are provided (by using the Write-Progress cmdlet) as shown in the following example.
The capability to write a detailed log file is also built into SQL Power Doc so you can see what’s going on while it’s running or review what happened after the fact (such as looking for errors).
When you run SQL Power Doc for the first time, I recommend trying it out against a single server, using the defaults (do not include database object information), and using verbose logging. When you’re comfortable with how it works and what it does, you can include more servers.
I also recommend that you do not run SQL Power Doc on a production SQL Server. Windows PowerShell has a reputation for being a bit of a memory hog sometimes, and the last thing you want to do is bring production to a screeching halt because of memory contention!
When this step is done, you’ll have a GZ compressed file on disk that contains the results of your inventory. You’ll use this file in the next step to generate the documentation.
Generate documentation
This step requires Excel on whatever machine you’re generating the documentation on, which likely means transferring the inventory file to your local desktop or laptop and doing the rest of the work there. This step loads the GZ compressed inventory file, decompresses it in memory, performs a database engine assessment, and uses Excel Interop to write everything to Excel workbooks.
As with the first step, this step writes progress to the console window and supports logging to a file. This step can take upwards of 10-20 minutes to finish depending on how much data it has to write, so you might want to grab a cup of coffee while it’s running.
When this step is finished, you’ll have three or four Excel workbooks containing the following information:
- Windows machine configuration
- SQL Server database engine configuration
- SQL Server database engine database objects (if included in the inventory)
- SQL Server database engine assessment
Each workbook contains a wealth of information about your servers: 23 sheets for Windows, 55 sheets for the database engine configuration, 74 sheets for the database engine database objects, and 6 sheets for the database engine assessment. I wasn’t kidding when I said SQL Power Doc collects a lot of information!
Uses for the documentation
Now that you’ve got comprehensive documentation about your servers in hand, here’s a few ideas for what you can do with it:
- Baselines: know what your SQL Server environment looked like last week, last month, and so on
- Security audits
- Licensing audits
- Provide a complete look at how your servers are configured without having to grant access
- Troubleshooting
- Compare server configurations, databases, SQL Agent settings, and so on
- Create a runbook that you can give to your operations team
- Plan upgrades: see what hidden features are in use on an instance
Having worked in IT for over 10 years I’ve found myself in all of these positions, and I wishI had SQL Power Doc sooner!
Now that you know the “power” of SQL Power Doc, there's no excuse not to document your servers. Head on over to the CodePlex site for the following resources so you can discover, document, and diagnose your SQL Servers today:
- SQL Server & Windows Documentation Using Windows PowerShell
- Requirements
- The SQL Power Doc Guide For PowerShell Beginners
- Downloadable code
~Kendal
Thank-you, Kendal, for an awesome blog post about an awesome project. This concludes SQL Server Week. Join me tomorrow for I Found this PowerShell Function—Now What?
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy