New-DatabaseConnection
Published 31 July 2019
Creates an object that other SQL Change Automation cmdlets can use to connect to a database.
Syntax
New-DatabaseConnection -ServerInstance <string> -Database <string> [-Authentication <string>] [-Username <string>] [-Password <string>] [-TrustServerCertificate <bool>] [-Encrypt <bool>] [<CommonParameters>]
|
Description
The New-DatabaseConnection cmdlet creates a DatabaseConnection object that can be used by other SQL Change Automation cmdlets to connect to a database. The object contains the server instance, database name, and security credentials that cmdlets will use to connect to the database.
You can use Windows authentication or SQL Server authentication to connect to the database. If you use the Username and Password parameters, SQL Server authentication will be used. If you don't use those parameters, Windows authentication will be used; the account used to connect will be the account running PowerShell or the PowerShell script.
The cmdlets that can use the Database Connection object to connect to a database are Invoke-DatabaseBuild, New-DatabaseReleaseArtifact, Sync-DatabaseSchema, Test-DatabaseConnection and Use-DatabaseReleaseArtifact.
As an alternative to using this cmdlet, you may use a standard database connection string in place of a Database Connection object. The following connection string properties are supported: ApplicationIntent, Asynchronous Processing, AttachDbFilename, Connect Timeout, Context Connection, Current Language, Data Source, Encrypt, Enlist, Failover Partner, Initial Catalog, Integrated Security, Load Balance Timeout, Max Pool Size, Min Pool Size, MultipleActiveResultSets, MultiSubnetFailover, Network Library, Packet Size, Password, Persist Security Info, Replication, Transaction Binding, TrustServerCertificate, Type System Version, User ID, User Instance and Workstation ID.
Parameters
-ServerInstance
<System.String>
The name or network address of the SQL Server instance to connect to. For example, "staging01\sql2014". This is equivalent to the Data Source property of a connection string.
| Aliases | None |
| Required? | true |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-Database
<System.String>
The database to connect to, on the server specified in ServerInstance. This is equivalent to the Initial Catalog property of a connection string.
| Aliases | None |
| Required? | true |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-Authentication
<System.String>
The authentication method that will be used to connect to the server. Possible values are "IntegratedSecurity", "SqlAuthentication" or "ActiveDirectoryPassword". This parameter is optional. If this parameter is not specified, SqlAuthentication will be used if a username is provided, otherwise IntegratedSecurity will be used.
| Aliases | None |
| Required? | false |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-Username
<System.String>
The username for the SQL Server account cmdlets will use to connect to the database. This is equivalent to the User ID property of a connection string. This parameter is optional. If you specify a null or empty string, Windows Authentication will be used and the Password parameter will be ignored.
| Aliases | None |
| Required? | false |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-Password
<System.String>
The password for the SQL Server account cmdlets will use to connect to the database. This is equivalent to the Password property of a connection string. This parameter is optional. If left unspecified, it defaults to the empty string.
This parameter is ignored if the Username parameter is null or empty.
| Aliases | None |
| Required? | false |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-TrustServerCertificate
<System.Boolean>
Indicates if the server certificate should be verified when connecting using SSL encryption. In order to provide backwards compatibility, if this parameter is set to false then it may still be promoted to true if the target server connection is local under some circumstances. This parameter is optional. If left unspecified it uses Microsoft.Data.SqlClient defaults.
| Aliases | None |
| Required? | false |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
-Encrypt
<System.Boolean>
Indicates if the connection should be encrypted using SSL. This parameter is optional. If left unspecified it uses Microsoft.Data.SqlClient defaults.
| Aliases | None |
| Required? | false |
| Position? | named |
| Default Value | None |
| Accept Pipeline Input | false |
| Accept Wildcard Characters | false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see http://technet.microsoft.com/en-us/library/hh847884.aspx.
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
-
None.
You cannot pipe input to this cmdlet.
Return values
The output type is the type of the objects that the cmdlet emits.
- RedGate.Versioning.Automation.Compare.SchemaSources.DatabaseConnection
Examples
---------- EXAMPLE 1 ----------
|
This example shows how to create a Database Connection object. The object will use SQL Server authentication to connect to the database.
The New-DatabaseConnection cmdlet creates a Database Connection object, $staging. This can be used to connect to the database, Staging, on the SQL Server staging01\sql2014. Because the Username and Password parameters are provided, SQL Server authentication will be used to connect to Staging.
---------- EXAMPLE 2 ----------
|
This example shows how to create a Database Connection object that will use Windows authentication to connect to the database.
The New-DatabaseConnection cmdlet creates a Database Connection object, $staging. This can be used to connect to the database Staging on the SQL Server staging01\sql2014. Because no Username and Password are provided, Windows authentication will be used to connect to the database.
