Getting Started

dbatools is a free PowerShell module with nearly 700 commands that replace manual SQL Server administration with powerful and fun automation.

Why dbatools?

Traditional Methods	dbatools
SSMS: Click through 50 servers manually	PowerShell: Query all 50 servers in one command
Migration: Days of planning and execution	Migration: Minutes with automated best practices
Backup Testing: Manual restores, hope for the best	Backup Testing: Automated verification of all backups
Documentation: Hours of manual collection	Documentation: Instant HTML/Excel reports
Scripting: Complex T-SQL across versions	Scripting: Consistent commands for SQL 2000-2022

Your First 5 Minutes

Let’s get you up and running with dbatools. These commands are read-only and safe to explore.

# 0. Check your PowerShell version (v3+ required for Windows, Core 7.4+ for Linux/macOS)
$PSVersionTable.PSVersion

# 1. Install dbatools (takes about 30 seconds)
Install-Module dbatools -Scope CurrentUser

# 2. See all databases on your local SQL Server
# Replace 'sql01' with your SQL Server name if needed
Get-DbaDatabase -SqlInstance sql01

# 3. Check when your databases were last backed up
Get-DbaLastBackup -SqlInstance sql01 | Format-Table

# 4. Run any T-SQL query you want
Invoke-DbaQuery -SqlInstance sql01, sql02, sql03 -Query "SELECT @@VERSION"

What just happened?

Get-DbaDatabase shows all your databases - no clicking through SSMS
Get-DbaLastBackup checks backup history - instantly spot backup problems
Invoke-DbaQuery runs any T-SQL you want - your most versatile command
These commands are read-only - they won’t change anything on your server

Note: Replace sql01 with your SQL Server instance name (like sql01, server\instance, or server:port).

Installation

Where Should You Install dbatools?

Install dbatools on your workstation or jump box - NOT on your SQL Servers.

Think of it like SSMS: you install it on your local machine and connect remotely to SQL Server instances. dbatools is a PowerShell module that runs on your computer and manages SQL Servers over the network.

Good places to install:

Your Windows workstation (where you run SSMS)
A dedicated management/jump server
Your laptop for demos and dev work

Don’t install on:

Production SQL Servers (unnecessary and adds risk)
Every SQL Server in your estate (wasteful)

Quick Install (Recommended)

# One-time setup: Allow PowerShell to run scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install dbatools for current user (no admin rights needed)
Install-Module dbatools -Scope CurrentUser

That’s it! dbatools is now installed on your workstation and ready to manage remote SQL Servers.

First Time Using PowerShell Gallery?

If you get a prompt about trusting PSGallery, type Y for Yes. You only need to do this once:

Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

Certificate Change (v2.5.5+ Users)

If you’re upgrading from an older version, you may need to use:

Install-Module dbatools -Force -SkipPublisherCheck

Learn more about our certificate change →

Other Installation Methods (Click to expand)

Install for All Users (Requires Admin)

Install-Module dbatools

Offline Installation

# On internet-connected machine:
Save-Module -Name dbatools -Path C:\temp

# Copy to target machine and place in:
# - All users: C:\Program Files\WindowsPowerShell\Modules
# - Current user: $HOME\Documents\WindowsPowerShell\Modules

# Import the module after copying
Import-Module dbatools

Chocolatey

choco install dbatools

Learning Approach

dbatools has over 700 commands - don’t let that overwhelm you! Think of it like learning SQL Server: start with the basics, then expand your knowledge over time.

Essential Discovery & Troubleshooting

Before you can automate, you need to explore:

Find-DbaInstance - Discover SQL instances on your network
Test-DbaConnection - Verify connectivity and permissions
Get-DbaDiskSpace - Check disk space before things go wrong
Find-DbaAgentJob - Find failed jobs across all servers
Find-DbaStoredProcedure - Search for code patterns across databases

Once you’re comfortable with these, branch out to whatever you work with most: migrations, security, monitoring, or configuration management.

Common Use Cases

Now that you’ve seen the basics, here are some powerful real-world examples.

Running Queries at Scale

# Run a query against multiple servers at once
Invoke-DbaQuery -SqlInstance sql01, sql02, sql03 -Query "SELECT @@VERSION"

