Since dbatools is command-line based, you can view/modify your current options using our various config commands.

• Get-DbatoolsConfig
• Get-DbatoolsConfigValue
• Set-DbatoolsConfig
• Reset-DbatoolsConfig
• Import-DbatoolsConfig
• Export-DbatoolsConfig
• Register-DbatoolsConfig
• Unregister-DbatoolsConfig

 
We offer the ability to configure various options such as connection timeouts, datetime formatting and default export paths. All-in-all, we offer nearly 100 configuration options to help customize and enhance your dbatools experience.

Exploring our options

To see a list of all of the options offered, open a PowerShell console and type Get-DbatoolsConfig.

In the image above, you can find some of the configuration options that you can set and will be widely used by dbatools.

These settings are scoped at the session-level. This means that if you use dbatools module within SQL Agent jobs and you have a different account to run it, you will need to set the options for the user/credential running your SQL Agent jobs. You can do this by logging into the server as that user and editing the options. You can also run PowerShell as that user by right-clicking the PowerShell logo in the taskbar, then pressing Shift + right-click over the PowerShell logo. There, you will be offered the option to run as a different user.

Because there are nearly 100 configuration options, you can take advantage of Out-Gridview to easily view and sort them.

You can then filter out the results in a easier manner.

“I saw that settings are grouped by modules. Whichs modules are available?”

If you run the following command, you will find all the distinct modules we have:

Get-DbatoolsConfig | Select-Object -Property Module -Unique

As you can see there are a good amount of different modules.

Get-DbatoolsConfig vs. Get-DbatoolsConfigValue

You may have noticed two similarly named commands: Get-DbatoolsConfig and Get-DbatoolsConfigValue. Let’s take a look at the differences.
 

Get-DbatoolsConfig – a rich object

This command returns not only the value for a setting but also the module where it belongs and a useful description about it.
You can specify the -FullName (preferable because it is unique) or only the -Name (same as -FullName but without the prefix which is the module name).

-FullName example:

Get-DbatoolsConfig -FullName sql.connection.timeout

-Name example:

Get-DbatoolsConfig -Name connection.timeout

We also provide a validation script to a configuration. If you want to know how we validate it, you can see the Validation property, as example if you run:

Get-DbatoolsConfig -FullName formatting.size.digits | Select-Object *

You will get:

 

Get-DbatoolsConfigValue – Is what you are thinking but we have interesting options

If you just want to get the configured value as a string, you should use the Get-DbatoolsConfigValue command. This command is widely used internally within the dbatools module.

You may find that we also use the -FallBack, as stated on documentation “A fallback value to use, if no value was registered to a specific configuration element. This basically is a default value that only applies on a “per call” basis, rather than a system-wide default.”

Also if we don’t want to get a null result we can specify the -NotNull parameter “…the function will throw an error if no value was found at all.”
 

Set a new configuration value

To update a value you need to use the Set-DbatoolsConfig command. Unfortunately, you will not find documentation for this command on our docs page. This is a known issue and it happens because that command is a cmdlet so the help is in the dbatools library itself.

For this particular case, you can and should rely on the Get-Help command.

Get-Help -Name Set-DbatoolsConfig -Full

The easier way to update a value is provide the -FullName and -Value parameters. Example:

Set-DbatoolsConfig -FullName formatting.size.digits -Value 3

Note that changes made by Set-DbatoolsConfig only persists for the current session. To permanently persist your changes, use Register-DbatoolsConfig. This command will be covered next.
 

Let’s see other examples

Want to clean the logs more frequently? Or keep them longer than the default of 7 days? Let’s change to 8 days by setting the Logging.MaxLogFileAge configuration.

Set-DbatoolsConfig -FullName Logging.MaxLogFileAge -Value (New-TimeSpan -Days 8)

Want to format dates and times differently?

Take a look at the formatting section and find a couple of configurations to set the format as you would like.

If you want to change from dd MMM yyyy format to yyyy MM dd you can run the following command:

