Connect‑SqlDscDatabaseEngine

SYNOPSIS

Connect to a SQL Server Database Engine and return the server object.

SYNTAX

SqlServer (Default)

Connect-SqlDscDatabaseEngine [-ServerName <String>] [-InstanceName <String>] [-Protocol <String>]
 [-Port <UInt16>] [-StatementTimeout <Int32>] [-Encrypt] 
 [<CommonParameters>]

SqlServerWithCredential

Connect-SqlDscDatabaseEngine [-ServerName <String>] [-InstanceName <String>] -Credential <PSCredential>
 [-LoginType <String>] [-Protocol <String>] [-Port <UInt16>] [-StatementTimeout <Int32>] [-Encrypt]
 [<CommonParameters>]

DESCRIPTION

This command connects to a SQL Server Database Engine instance and returns the Server object.

EXAMPLES

EXAMPLE 1

Connect-SqlDscDatabaseEngine

Connects to the default instance on the local server.

EXAMPLE 2

Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'

Connects to the instance 'MyInstance' on the local server.

EXAMPLE 3

Connect-SqlDscDatabaseEngine -ServerName 'sql.company.local' -InstanceName 'MyInstance'

Connects to the instance 'MyInstance' on the server 'sql.company.local'.

EXAMPLE 4

Connect-SqlDscDatabaseEngine -Credential ([System.Management.Automation.PSCredential]::new('DOMAIN\SqlUser', (ConvertTo-SecureString -String 'MyP@ssw0rd1' -AsPlainText -Force)))

Connects to the default instance on the local server impersonating the Windows user 'DOMAIN\SqlUser'.

EXAMPLE 5

Connect-SqlDscDatabaseEngine -LoginType 'SqlLogin' -Credential ([System.Management.Automation.PSCredential]::new('sa', (ConvertTo-SecureString -String 'MyP@ssw0rd1' -AsPlainText -Force)))

Connects to the default instance on the local server using the SQL login 'sa'.

EXAMPLE 6

Connect-SqlDscDatabaseEngine -ServerName '192.168.1.1' -InstanceName 'MyInstance' -Protocol 'tcp' -Port 50200

Connects to the named instance 'MyInstance' on server '192.168.1.1' using TCP/IP on port 50200. The connection string format is 'tcp:192.168.1.1\MyInstance,50200'.

EXAMPLE 7

Connect-SqlDscDatabaseEngine -ServerName '192.168.1.1' -Protocol 'tcp' -Port 1433

Connects to the default instance on server '192.168.1.1' using TCP/IP on port 1433. The connection string format is 'tcp:192.168.1.1,1433'.

PARAMETERS

-Credential

The credentials to use to impersonate a user when connecting to the SQL Server Database Engine instance. If this parameter is left out, then the current user will be used to connect to the SQL Server Database Engine instance using Windows Integrated authentication.

Type: PSCredential
Parameter Sets: SqlServerWithCredential
Aliases: SetupCredential, DatabaseCredential

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Encrypt

Specifies if encryption should be used.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-InstanceName

String containing the SQL Server Database Engine instance to connect to. Default value is 'MSSQLSERVER'.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: MSSQLSERVER
Accept pipeline input: False
Accept wildcard characters: False

-LoginType

Specifies which type of logon credential should be used. The valid types are 'WindowsUser' or 'SqlLogin'. Default value is 'WindowsUser' If set to 'WindowsUser' then the it will impersonate using the Windows login specified in the parameter Credential. If set to 'SqlLogin' then it will impersonate using the native SQL login specified in the parameter Credential.

Type: String
Parameter Sets: SqlServerWithCredential
Aliases:

Required: False
Position: Named
Default value: WindowsUser
Accept pipeline input: False
Accept wildcard characters: False

-Port

Specifies the TCP port number to use when connecting to the SQL Server instance. This parameter is only applicable when connecting via TCP/IP (Protocol = 'tcp'). Valid values are 1-65535.

If not specified for a named instance, the SQL Server Browser service will be used to determine the port. For default instances, port 1433 is used by default.

Type: UInt16
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Protocol

Specifies the network protocol to use when connecting to the SQL Server instance. Valid values are 'tcp' for TCP/IP, 'np' for Named Pipes, and 'lpc' for Shared Memory.

If not specified, the connection will use the default protocol order configured on the client.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ServerName

String containing the host name of the SQL Server to connect to. Default value is the current computer name.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: (Get-ComputerName)
Accept pipeline input: False
Accept wildcard characters: False

-StatementTimeout

Set the query StatementTimeout in seconds. Default 600 seconds (10 minutes).

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 600
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

None.

OUTPUTS

Microsoft.SqlServer.Management.Smo.Server

Returns the SQL Server server object.

NOTES

The protocol values ('tcp', 'np', 'lpc') are lowercase to match the SQL Server connection string prefix format, e.g., 'tcp:ServerName\Instance,Port'.

RELATED LINKS