Test-SqlDscIsDatabase: Check database existence

CHANGELOG.md

@@ -5,8 +5,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- BREAKING CHANGE: Removed public command `Test-SqlDscDatabase`. Use
+  `Test-SqlDscIsDatabase` to check existence. For property checks, use
+  `Test-SqlDscDatabaseProperty`. See [issue #2201](https://github.com/dsccommunity/SqlServerDsc/issues/2201).
+
 ### Added
 
+- Added public command `Test-SqlDscIsDatabase` to test if a database exists on a
+  SQL Server Database Engine instance ([issue #2201](https://github.com/dsccommunity/SqlServerDsc/issues/2201)).
 - Added public command `Get-SqlDscSetupLog` to retrieve SQL Server setup bootstrap
   logs (Summary.txt) from the most recent setup operation. This command can be used
   interactively for troubleshooting or within integration tests to help diagnose

azure-pipelines.yml

@@ -336,7 +336,7 @@ stages:
                   'tests/Integration/Commands/ConvertFrom-SqlDscDatabasePermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabase.Integration.Tests.ps1'
-                  'tests/Integration/Commands/Test-SqlDscDatabase.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Test-SqlDscIsDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscDatabaseProperty.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscDatabasePermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabasePermission.Integration.Tests.ps1'

source/Public/Test-SqlDscDatabaseProperty.ps1

@@ -26,6 +26,16 @@
     .PARAMETER DatabaseObject
         Specifies the database object to test properties for (from Get-SqlDscDatabase).
 
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s databases should be refreshed before
+        trying to get the database object. This is helpful when databases could have been
+        modified outside of the **ServerObject**, for example through T-SQL. But
+        on instances with a large amount of databases it might be better to make
+        sure the **ServerObject** is recent enough.
+
+        This parameter is only used when testing properties using **ServerObject** and
+        **Name** parameters.
+
     .PARAMETER Collation
         Specifies the default collation for the database.
 
@@ -505,6 +515,10 @@ function Test-SqlDscDatabaseProperty
         [System.String]
         $Name,
 
+        [Parameter(ParameterSetName = 'ServerObjectSet')]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh,
+
         [Parameter(ParameterSetName = 'DatabaseObjectSet', Mandatory = $true, ValueFromPipeline = $true)]
         [Microsoft.SqlServer.Management.Smo.Database]
         $DatabaseObject,
@@ -1109,7 +1123,7 @@ function Test-SqlDscDatabaseProperty
 
                 $previousErrorActionPreference = $ErrorActionPreference
                 $ErrorActionPreference = 'Stop'
-                $sqlDatabaseObject = $ServerObject | Get-SqlDscDatabase -Name $Name -ErrorAction 'Stop'
+                $sqlDatabaseObject = $ServerObject | Get-SqlDscDatabase -Name $Name -Refresh:$Refresh -ErrorAction 'Stop'
                 $ErrorActionPreference = $previousErrorActionPreference
             }
 
@@ -1127,7 +1141,7 @@ function Test-SqlDscDatabaseProperty
         $boundParameters = Remove-CommonParameter -Hashtable $PSBoundParameters
 
         # Remove function-specific parameters
-        foreach ($parameterToRemove in @('ServerObject', 'Name', 'DatabaseObject'))
+        foreach ($parameterToRemove in @('ServerObject', 'Name', 'DatabaseObject', 'Refresh'))
         {
             $boundParameters.Remove($parameterToRemove)
         }

source/Public/Test-SqlDscIsDatabase.ps1

@@ -0,0 +1,81 @@
+<#
+    .SYNOPSIS
+        Tests if a database exists on a SQL Server Database Engine instance.
+
+    .DESCRIPTION
+        This command tests if a database exists on a SQL Server Database Engine instance.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER Name
+        Specifies the name of the database to test for existence.
+
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s databases should be refreshed before
+        testing the database existence. This is helpful when databases could have been
+        modified outside of the **ServerObject**, for example through T-SQL. But
+        on instances with a large amount of databases it might be better to make
+        sure the **ServerObject** is recent enough.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Test-SqlDscIsDatabase -Name 'MyDatabase'
+
+        Tests if the database named **MyDatabase** exists on the instance.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        Test-SqlDscIsDatabase -ServerObject $serverObject -Name 'MyDatabase' -Refresh
+
+        Tests if the database named **MyDatabase** exists on the instance, refreshing
+        the server object's databases collection first.
+
+    .OUTPUTS
+        `[System.Boolean]`
+
+        Returns `$true` if the target object is a database; otherwise, `$false`.
+
+    .INPUTS
+        `[Microsoft.SqlServer.Management.Smo.Server]`
+
+        The server object can be provided via the pipeline to **ServerObject**.
+#>
+function Test-SqlDscIsDatabase
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [OutputType([System.Boolean])]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh
+    )
+
+    process
+    {
+        Write-Verbose -Message ($script:localizedData.IsDatabase_Test -f $Name, $ServerObject.InstanceName)
+
+        # Check if database exists using Get-SqlDscDatabase
+        $sqlDatabaseObject = Get-SqlDscDatabase -ServerObject $ServerObject -Name $Name -Refresh:$Refresh -ErrorAction 'SilentlyContinue'
+
+        if ($sqlDatabaseObject)
+        {
+            return $true
+        }
+        else
+        {
+            return $false
+        }
+    }
+}