Set-DbatoolsConfig -FullName formatting.date -Value 'yyyy MM dd'

What about sqlconnection timeout?

15 seconds (the default) is not enough? Change it using the sql.connection.timeout configuration.

Set-DbatoolsConfig -FullName Logging.MaxLogFileAge -Value 30

Do you use dbatools with Azure?

There are a couple of configs that you can set in the Azure section. Take a look at them:

Get-DbatoolsConfig -Module azure

Note that only a few of our commands have been tested to work with Azure. Better support for Azure is a long-term goal.
 

Permanently persist changes

As mentioned previously, when you use the Set command, it is set only for your current session. To make the change permanent, use Register-DbatoolsConfig.

Get-DbatoolsConfig | Register-DbatoolsConfig

This will write all configuration values, by default, in the registry.
Like all of our config commands, this works on Windows, Linux and macOS.
 

Reset configured value to its default

To reset all of your configured values to dbatools default, run the following:

Reset-DbatoolsConfig -FullName sql.connection.timeout

This will set the configuration value back to 15. To reset all of your dbatools options to default, run the following:

Get-DbatoolsConfig | Reset-DbatoolsConfig

What’s new?

Since last dbatools version 1.0.32, new PowerShell Remoting configurations are available. You can read more about it on my recent blog post More PowerShell Remoting coverage in dbatools to learn more.
 

Just remember…

Next time you catch yourself thinking about changing some default behaviour remember to take a look into these configurations. If you found something that is not available for your use case, talk with us on Slack or just open an feature request explaining your needs and we will try to guide/help you.

Thanks for reading!
Cláudio

With our recent release, “twentyfiveschmeckles (v0.8.694)“, we introduced the command Find-DbaStoredProcedure.

This command allows us to find which stored procedures have a specific string or regular expression. While that may not be groundbreaking, what is new are the features we provide and the speed at which we return them.
 

Use cases

Let me explain at least two cases where I think this command is (very) useful:

1 . Back in the days when I was a full time T-SQL developer each time we needed to build a new feature or implement an improvement that required new columns in tables, we had to find which stored procedures to target for refactoring. Modifying stored procedures that perform CRUD (Create, Read, Update, Delete) operations was a common target because of the multiple phases required in maintaining data correctly:

• we need to insert values on the new columns (Create)
• we then need to read and retrieve those new columns (Read)
• if the value is suitable of changes we need to update it (Update)
• and finally if we need to delete records, that column may be part of some WHERE clause (Delete).

It’s clear we need a way find all stored procedures that use a specific table or a sibling column and we want the results to be returned as quickly and with as little work as possible; often times you may need to implement many changes and simply searching through the database or results can be frustrating or inexact.

2 . As a full-time DBA you may receive complaints like “a stored procedure is failing on instance A” or vague information like “I received an error incorrect syntax near ‘blah’.” Often we don’t have further input and we need to narrow down which database, procedure, and now line this issue belongs to belongs.

If a developer asks for help, or you need to check a version of a module, you typically starts with determining which change was made, visiting the database on all environments (eg. DEV, QA, PRD and more!) to verify which environments it was made, when it happened, and in which environments changes might be missing

That’s just two scenarios, I’m sure that you have encountered dozens more, or will in the future.
 

Why should you care?

$servers | Find-DbaStoredProcedure -Pattern lemaire 37,545 #SQLServer stored procedures on 9 servers evaluated in 8.67 seconds! https://t.co/uTBcP6bCHJ

— Chrissy LeMaire (@cl) February 9, 2017

Chrissy tweeted her experience going through 9 servers and searching more than 37,000 objects in less than 9 seconds.

My first thought was “WOW! that’s fast.” but given the results I honestly wondered how and if it could actually be that fast (Chrissy did, too, actually.)

Turns out, it’s true and I’m here to share my findings with you!

I’ve done four different tests comparing dbatools command and standard SSMS approaches I’ve used since the beginning of time:

