Get-DbaDatabase - Add Pattern parameter for wildcard database filtering (#9897)

Author: potatoqualitee

CLAUDE.md

@@ -376,6 +376,21 @@ Failure to register in both locations will result in the command not being avail
 - Keep the description concise and descriptive (not vague)
 - Focus on what the change does, not implementation details
 
+### Pattern Parameter Convention
+
+**CRITICAL RULE**: When adding a -Pattern parameter to any dbatools command, it MUST use regular expressions (regex), not SQL LIKE wildcards or PowerShell wildcards.
+
+```powershell
+# CORRECT - Regex pattern matching
+if ($name -match $pattern) { return $true }
+
+# WRONG - SQL LIKE wildcards
+$psPattern = $pattern -replace '%', '*' -replace '_', '?'
+if ($name -like $psPattern) { return $true }
+```
+
+This ensures consistency across all dbatools commands that support pattern matching.
+
 ### Parameter Validation Pattern
 
 ```powershell

public/Get-DbaDatabase.ps1

@@ -20,13 +20,18 @@ function Get-DbaDatabase {
         For MFA support, please use Connect-DbaInstance.
 
     .PARAMETER Database
-        Specifies one or more databases to include in the results. Supports wildcards and exact name matching.
+        Specifies one or more databases to include in the results using exact name matching.
         Use this when you need to retrieve specific databases instead of all databases on the instance.
 
     .PARAMETER ExcludeDatabase
-        Specifies one or more databases to exclude from the results. Supports wildcards and exact name matching.
+        Specifies one or more databases to exclude from the results using exact name matching.
         Use this to filter out specific databases like test or staging environments from your inventory.
 
+    .PARAMETER Pattern
+        Specifies a pattern for filtering databases using regular expressions.
+        Use this when you need to match databases by pattern, such as "^dbatools_" or ".*_prod$".
+        This parameter supports standard .NET regular expression syntax.
+
     .PARAMETER ExcludeUser
         Returns only system databases (master, model, msdb, tempdb).
         Use this when you need to focus on system database maintenance tasks or validation.
@@ -164,6 +169,11 @@ function Get-DbaDatabase {
 
         Returns databases 'OneDb' and 'OtherDB' from SQL Server instances SQL2 and SQL3 if databases by those names exist on those instances.
 
+    .EXAMPLE
+        PS C:\> Get-DbaDatabase -SqlInstance SQL2,SQL3 -Pattern "^dbatools_"
+
+        Returns all databases that match the regex pattern "^dbatools_" (e.g., dbatools_example1, dbatools_example2) from SQL Server instances SQL2 and SQL3.
+
     #>
     [CmdletBinding(DefaultParameterSetName = "Default")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "", Justification = "Internal functions are ignored")]
@@ -173,6 +183,7 @@ function Get-DbaDatabase {
         [PSCredential]$SqlCredential,
         [string[]]$Database,
         [string[]]$ExcludeDatabase,
+        [string[]]$Pattern,
         [Alias("SystemDbOnly", "NoUserDb", "ExcludeAllUserDb")]
         [switch]$ExcludeUser,
         [Alias("UserDbOnly", "NoSystemDb", "ExcludeAllSystemDb")]
@@ -306,9 +317,21 @@ function Get-DbaDatabase {
             }
 
             $backed_info = Invoke-QueryRawDatabases
+
+            # Helper function to test if a name matches any of the provided regex patterns
+            $matchesPattern = {
+                param($name, $patterns)
+                if (!$patterns) { return $true }
+                foreach ($pattern in $patterns) {
+                    if ($name -match $pattern) { return $true }
+                }
+                return $false
+            }
+
             $backed_info = $backed_info | Where-Object {
                 ($_.name -in $Database -or !$Database) -and
                 ($_.name -notin $ExcludeDatabase -or !$ExcludeDatabase) -and
+                (& $matchesPattern $_.name $Pattern) -and
                 ($_.Owner -in $Owner -or !$Owner) -and
                 ($_.state -ne 6 -or !$OnlyAccessible)
             }
@@ -331,6 +354,7 @@ function Get-DbaDatabase {
                     Where-Object {
                         ($_.Name -in $Database -or !$Database) -and
                         ($_.Name -notin $ExcludeDatabase -or !$ExcludeDatabase) -and
+                        (& $matchesPattern $_.Name $Pattern) -and
                         ($_.Owner -in $Owner -or !$Owner) -and
                         ($_.RecoveryModel -in $RecoveryModel -or !$_.RecoveryModel) -and
                         $_.EncryptionEnabled -in $Encrypt
@@ -340,6 +364,7 @@ function Get-DbaDatabase {
                     Where-Object {
                         ($_.Name -in $Database -or !$Database) -and
                         ($_.Name -notin $ExcludeDatabase -or !$ExcludeDatabase) -and
+                        (& $matchesPattern $_.Name $Pattern) -and
                         ($_.Owner -in $Owner -or !$Owner) -and
                         $_.ReadOnly -in $Readonly -and
                         $_.IsAccessible -in $AccessibleFilter -and

tests/Get-DbaDatabase.Tests.ps1

@@ -15,6 +15,7 @@ Describe $CommandName -Tag UnitTests {
                 "SqlCredential",
                 "Database",
                 "ExcludeDatabase",
+                "Pattern",
                 "ExcludeUser",
                 "ExcludeSystem",
                 "Owner",
@@ -83,6 +84,52 @@ Describe $CommandName -Tag IntegrationTests {
     }
 }
 
+Describe $CommandName -Tag IntegrationTests {
+    BeforeAll {
+        $random = Get-Random
+        $dbPrefix = "dbatoolsci_pattern"
+        $dbname1 = "${dbPrefix}_test1_$random"
+        $dbname2 = "${dbPrefix}_test2_$random"
+        $dbname3 = "${dbPrefix}_prod1_$random"
+        $dbname4 = "other_database_$random"
+        $null = New-DbaDatabase -SqlInstance $TestConfig.instance1 -Name $dbname1, $dbname2, $dbname3, $dbname4
+    }
+    AfterAll {
+        $null = Get-DbaDatabase -SqlInstance $TestConfig.instance1 -Database $dbname1, $dbname2, $dbname3, $dbname4 | Remove-DbaDatabase
+    }
+
+    Context "Pattern parameter filtering" {
+        It "Should return databases matching pattern with regex" {
+            $results = Get-DbaDatabase -SqlInstance $TestConfig.instance1 -Pattern "^${dbPrefix}_"
+            $results.Name | Should -Contain $dbname1
+            $results.Name | Should -Contain $dbname2
+            $results.Name | Should -Contain $dbname3
+            $results.Name | Should -Not -Contain $dbname4
+        }
+
+        It "Should return databases matching pattern with _test segment" {
+            $results = Get-DbaDatabase -SqlInstance $TestConfig.instance1 -Pattern "^${dbPrefix}_test"
+            $results.Name | Should -Contain $dbname1
+            $results.Name | Should -Contain $dbname2
+            $results.Name | Should -Not -Contain $dbname3
+            $results.Name | Should -Not -Contain $dbname4
+        }
+
+        It "Should return databases matching multiple patterns" {
+            $results = Get-DbaDatabase -SqlInstance $TestConfig.instance1 -Pattern "^${dbPrefix}_test", "^${dbPrefix}_prod"
+            $results.Name | Should -Contain $dbname1
+            $results.Name | Should -Contain $dbname2
+            $results.Name | Should -Contain $dbname3
+            $results.Name | Should -Not -Contain $dbname4
+        }
+
+        It "Should return no results for non-matching pattern" {
+            $results = Get-DbaDatabase -SqlInstance $TestConfig.instance1 -Pattern "^nonexistent_"
+            $results | Should -BeNullOrEmpty
+        }
+    }
+}
+
 Describe $CommandName -Tag UnitTests -Skip {
     # Skip UnitTests because they need refactoring.