Set-SqlDscDatabaseProperty: Refactor command

CHANGELOG.md

@@ -10,9 +10,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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).
+- BREAKING CHANGE: `Set-SqlDscDatabase`
+  - Removed parameter `OwnerName` [issue #2177](https://github.com/dsccommunity/SqlServerDsc/issues/2177).
+    Use the new command `Set-SqlDscDatabaseOwner` to change database ownership instead.
 
 ### Added
 
+- Added public command `Set-SqlDscDatabaseOwner` to change the owner of a SQL Server
+  database [issue #2177](https://github.com/dsccommunity/SqlServerDsc/issues/2177).
+  This command uses the SMO `SetOwner()` method and supports both `ServerObject`
+  and `DatabaseObject` parameter sets. This replaces the ownership changes
+  previously done via the `OwnerName` parameter in `Set-SqlDscDatabase`.
 - 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
@@ -220,6 +228,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- BREAKING CHANGE: `Set-SqlDscDatabase` has been renamed to `Set-SqlDscDatabaseProperty`
+  to better reflect its purpose of setting database properties. All existing references
+  should be updated to use the new name.
+- `Set-SqlDscDatabaseProperty` (formerly `Set-SqlDscDatabase`)
+  - BREAKING CHANGE: Completely refactored to support settable SMO Database
+    properties as parameters ([issue #2177](https://github.com/dsccommunity/SqlServerDsc/issues/2177)).
 - `Remove-SqlDscAgentAlert`
   - Now uses `$PSCmdlet.ThrowTerminatingError()` instead of exception helper
     functions for proper terminating error handling ([issue #2193](https://github.com/dsccommunity/SqlServerDsc/issues/2193)).
@@ -235,7 +249,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `New-SqlDscDatabase`
   - Now uses `$PSCmdlet.ThrowTerminatingError()` instead of exception helper
     functions for proper terminating error handling ([issue #2200](https://github.com/dsccommunity/SqlServerDsc/issues/2200)).
-- `Set-SqlDscDatabase`
+- `Set-SqlDscDatabaseProperty` (formerly `Set-SqlDscDatabase`)
   - Now uses `$PSCmdlet.ThrowTerminatingError()` instead of exception helper
     functions for proper terminating error handling ([issue #2198](https://github.com/dsccommunity/SqlServerDsc/issues/2198)).
 - `Add-SqlDscTraceFlag`

azure-pipelines.yml

@@ -335,7 +335,9 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscDatabase.Integration.Tests.ps1'
                   '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/Get-SqlDscCompatibilityLevel.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Set-SqlDscDatabaseProperty.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Set-SqlDscDatabaseOwner.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'

source/Public/Get-SqlDscCompatibilityLevel.ps1

@@ -0,0 +1,138 @@
+<#
+    .SYNOPSIS
+        Gets the supported database compatibility levels for a SQL Server instance or version.
+
+    .DESCRIPTION
+        This command returns the supported database compatibility levels for a SQL Server
+        Database Engine instance or a specific SQL Server version.
+
+        The compatibility levels are determined based on the SQL Server version, following
+        the official Microsoft documentation for supported compatibility level ranges.
+
+    .PARAMETER ServerObject
+        Specifies the SQL Server connection object to get supported compatibility levels for.
+
+    .PARAMETER Version
+        Specifies the SQL Server version to get supported compatibility levels for.
+        Only the major version number is used for determining compatibility levels.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        Get-SqlDscCompatibilityLevel -ServerObject $serverObject
+
+        Returns all supported compatibility levels for the connected SQL Server instance.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Get-SqlDscCompatibilityLevel
+
+        Returns all supported compatibility levels using pipeline input.
+
+    .EXAMPLE
+        Get-SqlDscCompatibilityLevel -Version '16.0.1000.6'
+
+        Returns all supported compatibility levels for SQL Server 2022 (version 16).
+
+    .INPUTS
+        Microsoft.SqlServer.Management.Smo.Server
+
+        The server object to get supported compatibility levels for.
+
+    .OUTPUTS
+        System.String[]
+
+        Returns an array of supported compatibility level names (e.g., 'Version160', 'Version150').
+#>
+function Get-SqlDscCompatibilityLevel
+{
+    [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.')]
+    [CmdletBinding(DefaultParameterSetName = 'ServerObject')]
+    [OutputType([System.String[]])]
+    param
+    (
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(ParameterSetName = 'Version', Mandatory = $true)]
+        [System.Version]
+        $Version
+    )
+
+    process
+    {
+        # Get the major version based on parameter set
+        $majorVersion = if ($PSCmdlet.ParameterSetName -eq 'ServerObject')
+        {
+            Write-Verbose -Message ($script:localizedData.GetCompatibilityLevel_GettingForInstance -f $ServerObject.InstanceName, $ServerObject.VersionMajor)
+            $ServerObject.VersionMajor
+        }
+        else
+        {
+            Write-Verbose -Message ($script:localizedData.GetCompatibilityLevel_GettingForVersion -f $Version, $Version.Major)
+            $Version.Major
+        }
+
+        # Get all available compatibility levels from the enum
+        $allCompatibilityLevels = [System.Enum]::GetNames([Microsoft.SqlServer.Management.Smo.CompatibilityLevel])
+
+        <#
+            Determine minimum supported compatibility level based on SQL Server version
+            Reference: https://learn.microsoft.com/en-us/sql/t-sql/statements/alter-database-transact-sql-compatibility-level
+        #>
+        $minimumCompatLevel = switch ($majorVersion)
+        {
+            { $_ -ge 12 }
+            {
+                100 # SQL 2014 (v12) and later support minimum compat level 100
+            }
+
+            11
+            {
+                90 # SQL 2012 (v11) supports minimum compat level 90
+            }
+
+            { $_ -le 10 }
+            {
+                80 # SQL 2008 R2 (v10.5) and earlier support minimum compat level 80
+            }
+        }
+
+        <#
+            Filter compatibility levels that are supported by this SQL Server version
+            CompatibilityLevel enum values are named like "Version80", "Version90", etc.
+            SQL Server supports compatibility levels from the minimum up to (version * 10)
+        #>
+        $supportedCompatibilityLevels = $allCompatibilityLevels | Where-Object -FilterScript {
+            if ($_ -match 'Version(\d+)')
+            {
+                $compatLevelVersion = [System.Int32] $Matches[1]
+                ($compatLevelVersion -ge $minimumCompatLevel) -and ($compatLevelVersion -le ($majorVersion * 10))
+            }
+            else
+            {
+                $false
+            }
+        }
+
+        <#
+            Warn if SQL Server version is newer than what SMO library supports
+            Check if the expected maximum compatibility level is missing from the supported list
+        #>
+        $expectedMaxCompatLevel = "Version$($majorVersion * 10)"
+        if ($expectedMaxCompatLevel -notin $supportedCompatibilityLevels -and $supportedCompatibilityLevels.Count -gt 0)
+        {
+            # Get the actual maximum from the last element (they're in ascending order)
+            $lastCompatLevel = $supportedCompatibilityLevels[-1]
+            if ($lastCompatLevel -match 'Version(\d+)')
+            {
+                $maxCompatLevelInEnum = [System.Int32] $Matches[1]
+                Write-Warning -Message ($script:localizedData.GetCompatibilityLevel_SmoTooOld -f $majorVersion, $maxCompatLevelInEnum, ($majorVersion * 10))
+            }
+        }
+
+        Write-Debug -Message ($script:localizedData.GetCompatibilityLevel_Found -f $supportedCompatibilityLevels.Count, $majorVersion)
+
+        return $supportedCompatibilityLevels
+    }
+}

source/Public/Get-SqlDscDatabase.ps1

@@ -88,6 +88,12 @@ function Get-SqlDscDatabase
             }
             else
             {
+                if ($Refresh.IsPresent)
+                {
+                    # Refresh the database object
+                    $databaseObject.Refresh()
+                }
+
                 Write-Verbose -Message ($script:localizedData.Database_Found -f $Name)
             }
         }

source/Public/New-SqlDscDatabase.ps1

@@ -15,6 +15,12 @@
         The name of the SQL collation to use for the new database.
         Default value is server collation.
 
+    .PARAMETER CatalogCollation
+        Specifies the collation type for the system catalog. Valid values are
+        DATABASE_DEFAULT and SQL_Latin1_General_CP1_CI_AS. This property can
+        only be set during database creation and cannot be modified afterward.
+        This parameter requires SQL Server 2019 (version 15) or later.
+
     .PARAMETER CompatibilityLevel
         The version of the SQL compatibility level to use for the new database.
         Default value is server version.
@@ -73,6 +79,10 @@ function New-SqlDscDatabase
         [System.String]
         $Collation,
 
+        [Parameter()]
+        [Microsoft.SqlServer.Management.Smo.CatalogCollationType]
+        $CatalogCollation,
+
         [Parameter()]
         [ValidateSet('Version80', 'Version90', 'Version100', 'Version110', 'Version120', 'Version130', 'Version140', 'Version150', 'Version160')]
         [System.String]
@@ -177,6 +187,24 @@ function New-SqlDscDatabase
             }
         }
 
+        # Validate CatalogCollation if specified (requires SQL Server 2019+)
+        if ($PSBoundParameters.ContainsKey('CatalogCollation'))
+        {
+            if ($ServerObject.VersionMajor -lt 15)
+            {
+                $errorMessage = $script:localizedData.Database_CatalogCollationNotSupported -f $ServerObject.InstanceName, $ServerObject.VersionMajor
+
+                $PSCmdlet.ThrowTerminatingError(
+                    [System.Management.Automation.ErrorRecord]::new(
+                        [System.InvalidOperationException]::new($errorMessage),
+                        'NSD0005', # cspell: disable-line
+                        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                        $CatalogCollation
+                    )
+                )
+            }
+        }
+
         $verboseDescriptionMessage = $script:localizedData.Database_Create_ShouldProcessVerboseDescription -f $Name, $ServerObject.InstanceName
         $verboseWarningMessage = $script:localizedData.Database_Create_ShouldProcessVerboseWarning -f $Name
         $captionMessage = $script:localizedData.Database_Create_ShouldProcessCaption
@@ -197,6 +225,11 @@ function New-SqlDscDatabase
                     $sqlDatabaseObjectToCreate.Collation = $Collation
                 }
 
+                if ($PSBoundParameters.ContainsKey('CatalogCollation'))
+                {
+                    $sqlDatabaseObjectToCreate.CatalogCollation = $CatalogCollation
+                }
+
                 if ($PSBoundParameters.ContainsKey('CompatibilityLevel'))
                 {
                     $sqlDatabaseObjectToCreate.CompatibilityLevel = $CompatibilityLevel