1. Search only on one database in one server
2. Search on all databases (40)  on one server
3. Search on one database in two different server
4. Search on all databases (47) in two different servers

Note: For the 3rd and 4th test I will be connected to a different instance (sql2012) in order to add the connect time. This will simulate better what dbatools uses.
 

For 1st test:

We will use the following T-SQL:

USE AdventureWorks2014
GO

SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
FROM sys.sql_modules m
INNER JOIN sys.procedures p
ON m.object_id = p.object_id
WHERE m.[definition] like '%JobTitle%'

dbatools command:

Find-DbaStoredProcedure -SqlInstance sql2016 -Databases AdventureWorks2014 -Pattern JobTitle

For 2nd test:

T-SQL:

exec sp_MSforeachdb 'USE [?]
SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
FROM sys.sql_modules m
INNER JOIN sys.procedures p
ON m.object_id = p.object_id
WHERE m.[definition] like ''%JobTitle%'''

And the dbatools command looks like:

Find-DbaStoredProcedure -SqlInstance sql2016 -Pattern JobTitle
 

3rd test:

T-SQL code (Note: sqlcmd mode must be enabled on SSMS to run this script – please read this article to learn more):

:connect sql2016
Use AdventureWorks2014
GO
 SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
  FROM sys.sql_modules m
    INNER JOIN sys.procedures p
       ON m.object_id = p.object_id
 WHERE m.[definition] like '%JobTitle%'
GO

:connect sql2014
Use AdventureWorks2014
GO
 SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
  FROM sys.sql_modules m
    INNER JOIN sys.procedures p
       ON m.object_id = p.object_id
 WHERE m.[definition] like '%JobTitle%'
GO

dbatools command:

Find-DbaStoredProcedure -SqlInstance sql2016, sql2014 -Databases AdventureWorks2014 -Pattern JobTitle

4th and final test:

T-SQL:

:connect sql2016
SET STATISTICS TIME ON
exec sp_MSforeachdb 'USE [?]
SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
  FROM sys.sql_modules m
    INNER JOIN sys.procedures p
       ON m.object_id = p.object_id
 WHERE m.[definition] like ''%JobTitle%'''
GO

:connect sql2014
SET STATISTICS TIME ON
exec sp_MSforeachdb 'USE [?]
SELECT db_name() AS DBName, p.[name], m.[definition] as TextBody
  FROM sys.sql_modules m
    INNER JOIN sys.procedures p
       ON m.object_id = p.object_id
 WHERE m.[definition] like ''%JobTitle%'''

dbatools command:

Find-DbaStoredProcedure -SqlInstance sql2016, sql2014 -Pattern JobTitle

Here are the results:

The values are in ms (less is better)

A tie?

Not even close. Lets look to the output and see which one appears richer.
 

More detail in the results

T-SQL output:

dbatools output:

We show the line number where pattern was found.
 

And similarly, more powerful search abilities

Consider accurately searching for all occurrences the following regex pattern, which represents an email address:

Find-DbaStoredProcedure -SqlInstance sql2016 -Pattern '\w+@\w+\.\w+'

We can even output this to a grid and filter:

But I want nice GUI! – Redgate SQL Search for the rescue

Well, for some of us PowerShell console is a nice GUI

If you want to do this type of search, you can download and use the free SQL Search from Redgate. This is a great tool that allows us to search not only on Stored Procedures but also on other object definitions such as Tables, Views, Constraints, Triggers, Functions and even Agent Jobs.

This is fast! See it in action.

 
You can see additional details in the grid result, such as:

• The type of object matched
• The type of match (such as column name, just a text match)
• The line of SQL that matches your search (Just like our Find-DbaStoredProcedure command)

Wrap up

So for me and those that use the traditional query(SSMS) based methods, this is like night and day when dealing with multiple databases. It really is faster!

I wanted to blog this for you because I think this brings new ways to gather and filter the output we often need and hopefully you can use them further in the pipeline.

If you have experience with this scenario or others that that you would like to share, please drop us a message

Thanks for reading.
Cláudio