# Export query results to CSV
Invoke-DbaQuery -SqlInstance sql01 -Database master -Query "SELECT * FROM sys.databases" |
    Export-Csv -Path C:\temp\databases.csv -NoTypeInformation

# Run a script file against all your servers
Get-Content C:\Scripts\CheckStatus.sql | Invoke-DbaQuery -SqlInstance (Get-Content C:\servers.txt)

Backups & Restores

# Backup all user databases with compression
Backup-DbaDatabase -SqlInstance sql01 -ExcludeSystem -Compress

# Simple restore
Restore-DbaDatabase -SqlInstance sql01 -Path "C:\temp\mydb.bak"

# Test ALL your backups on a different server
# This actually restores them, verifies integrity, then drops them
Test-DbaLastBackup -SqlInstance sql01 -Destination sql02 | Out-GridView

Finding Things Fast

# Find a database across multiple servers
Find-DbaDatabase -SqlInstance sql01, sql02, sql03 -Pattern "Production"

# Find stored procedures containing specific text
Find-DbaStoredProcedure -SqlInstance sql01 -Pattern "INSERT INTO Audit"

# Discover SQL instances on your network
Find-DbaInstance -ComputerName server01, server02

Monitoring & Health

# Check disk space before problems happen
Get-DbaDiskSpace -ComputerName sql01, sql02 | Out-GridView

# Find databases without recent backups
Get-DbaLastBackup -SqlInstance sql01 |
    Where-Object LastFullBackup -lt (Get-Date).AddDays(-7)

# Check for corruption
Get-DbaLastGoodCheckDb -SqlInstance sql01 | Out-GridView

# Find failed jobs across all servers
Find-DbaAgentJob -SqlInstance sql01, sql02 -Failed | Get-DbaAgentJobHistory

# See who's running what and blocking whom
Get-DbaProcess -SqlInstance sql01 | Out-GridView

# Monitor currently running queries with sp_WhoIsActive
Install-DbaWhoIsActive -SqlInstance sql01 -Database master
Invoke-DbaWhoIsActive -SqlInstance sql01

Data Import & Export

# Import CSV files into SQL Server (auto-creates tables!)
Import-DbaCsv -Path C:\data\sales.csv -SqlInstance sql01 -Database tempdb -AutoCreateTable

