Style Guide

Here are a few things to keep in mind when programming for dbatools.

Use these templates

The GitHub repo, dbatools-templates is dedicated to templates for commands. You can also look to similar commands for templates.

Get familiar with the current code

The code structure is as follows:

• dbatools\
  • functions\
    
    • Copy-DbaDatabase.ps1
    • Copy-DbaLogin.ps1
    • …
  • tests\
    
    • InModule.Help.Tests.ps1
  • dbatools.psd1
  • dbatools.psm1
  • LICENSE.txt
  • README.md

This is important

In order to get your function to access the shared environment that dbatools creates, you must do the following.

• Create your `.ps1` file from the template mentioned above and place it in the functions directory
• Reload the module: `Import-Module .\dbatools.psm1 -Force`

This will allow your function to access our internal functions such as Connect-SqlInstance until we add it ourselves to the psd1 file.

Note that the .psd1 should never be included in your pull request because it causes conflicts.

Minimum requirements

One source of pride for this project is that it works on most systems. We at least try to make it work on SQL Server 2000, though sometimes it's not possible. SQL Server 2005 and above usually works well.

If you have to pick between Azure and SQL Server, please do choose Azure, and ensure your command informs the user that SQL Server 2000 is not supported.

Also, remember that this module is intended for migrations and hence older systems, so PowerShell v3 is the base that we'll be using to program. Some modern methods and cmdlets won't be available to you, but it's a really solid version that still supports a ton.

Often times, clusters have to be handled differently. Try to test your command against a cluster if you've got access.

Program Thoroughly and Optimistically

Does the user need a table to be created? Create it for them and populate the database name (dbatools) and table names with defaults.

Program as if there is a solution. Locked out of your SQL Server because of a bad logon trigger? Program as though you can somehow populate a list of logon triggers, because we can probably find a way :D Let's work together to find a way.

Is there something you always forget as a DBA like Trace Flags? Perhaps your command can have a dictionary or your command could be the dictionary.

Use T-SQL only when appropriate

This can't be emphasized enough; SMO takes care of all the SQL commands for you, so use SMO by default. That way, the module will be compatible with all the different versions of SQL Server.

Don't know which SMO object you need? Look up the T-SQL syntax first; that's what we do. We needed to change the password for a credential, saw that it's ALTER CREDENTIAL in T-SQL and guessed that the issue could be resolved with $credential.alter() and sure enough that was it.

When is it appropriate to use T-SQL? When SMO can't be used. Like to find out supported features for a particular edition, in use right now by the database (stored in sys.dm_db_persisted_sku_features), if you need info from sys.key_encryptions or actually, if you want to detach a database but not modify the $databases collection.

We also use T-SQL when we need to work with FileGroups. This is because SMO slows down a great deal on servers with tons of databases and this is one easy way to ensure our commands perform well in these environments.

Don't rely on SQLPS

Do not require the user to load SQLPS or the new awesome version of SQLPS, SqlServer. This is for a number of reasons, but here's three. Remember, we program for the lowest common denominator and expect that the user is running old versions of things.

Got Questions?

We're available in the Slack channel #dbatools and via email ([email protected])