Skip to content

Commit 6afc970

Browse files
github-actions[bot]andreasjordan
github-actions[bot]
and
andreasjordan
committed
Add-DbaInstanceList, Get-DbaInstanceList, Remove-DbaInstanceList - Add manual instance autocomplete list
Adds three new commands for managing a user-maintained list of SQL Server instance names that are pre-loaded into the dbatools TEPP (tab expansion++) cache for the -SqlInstance parameter. This allows users to have frequently used instances available for autocomplete in their PowerShell terminal without needing to connect to them first. Also supports loading instances from the $env:DBATOOLS_KNOWN_INSTANCES environment variable (comma-separated) for easy profile-based setup. Closes #8918 (do *InstanceList*) Co-authored-by: Andreas Jordan <andreasjordan@users.noreply.github.com>
1 parent 97d03be commit 6afc970

9 files changed

Lines changed: 404 additions & 2 deletions

‎dbatools.psd1‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -759,7 +759,10 @@
759759
'New-DbaReplSubscription',
760760
'Remove-DbaReplSubscription',
761761
'New-DbaReplCreationScriptOptions',
762-
'Get-DbaReplSubscription'
762+
'Get-DbaReplSubscription',
763+
'Add-DbaInstanceList',
764+
'Get-DbaInstanceList',
765+
'Remove-DbaInstanceList'
763766
)
764767

765768
# Cmdlets to export from this module

