Skip to content

Commit 6416b4e

Browse files
andreasjordanandreasjordan
authored
Add Compare-DbaLogin command (#10319)
1 parent db77a34 commit 6416b4e

4 files changed

Lines changed: 241 additions & 0 deletions

File tree

‎dbatools.psd1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
'Compare-DbaAgReplicaAgentJob',
8585
'Compare-DbaAgReplicaCredential',
8686
'Compare-DbaAgReplicaLogin',
87+
'Compare-DbaLogin',
8788
'Compare-DbaAgReplicaOperator',
8889
'Compare-DbaAgReplicaSync',
8990
'Compare-DbaAvailabilityGroup',

‎dbatools.psm1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,7 @@ if ($PSVersionTable.PSVersion.Major -lt 5) {
460460
'Compare-DbaAgReplicaAgentJob',
461461
'Compare-DbaAgReplicaCredential',
462462
'Compare-DbaAgReplicaLogin',
463+
'Compare-DbaLogin',
463464
'Compare-DbaAgReplicaOperator',
464465
'Compare-DbaAgReplicaSync',
465466
'Compare-DbaAvailabilityGroup',

‎public/Compare-DbaLogin.ps1‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
function Compare-DbaLogin {
2+
<#
3+
.SYNOPSIS
4+
Compares SQL Server logins between a source and one or more destination instances.
5+
6+
.DESCRIPTION
7+
Compares SQL Server logins between a source instance and one or more destination instances to identify which logins exist only on the source, only on the destination, or on both. This is useful for identifying logins that would be lost when using Copy-DbaLogin with -Force, or for auditing login consistency between environments.
8+
9+
Returns one object per login per destination instance, indicating whether the login exists on the source, destination, or both.
10+
11+
.PARAMETER Source
12+
The source SQL Server instance.
13+
14+
.PARAMETER SourceSqlCredential
15+
Login to the source instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
16+
17+
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
18+
19+
For MFA support, please use Connect-DbaInstance.
20+
21+
.PARAMETER Destination
22+
The destination SQL Server instance or instances.
23+
24+
.PARAMETER DestinationSqlCredential
25+
Login to the destination instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
26+
27+
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
28+
29+
For MFA support, please use Connect-DbaInstance.
30+
31+
.PARAMETER Login
32+
Specifies one or more logins to include in the comparison. All other logins are excluded.
33+
34+
.PARAMETER ExcludeLogin
35+
Specifies one or more logins to exclude from the comparison.
36+
37+
.PARAMETER ExcludeSystemLogin
38+
Excludes built-in system logins from the comparison results.
39+
40+
.PARAMETER EnableException
41+
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
42+
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
43+
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
44+
45+
.NOTES
46+
Tags: Login, Security, Compare
47+
Author: the dbatools team + Claude
48+
49+
Website: https://dbatools.io
50+
Copyright: (c) 2026 by dbatools, licensed under MIT
51+
License: MIT https://opensource.org/licenses/MIT
52+
53+
.LINK
54+
https://dbatools.io/Compare-DbaLogin
55+
56+
.OUTPUTS
57+
PSCustomObject
58+
59+
Returns one object for each login found on either the source or destination instance.
60+
61+
Properties:
62+
- SourceServer: The name of the source SQL Server instance
63+
- DestinationServer: The name of the destination SQL Server instance
64+
- LoginName: The name of the login account
65+
- LoginType: The login type (SqlLogin, WindowsUser, WindowsGroup, etc.)
66+
- Status: Indicates where the login exists - "SourceOnly", "DestinationOnly", or "Both"
67+
68+
.EXAMPLE
69+
PS C:\> Compare-DbaLogin -Source sql1 -Destination sql2
70+
71+
Compares all logins between sql1 and sql2, returning the status of each login.
72+
73+
.EXAMPLE
74+
PS C:\> Compare-DbaLogin -Source sql1 -Destination sql2 | Where-Object Status -eq "DestinationOnly"
75+
76+
Returns logins that exist on sql2 but not on sql1. These logins would be lost if Copy-DbaLogin -Force were run from sql1 to sql2.
77+
78+
.EXAMPLE
79+
PS C:\> Compare-DbaLogin -Source sql1 -Destination sql2 | Where-Object Status -eq "SourceOnly"
80+
81+
Returns logins that exist on sql1 but not on sql2. These are the logins that Copy-DbaLogin would create.
82+
83+
.EXAMPLE
84+
PS C:\> Compare-DbaLogin -Source sql1 -Destination sql2 -ExcludeSystemLogin
85+
86+
Compares user-created logins between sql1 and sql2, excluding built-in system logins.
87+
88+
.EXAMPLE
89+
PS C:\> Compare-DbaLogin -Source sql1 -Destination sql2, sql3 -Login 'appuser', 'reportuser'
90+
91+
Compares the specified logins between sql1 and both sql2 and sql3.
92+
#>
93+
[CmdletBinding()]
94+
param (
95+
[Parameter(Mandatory)]
96+
[DbaInstanceParameter]$Source,
97+
[PSCredential]$SourceSqlCredential,
98+
[Parameter(Mandatory)]
99+
[DbaInstanceParameter[]]$Destination,
100+
[PSCredential]$DestinationSqlCredential,
101+
[string[]]$Login,
102+
[string[]]$ExcludeLogin,
103+
[switch]$ExcludeSystemLogin,
104+
[switch]$EnableException
105+
)
106+
107+
begin {
108+
try {
109+
$sourceServer = Connect-DbaInstance -SqlInstance $Source -SqlCredential $SourceSqlCredential
110+
} catch {
111+
Stop-Function -Message "Failure connecting to $Source" -Category ConnectionError -ErrorRecord $_ -Target $Source
112+
return
113+
}
114+
115+
$splatGetSource = @{
116+
SqlInstance = $sourceServer
117+
ExcludeSystemLogin = $ExcludeSystemLogin
118+
}
119+
if ($Login) {
120+
$splatGetSource["Login"] = $Login
121+
}
122+
if ($ExcludeLogin) {
123+
$splatGetSource["ExcludeLogin"] = $ExcludeLogin
124+
}
125+
$sourceLogins = Get-DbaLogin @splatGetSource
126+
}
127+
128+
process {
129+
if (Test-FunctionInterrupt) { return }
130+
131+
foreach ($destInstance in $Destination) {
132+
try {
133+
$destServer = Connect-DbaInstance -SqlInstance $destInstance -SqlCredential $DestinationSqlCredential
134+
} catch {
135+
Stop-Function -Message "Failure connecting to $destInstance" -Category ConnectionError -ErrorRecord $_ -Target $destInstance -Continue
136+
}
137+
138+
$splatGetDest = @{
139+
SqlInstance = $destServer
140+
ExcludeSystemLogin = $ExcludeSystemLogin
141+
}
142+
if ($Login) {
143+
$splatGetDest["Login"] = $Login
144+
}
145+
if ($ExcludeLogin) {
146+
$splatGetDest["ExcludeLogin"] = $ExcludeLogin
147+
}
148+
$destLogins = Get-DbaLogin @splatGetDest
149+
150+
$allLoginNames = New-Object System.Collections.ArrayList
151+
foreach ($srcLogin in $sourceLogins) {
152+
if ($srcLogin.Name -notin $allLoginNames) {
153+
$null = $allLoginNames.Add($srcLogin.Name)
154+
}
155+
}
156+
foreach ($dstLogin in $destLogins) {
157+
if ($dstLogin.Name -notin $allLoginNames) {
158+
$null = $allLoginNames.Add($dstLogin.Name)
159+
}
160+
}
161+
162+
foreach ($loginName in $allLoginNames) {
163+
$srcLogin = $sourceLogins | Where-Object Name -eq $loginName
164+
$dstLogin = $destLogins | Where-Object Name -eq $loginName
165+
166+
if ($srcLogin -and $dstLogin) {
167+
$status = "Both"
168+
} elseif ($srcLogin) {
169+
$status = "SourceOnly"
170+
} else {
171+
$status = "DestinationOnly"
172+
}
173+
174+
[PSCustomObject]@{
175+
SourceServer = $sourceServer.Name
176+
DestinationServer = $destServer.Name
177+
LoginName = $loginName
178+
LoginType = if ($srcLogin) { $srcLogin.LoginType } else { $dstLogin.LoginType }
179+
Status = $status
180+
}
181+
}
182+
}
183+
}
184+
}

‎tests/Compare-DbaLogin.Tests.ps1‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
2+
param(
3+
$ModuleName = "dbatools",
4+
$CommandName = "Compare-DbaLogin",
5+
$PSDefaultParameterValues = $TestConfig.Defaults
6+
)
7+
8+
Describe $CommandName -Tag UnitTests {
9+
Context "Parameter validation" {
10+
It "Should have the expected parameters" {
11+
$hasParameters = (Get-Command $CommandName).Parameters.Values.Name | Where-Object { $PSItem -notin ("WhatIf", "Confirm") }
12+
$expectedParameters = $TestConfig.CommonParameters
13+
$expectedParameters += @(
14+
"Source",
15+
"SourceSqlCredential",
16+
"Destination",
17+
"DestinationSqlCredential",
18+
"Login",
19+
"ExcludeLogin",
20+
"ExcludeSystemLogin",
21+
"EnableException"
22+
)
23+
Compare-Object -ReferenceObject $expectedParameters -DifferenceObject $hasParameters | Should -BeNullOrEmpty
24+
}
25+
}
26+
}
27+
28+
Describe $CommandName -Tag IntegrationTests {
29+
BeforeAll {
30+
$PSDefaultParameterValues["*-Dba*:EnableException"] = $true
31+
32+
$loginName = "dbatoolsci_comparelogin_$(Get-Random)"
33+
34+
$null = New-DbaLogin -SqlInstance $TestConfig.InstanceMulti2 -Login $loginName -SecurePassword (ConvertTo-SecureString "Password1234!" -AsPlainText -Force)
35+
36+
$PSDefaultParameterValues.Remove("*-Dba*:EnableException")
37+
}
38+
39+
AfterAll {
40+
$PSDefaultParameterValues["*-Dba*:EnableException"] = $true
41+
42+
$null = Remove-DbaLogin -SqlInstance $TestConfig.InstanceMulti2 -Login $loginName
43+
44+
$PSDefaultParameterValues.Remove("*-Dba*:EnableException")
45+
}
46+
47+
Context "When comparing logins between instances" {
48+
It "Returns a result with a DestinationOnly login" {
49+
$result = Compare-DbaLogin -Source $TestConfig.InstanceMulti1 -Destination $TestConfig.InstanceMulti2 -Login $loginName
50+
$result | Should -Not -BeNullOrEmpty
51+
$result.LoginName | Should -Be $loginName
52+
$result.Status | Should -Be "DestinationOnly"
53+
}
54+
}
55+
}

0 commit comments

Comments
 (0)