Install-DbaCommunitySoftware

Synopsis

Installs community-maintained SQL Server tooling through a single command

Description

Installs one or more of the community stored procedure kits that dbatools ships installers for, without needing to remember six separate command names. This is the install-side counterpart to Save-DbaCommunitySoftware, which already unifies the download step behind one -Software parameter.

Each tool is handed off to its dedicated installer, and the objects that installer emits are passed straight back to you:

• MaintenanceSolution: Install-DbaMaintenanceSolution (Ola Hallengren), SQL Server 2017 and later only
• FirstResponderKit: Install-DbaFirstResponderKit (Brent Ozar Unlimited)
• DarlingData: Install-DbaDarlingData (Erik Darling)
• SQLWATCH: Install-DbaSqlWatch (Marcin Gminski)
• WhoIsActive: Install-DbaWhoIsActive (Adam Machanic)
• DbaMultiTool: Install-DbaMultiTool (John McCall)

Three behaviors deliberately differ from calling an installer yourself:

• SQLWATCH is skipped with a warning on PowerShell Core, and the rest of the batch still runs. Install-DbaSqlWatch supports Windows PowerShell only, and left to itself it downloads its payload before reaching that check, so selecting All from PowerShell Core would fetch a file it can never use.

• WhoIsActive is given master when you do not pass Database. Called directly with no database, Install-DbaWhoIsActive opens an interactive picker, which would stall an unattended run.

• A failure against one tool does not end the batch. The remaining tools still run, and the failure surfaces as a warning naming the tool. With EnableException the first failure throws, as it would anywhere else in dbatools.

Each installer is called once with the whole instance list rather than once per instance, because they all download their payload before touching the first instance. Passing ten instances therefore fetches each archive once, not ten times.

A single script that fails partway through is reported rather than thrown. FirstResponderKit, DarlingData and DbaMultiTool catch a failed script themselves, warn, and hand back that row with a Status of Error, so EnableException does not make it terminating here any more than it does when you call those installers directly. Check Status on the returned objects to find them.

Everything else, including each installer version floor and its own confirmation prompts, is exactly what you get from the installer directly. An instance below a tool version floor is skipped by that installer with a warning while the rest of the batch continues.

Only the parameters common to most of the installers are surfaced here. When you need tool-specific options such as the Ola Hallengren job scheduling switches, the First Responder Kit script selection, or the SqlWatch pre-release feed, call that installer directly.

AzSqlTips is deliberately absent. Save-DbaCommunitySoftware downloads it, but it is consumed by Invoke-DbaDbAzSqlTip as a query rather than installed as stored procedures.

Syntax

Install-DbaCommunitySoftware
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-SqlCredential] <PSCredential>]
    [-Software] <String[]>
    [[-Database] <String>]
    [[-Branch] <String>]
    [[-LocalFile] <String>]
    [-Force]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example 1: Installs every supported community tool on sql2017

PS C:\> Install-DbaCommunitySoftware -SqlInstance sql2017 -Software All

Installs every supported community tool on sql2017. Each tool lands in its own default database, so SqlWatch goes to SQLWATCH and the rest go to master.

Example 2: Installs the First Responder Kit and sp_WhoIsActive into the DBAtools database on sql2017

PS C:\> Install-DbaCommunitySoftware -SqlInstance sql2017 -Software FirstResponderKit, WhoIsActive -Database DBAtools

Example 3: Refreshes the local cached copies and installs the Ola Hallengren Maintenance Solution and DarlingData on...

PS C:\> Install-DbaCommunitySoftware -SqlInstance sql2017, sql2019 -Software MaintenanceSolution, DarlingData -Force

Refreshes the local cached copies and installs the Ola Hallengren Maintenance Solution and DarlingData on both instances, without prompting for confirmation. Both instances are SQL Server 2017 or
later, which the Maintenance Solution requires.

Example 4: Installs sp_WhoIsActive on sql2017 from an already downloaded file, for a server with no internet access

PS C:\> Install-DbaCommunitySoftware -SqlInstance sql2017 -Software WhoIsActive -LocalFile C:\temp\sp_whoisactive.zip