‎dbatools.psm1‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -939,7 +939,10 @@ if ($PSVersionTable.PSVersion.Major -lt 5) {
939939
'Invoke-DbaDbAzSqlTip',
940940
'New-DbaAgentAlert',
941941
'Set-DbatoolsInsecureConnection',
942-
'Test-DbaAgSpn'
942+
'Test-DbaAgSpn',
943+
'Add-DbaInstanceList',
944+
'Get-DbaInstanceList',
945+
'Remove-DbaInstanceList'
943946
)
944947
$script:noncoresmo = @(
945948
# SMO issues

‎private/dynamicparams/sqlinstance.ps1‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,23 @@
22
if (-not [Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"]) {
33
[Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] = @()
44
}
5+
6+
# Load user-defined instances from config (set via Add-DbaInstanceList)
7+
foreach ($instance in (Get-DbatoolsConfigValue -FullName "TabExpansion.KnownInstances" -Fallback @())) {
8+
if ($instance -and [Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] -notcontains $instance) {
9+
[Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] += $instance
10+
}
11+
}
12+
13+
# Load from environment variable (comma-separated list, e.g. set in PowerShell profile)
14+
if ($env:DBATOOLS_KNOWN_INSTANCES) {
15+
foreach ($instance in ($env:DBATOOLS_KNOWN_INSTANCES -split ",")) {
16+
$lower = $instance.Trim().ToLowerInvariant()
17+
if ($lower -and [Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] -notcontains $lower) {
18+
[Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] += $lower
19+
}
20+
}
21+
}
522
#endregion Initialize Cache
623

724
#region Tepp Data return

‎public/Add-DbaInstanceList.ps1‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
function Add-DbaInstanceList {
2+
<#
3+
.SYNOPSIS
4+
Adds one or more SQL Server instances to the user-maintained autocomplete list.
5+
6+
.DESCRIPTION
7+
Adds SQL Server instance names to a persistent list that pre-populates the tab completion
8+
cache for the -SqlInstance parameter across all dbatools commands. This allows users to
9+
have their frequently used instances available for autocomplete in their PowerShell
10+
terminal without needing to connect to them first.
11+
12+
The instance list is stored using the dbatools configuration system. Use -Register to
13+
persist the list across PowerShell sessions.
14+
15+
Instances can also be pre-loaded at module import time by setting the
16+
$env:DBATOOLS_KNOWN_INSTANCES environment variable to a comma-separated list of instance
17+
names in your PowerShell profile.
18+
19+
.PARAMETER SqlInstance
20+
The SQL Server instance name or names to add to the autocomplete list.
21+
Accepts pipeline input.
22+
23+
.PARAMETER Register
24+
Persists the instance list to disk so it is available in future PowerShell sessions.
25+
Without this switch, the list only exists for the current session.
26+
27+
.PARAMETER Scope
28+
Determines where the persistent configuration is stored when using -Register.
29+
UserDefault stores the setting for the current user only.
30+
31+
.OUTPUTS
32+
None
33+
34+
This command updates the autocomplete cache but does not output any objects to the
35+
pipeline. Use Get-DbaInstanceList to retrieve the configured instance names.
36+
37+
.NOTES
38+
Tags: TabCompletion, Autocomplete
39+
Author: the dbatools team + Claude
40+
41+
Website: https://dbatools.io
42+
Copyright: (c) 2018 by dbatools, licensed under MIT
43+
License: MIT https://opensource.org/licenses/MIT
44+
45+
.LINK
46+
https://dbatools.io/Add-DbaInstanceList
47+
48+
.EXAMPLE
49+
PS C:\> Add-DbaInstanceList -SqlInstance "sql01", "sql02\dev"
50+
51+
Adds sql01 and sql02\dev to the autocomplete instance list for the current session.
52+
53+
.EXAMPLE
54+
PS C:\> Add-DbaInstanceList -SqlInstance "sql01" -Register
55+
56+
Adds sql01 to the autocomplete instance list and persists it across PowerShell sessions.
57+
58+
.EXAMPLE
59+
PS C:\> "sql01", "sql02" | Add-DbaInstanceList -Register
60+
61+
Adds two instances to the list via pipeline and persists them across sessions.
62+
#>
63+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
64+
[CmdletBinding()]
65+
param (
66+
[Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
67+
[string[]]$SqlInstance,
68+
[switch]$Register,
69+
[Dataplat.Dbatools.Configuration.ConfigScope]$Scope = [Dataplat.Dbatools.Configuration.ConfigScope]::UserDefault
70+
)
71+
72+
begin {
73+
$current = Get-DbatoolsConfigValue -FullName "TabExpansion.KnownInstances" -Fallback @()
74+
$toAdd = @()
75+
}
76+
77+
process {
78+
foreach ($instance in $SqlInstance) {
79+
$lower = $instance.Trim().ToLowerInvariant()
80+
if (-not $lower) { continue }
81+
82+
if ($current -notcontains $lower -and $toAdd -notcontains $lower) {
83+
$toAdd += $lower
84+
}
85+
86+
# Update the TEPP cache immediately for this session
87+
if ([Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] -notcontains $lower) {
88+
[Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"] += $lower
89+
}
90+
}
91+
}
92+
93+
end {
94+
if ($toAdd.Count -gt 0) {
95+
$combined = @($current) + @($toAdd)
96+
Set-DbatoolsConfig -FullName "TabExpansion.KnownInstances" -Value $combined
97+
}
98+
if ($Register) {
99+
Register-DbatoolsConfig -FullName "TabExpansion.KnownInstances" -Scope $Scope
100+
}
101+
}
102+
}

‎public/Get-DbaInstanceList.ps1‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
function Get-DbaInstanceList {
2+
<#
3+
.SYNOPSIS
4+
Returns the user-maintained list of SQL Server instances used for tab completion.
5+
6+
.DESCRIPTION
7+
Returns all SQL Server instance names from the user-maintained list that is pre-loaded
8+
into the dbatools tab completion cache for the -SqlInstance parameter. This list allows
9+
users to have their frequently used instances available for autocomplete in their
10+
PowerShell terminal without needing to connect to them first.
11+
12+
Use Add-DbaInstanceList to add instances to the list and Remove-DbaInstanceList to
13+
remove them.
14+
15+
Instances can also be pre-loaded at module import time by setting the
16+
$env:DBATOOLS_KNOWN_INSTANCES environment variable to a comma-separated list of instance
17+
names in your PowerShell profile.
18+
19+
.OUTPUTS
20+
System.String
21+
22+
Returns instance names as strings. Each instance name in the user-maintained
23+
autocomplete list is returned as a separate string object.
24+
25+
.NOTES
26+
Tags: TabCompletion, Autocomplete
27+
Author: the dbatools team + Claude
28+
29+
Website: https://dbatools.io
30+
Copyright: (c) 2018 by dbatools, licensed under MIT
31+
License: MIT https://opensource.org/licenses/MIT
32+
33+
.LINK
34+
https://dbatools.io/Get-DbaInstanceList
35+
36+
.EXAMPLE
37+
PS C:\> Get-DbaInstanceList
38+
39+
Returns all instance names from the user-maintained autocomplete list.
40+
41+
.EXAMPLE
42+
PS C:\> Get-DbaInstanceList | Remove-DbaInstanceList
43+
44+
Removes all instances from the user-maintained autocomplete list.
45+
#>
46+
[CmdletBinding()]
47+
param ()
48+
49+
process {
50+
Get-DbatoolsConfigValue -FullName "TabExpansion.KnownInstances" -Fallback @()
51+
}
52+
}

‎public/Remove-DbaInstanceList.ps1‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
function Remove-DbaInstanceList {
2+
<#
3+
.SYNOPSIS
4+
Removes one or more SQL Server instances from the user-maintained autocomplete list.
5+
6+
.DESCRIPTION
7+
Removes SQL Server instance names from the user-maintained list that is pre-loaded into
8+
the dbatools tab completion cache for the -SqlInstance parameter. The instances are
9+
removed from the stored configuration but remain in the current session's TEPP cache
10+
until the module is reloaded.
11+
12+
Use Add-DbaInstanceList to add instances to the list and Get-DbaInstanceList to view
13+
the current list.
14+
15+
.PARAMETER SqlInstance
16+
The SQL Server instance name or names to remove from the autocomplete list.
17+
Accepts pipeline input.
18+
19+
.PARAMETER Register
20+
Persists the updated instance list to disk after removal so the change is available in
21+
future PowerShell sessions. Without this switch, the removal only affects the stored
22+
configuration for the current session.
23+
24+
.PARAMETER Scope
25+
Determines where the persistent configuration is stored when using -Register.
26+
UserDefault stores the setting for the current user only.
27+
28+
.OUTPUTS
29+
None
30+
31+
This command updates the stored configuration but does not output any objects to the
32+
pipeline. Use Get-DbaInstanceList to retrieve the current configured instance names.
33+
34+
.NOTES
35+
Tags: TabCompletion, Autocomplete
36+
Author: the dbatools team + Claude
37+
38+
Website: https://dbatools.io
39+
Copyright: (c) 2018 by dbatools, licensed under MIT
40+
License: MIT https://opensource.org/licenses/MIT
41+
42+
.LINK
43+
https://dbatools.io/Remove-DbaInstanceList
44+
45+
.EXAMPLE
46+
PS C:\> Remove-DbaInstanceList -SqlInstance "sql01"
47+
48+
Removes sql01 from the autocomplete instance list.
49+
50+
.EXAMPLE
51+
PS C:\> Remove-DbaInstanceList -SqlInstance "sql01", "sql02\dev" -Register
52+
53+
Removes two instances from the list and persists the change across PowerShell sessions.
54+
55+
.EXAMPLE
56+
PS C:\> Get-DbaInstanceList | Remove-DbaInstanceList -Register
57+
58+
Removes all instances from the user-maintained autocomplete list and persists the change.
59+
#>
60+
[CmdletBinding(SupportsShouldProcess)]
61+
param (
62+
[Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
63+
[string[]]$SqlInstance,
64+
[switch]$Register,
65+
[Dataplat.Dbatools.Configuration.ConfigScope]$Scope = [Dataplat.Dbatools.Configuration.ConfigScope]::UserDefault
66+
)
67+
68+
begin {
69+
$current = @(Get-DbatoolsConfigValue -FullName "TabExpansion.KnownInstances" -Fallback @())
70+
$toRemove = @()
71+
}
72+
73+
process {
74+
foreach ($instance in $SqlInstance) {
75+
$lower = $instance.Trim().ToLowerInvariant()
76+
if (-not $lower) { continue }
77+
if ($toRemove -notcontains $lower) {
78+
$toRemove += $lower
79+
}
80+
}
81+
}
82+
83+
end {
84+
if ($toRemove.Count -gt 0) {
85+
if ($PSCmdlet.ShouldProcess("instance list", "Remove $($toRemove -join ', ')")) {
86+
$updated = $current | Where-Object { $toRemove -notcontains $_ }
87+
if ($null -eq $updated) { $updated = @() }
88+
Set-DbatoolsConfig -FullName "TabExpansion.KnownInstances" -Value @($updated)
89+
if ($Register) {
90+
Register-DbatoolsConfig -FullName "TabExpansion.KnownInstances" -Scope $Scope
91+
}
92+
}
93+
}
94+
}
95+
}

‎tests/Add-DbaInstanceList.Tests.ps1‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
#Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
2+
param(
3+
$ModuleName = "dbatools",
4+
$CommandName = "Add-DbaInstanceList",
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+
"SqlInstance",
15+
"Register",
16+
"Scope"
17+
)
18+
Compare-Object -ReferenceObject $expectedParameters -DifferenceObject $hasParameters | Should -BeNullOrEmpty
19+
}
20+
}
21+
}
22+
23+
Describe $CommandName -Tag IntegrationTests {
24+
BeforeAll {
25+
$instanceName = "dbatoolsci_testinstance_$(Get-Random)"
26+
}
27+
28+
AfterAll {
29+
$null = Remove-DbaInstanceList -SqlInstance $instanceName -Confirm:$false -ErrorAction SilentlyContinue
30+
}
31+
32+
Context "adds instances to the list" {
33+
It "adds an instance without error" {
34+
{ Add-DbaInstanceList -SqlInstance $instanceName } | Should -Not -Throw
35+
}
36+
37+
It "instance appears in Get-DbaInstanceList after adding" {
38+
$result = Get-DbaInstanceList
39+
$result | Should -Contain $instanceName.ToLowerInvariant()
40+
}
41+
42+
It "instance appears in the TEPP cache after adding" {
43+
$cache = [Dataplat.Dbatools.TabExpansion.TabExpansionHost]::Cache["sqlinstance"]
44+
$cache | Should -Contain $instanceName.ToLowerInvariant()
45+
}
46+
47+
It "does not add duplicates" {
48+
Add-DbaInstanceList -SqlInstance $instanceName
49+
$result = Get-DbaInstanceList
50+
($result | Where-Object { $PSItem -eq $instanceName.ToLowerInvariant() }).Count | Should -Be 1
51+
}
52+
}
53+
}

‎tests/Get-DbaInstanceList.Tests.ps1‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
2+
param(
3+
$ModuleName = "dbatools",
4+
$CommandName = "Get-DbaInstanceList",
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+
Compare-Object -ReferenceObject $expectedParameters -DifferenceObject $hasParameters | Should -BeNullOrEmpty
14+
}
15+
}
16+
}
17+
18+
Describe $CommandName -Tag IntegrationTests {
19+
BeforeAll {
20+
$instanceName = "dbatoolsci_testinstance_$(Get-Random)"
21+
Add-DbaInstanceList -SqlInstance $instanceName
22+
}
23+
24+
AfterAll {
25+
$null = Remove-DbaInstanceList -SqlInstance $instanceName -Confirm:$false -ErrorAction SilentlyContinue
26+
}
27+
28+
Context "returns the instance list" {
29+
It "returns results without error" {
30+
{ Get-DbaInstanceList } | Should -Not -Throw
31+
}
32+
33+
It "returns the added instance" {
34+
$result = Get-DbaInstanceList
35+
$result | Should -Contain $instanceName.ToLowerInvariant()
36+
}
37+
}
38+
}

0 commit comments

Comments
 (0)