source/en-US/SqlServerDsc.strings.psd1

@@ -387,16 +387,8 @@ ConvertFrom-StringData @'
     Database_Remove_ShouldProcessCaption = Remove database from instance
     Remove_SqlDscDatabase_NotFound = Database '{0}' was not found.
 
-    ## Test-SqlDscDatabase
-    Database_Test = Testing the state of database '{0}' on instance '{1}'.
-    Database_InDesiredStatePresent = Database '{0}' is present and in desired state.
-    Database_InDesiredStateAbsent = Database '{0}' is absent as expected.
-    Database_NotInDesiredStatePresent = Expected the database '{0}' to be present, but it was absent.
-    Database_NotInDesiredStateAbsent = Expected the database '{0}' to be absent, but it was present.
-    Database_CollationWrong = The database '{0}' exists and has the collation '{1}', but expected it to have the collation '{2}'.
-    Database_CompatibilityLevelWrong = The database '{0}' exists and has the compatibility level '{1}', but expected it to have the compatibility level '{2}'.
-    Database_RecoveryModelWrong = The database '{0}' exists and has the recovery model '{1}', but expected it to have the recovery model '{2}'.
-    Database_OwnerNameWrong = The database '{0}' exists and has the owner '{1}', but expected it to have the owner '{2}'.
+    ## Test-SqlDscIsDatabase
+    IsDatabase_Test = Testing if database '{0}' exists on instance '{1}'. (TSID0001)
 
     ## Test-SqlDscDatabaseProperty
     DatabaseProperty_TestingProperties = Testing properties of database '{0}' on instance '{1}'. (TSDDP0001)

tests/Integration/Commands/README.md

@@ -92,7 +92,8 @@ Get-SqlDscDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTES
 ConvertFrom-SqlDscDatabasePermission | 4 | 0 (Prerequisites) | - | -
 New-SqlDscDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | SqlDscIntegrationTestDatabase_Persistent database
 Set-SqlDscDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
-Test-SqlDscDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
+Test-SqlDscIsDatabase | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
+Test-SqlDscDatabaseProperty | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Get-SqlDscDatabasePermission | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | Test database, Test user
 ConvertTo-SqlDscDatabasePermission | 4 | 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -
 Set-SqlDscDatabasePermission | 4 | 4 (New-SqlDscLogin), 1 (Install-SqlDscServer), 0 (Prerequisites) | DSCSQLTEST | -