Installs sp_WhoIsActive on sql2017 from an already downloaded file, for a server with no internet access. LocalFile takes exactly one tool at a time.

Example 5: Shows what the First Responder Kit install would do on every instance listed in servers.txt, without changing...

PS C:\> Get-Content C:\servers.txt | Install-DbaCommunitySoftware -Software FirstResponderKit -WhatIf

Shows what the First Responder Kit install would do on every instance listed in servers.txt, without changing anything.

Required Parameters

-SqlInstance

The target SQL Server instance or instances. This can be a collection and receive pipeline input to allow the function to be executed against multiple SQL Server instances.

-Software

Specifies which community tools to install. Accepts multiple values, or All to install every tool in one pass.
The names match Save-DbaCommunitySoftware so the download and install steps read the same way.

Optional Parameters

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-Database

Specifies the database to install the tools into. When you leave this off, each installer keeps its own default, which means master for most tools and SQLWATCH for SqlWatch.
Set this when you want every selected tool in one specific database, such as a dedicated DBA utility database.

-Branch

Specifies the source branch to download from. Only First Responder Kit, DarlingData and DbaMultiTool support branch selection, and their accepted values differ, so a value valid for one may be
rejected by another.
A warning names any selected tool that has no branch to switch.

-LocalFile

Specifies a zip archive or SQL script to install from instead of downloading. Use this on servers with no internet access.
Get the archive from the project release page on a machine that does have access and copy it across. Save-DbaCommunitySoftware does not produce a file for this: it consumes LocalFile the same way, to
refresh the local cache. The release page for each tool is listed in the Save-DbaCommunitySoftware help.
Because an archive belongs to exactly one tool, this can only be combined with a single Software value.

-Force

If this switch is enabled, the local cached copy of each tool is refreshed before installing and confirmation prompts are suppressed.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.

-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.

-Confirm

Prompts you for confirmation before executing any changing operations within the command.

Outputs

PSCustomObject

Objects are passed through from each installer unchanged, so the property set follows the tool rather than this command. Selecting several tools returns a mix of the shapes below, in the order the tools were requested. All three shapes share ComputerName, InstanceName and SqlInstance, so a mixed batch still groups and formats on those.

FirstResponderKit, DarlingData, DbaMultiTool and WhoIsActive return one object per script the installer ran:

• ComputerName (String): The name of the computer where the SQL Server instance resides

• InstanceName (String): The name of the SQL Server instance

• SqlInstance (String): The full SQL Server instance name (computer\instance)

• Database (String): The name of the database the script was installed into

• Name (String): The script base name, such as sp_Blitz or sp_BlitzCache. DarlingData installs from one combined script and so returns a single row named DarlingData; WhoIsActive returns a single row named sp_WhoisActive

• Status (String): Installed when the object was created, Updated when it already existed, Skipped when the script does not apply to that instance version, Error when that script failed. DbaMultiTool never reports Skipped, and WhoIsActive reports only Installed or Updated

• Version (String): WhoIsActive only. The sp_WhoisActive version read out of the installed script, or an empty string when the script carries no version header

MaintenanceSolution returns one object per instance, not per script, and has no Database, Name or Status:

• ComputerName (String): The name of the computer where the SQL Server instance resides
• InstanceName (String): The name of the SQL Server instance
• SqlInstance (String): The full SQL Server instance name (computer\instance)
• Results (String): Success or Failed, covering the whole solution install on that instance

SQLWATCH returns one object per instance and has no Name:

• ComputerName (String): The name of the computer where the SQL Server instance resides
• InstanceName (String): The name of the SQL Server instance
• SqlInstance (String): The full SQL Server instance name (computer\instance)
• Database (String): The name of the database SqlWatch was published to, SQLWATCH unless you pass Database
• Status (System.Text.RegularExpressions.Match): The last parenthesized fragment of the DACPAC publish result, which renders as its matched text
• DashboardPath (String): The full local file system path to the SqlWatch Dashboard directory Note: an instance a tool refuses, such as MaintenanceSolution against anything below SQL Server 2017, produces a warning from that installer and no object, while the rest of the batch continues.