# Copy data between tables, even across servers
Copy-DbaDbTableData -SqlInstance sql01 -Database source -Table Customers `
    -DestinationSqlInstance sql02 -DestinationDatabase target -DestinationTable Customers

# Write PowerShell objects directly to SQL Server
Get-Process | Write-DbaDbTableData -SqlInstance sql01 -Database tempdb -Table ProcessList -AutoCreateTable

Migrations & DR

# Migrate entire SQL instance with one command
$params = @{
    Source = 'sql01'
    Destination = 'sql02'
    BackupRestore = $true
    SharedPath = '\\nas\temp'
}
Start-DbaMigration @params

# Export everything for disaster recovery
# Creates scripts for logins, jobs, databases, configs, everything
Export-DbaInstance -SqlInstance sql01 -Path C:\temp\dr

# Copy just the jobs between servers
Copy-DbaAgentJob -Source sql01 -Destination sql02

# Migrate a database with logins
Copy-DbaDatabase -Source sql01 -Destination sql02 -Database MyApp -BackupRestore -SharedPath \\nas\migration
Copy-DbaLogin -Source sql01 -Destination sql02 -Login ad\appuser

Quick Wins

Lost sysadmin access? Use Reset-DbaAdmin
Need to test your backups? Use Test-DbaLastBackup
SPN management got you down? Use our suite of SPN commands
Got so many databases you can’t keep track? Use Find-DbaDatabase

Getting Help

# Detailed help for any command
Get-Help Test-DbaLastBackup -Full

# See examples
Get-Help Test-DbaLastBackup -Examples

# Find commands by keyword
Get-Command -Module dbatools *backup*
Find-DbaCommand -Tag Migration

# Open online help in browser
Get-Help Test-DbaLastBackup -Online

Resources:

Documentation
Command Reference
Blog
Slack Community - Friendly help from the community

Advanced Topics

Authentication

By default, dbatools uses Windows Authentication (your current login). To use SQL logins or different Windows credentials:

SQL Authentication

$cred = Get-Credential sqladmin
Get-DbaDatabase -SqlInstance sql01 -SqlCredential $cred

Alternative Windows Credentials

For commands that access Windows (like Get-DbaDiskSpace):

$cred = Get-Credential ad\winadmin
Get-DbaDiskSpace -ComputerName sql01 -Credential $cred

Storing Credentials Securely

PowerShell’s Export-CliXml provides a fast and secure way to store credentials to disk. The credentials are encrypted using Windows Data Protection API (DPAPI) and can only be decrypted by the same user on the same machine.

# Save credentials to disk (one-time setup)
Get-Credential | Export-CliXml -Path "$HOME\sql-credentials.xml"

# Reuse saved credentials in scripts
$cred = Import-CliXml -Path "$HOME\sql-credentials.xml"
Get-DbaDatabase -SqlInstance sql01 -SqlCredential $cred

For more advanced credential management approaches including the Secrets Management module, see Rob Sewell’s guide.

Custom Ports

If you use non-default ports and SQL Browser is disabled, use a colon or comma:

# Using colon or comma for non-default ports
Get-DbaDatabase -SqlInstance 'sql01:55559'
Get-DbaDatabase -SqlInstance 'sql01,55559'  # Note: quotes required with comma

PowerShell treats commas as array separators, so you must use quotes.

PowerShell Transcript Logging

# Import module before starting transcript (PS 5.1 requirement)
Import-Module dbatools
Start-Transcript
Get-DbaDatabase -SqlInstance sql01
Stop-Transcript

Troubleshooting

Common Issues

Issue: “Could not connect to SqlInstance”

# Test connectivity
Test-DbaConnection -SqlInstance sql01

# Check if SQL Browser service is running (for named instances)
Get-DbaService -ComputerName sql01 -Type Browser

Issue: “Access denied” errors

# Ensure you have proper SQL permissions
Get-DbaLogin -SqlInstance sql01 -Login $env:USERNAME

# For Windows authentication issues, verify domain connectivity
Test-ComputerSecureChannel

Issue: Module won’t import

# Check execution policy
Get-ExecutionPolicy

# Force reimport if needed
Remove-Module dbatools -Force -ErrorAction SilentlyContinue
Import-Module dbatools -Force

For more help, visit our troubleshooting guide or ask in Slack.

More Learning Resources

📖 Learn dbatools in a Month of Lunches

Want structured, in-depth training? Check out our official book Learn dbatools in a Month of Lunches by dbatools creator Chrissy LeMaire and core contributors Rob Sewell, Jess Pomfret, and Cláudio Silva (Manning Publications, 2022).

In 28 bite-sized lessons, learn automation techniques directly from the experts who built dbatools. Perfect for DBAs and systems engineers who want to master SQL Server automation.

Blog Articles

Our blog has great articles for diving deeper:

Community & Support

Get Involved:

Community Channels:

Stats:

📦 7+ million downloads on PowerShell Gallery
👥 250+ contributors
🎯 700+ commands
🚀 10+ years of active development

System Requirements

SQL Server Compatibility

Version	Commands Supported
SQL Server 2000	75%
SQL Server 2005	90%
SQL Server 2008/R2	93%
SQL Server 2012+	100%
Azure SQL VM	As per version above
Azure SQL Database	40%
Azure SQL Managed Instance	60%
Containers/Kubernetes	75%

Operating System Compatibility

OS	Commands Supported	PowerShell Required
Windows 7/8/10/11	100%	v3+
Windows Server 2008 R2+	100%	v3+
Linux (Intel/ARM64)	78%	Core 7.4.0+
macOS (Intel/M1)	78%	Core 7.4.0+

💡 Note: Commands requiring SQL WMI or -ComputerName parameter typically don’t work on Linux/macOS.

Network Requirements

For remote SQL Server management, ensure these ports are accessible:

Protocol	Default Port	Used By	Required For	Firewall Note
SQL Database Engine	1433	`Get-DbaDatabase`	62% of commands	Allow inbound on SQL Server
WS-Management	5985/5986	`New-DbaClientAlias`	25% of commands	Windows Remote Management
SQL WMI	135	`Enable-DbaAgHadr`	4% of commands	DCOM/RPC endpoint mapper
SMB	445	`Backup-DbaDatabase`	4% of commands	File sharing for backups

Firewall Tip: Create a dedicated Windows Firewall rule group for dbatools management traffic.