2.2 Keys and Values

  • Article

The following table provides a list of all keys accepted as a SqlClient Connection String.

Keyword

Description

Addr

Synonym of the Data Source key.

Address

Synonym of the Data Source key.

App

Synonym of the Application Name key.

ApplicationIntent

When the value of this key is set to "ReadOnly", the client MUST request a read workload when connecting to an AlwaysOn-enabled database.

The value of this key MUST be "ReadOnly" or "ReadWrite".

The default value of this key is "ReadWrite".

Application Name

Sets the name of the application in the application identifier as specified by the ibAppName and cchAppName fields in [MS-TDS] section 2.2.6.4.

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is ".NET SqlClient Data Provider".

Async

Synonym of the Asynchronous Processing key.

Asynchronous Processing<1>

When the value of this key is set to "true", asynchronous support MUST be enabled.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

AttachDBFilename

Sets the name of the primary file of an attachable database<2> as specified by the ibAtchDBFile and cchAtchDBFile fields in [MS-TDS] section 2.2.6.4.

The default value of this key is "".

If the value of the AttachDBFilename key is specified in the connection string, the database is attached and becomes the default database for the connection.

If the Database key is not specified and if the database was previously attached, the database will not be reattached. The previously attached database will be used as the default database for the connection.

If the Database key is specified together with the AttachDBFilename key, the value of the Database key SHOULD be used as the alias. However, if the name is already used in another attached database, the connection MUST fail.

For more information about attachable databases, see [MSDN-DAD].

For more information about default databases, see [MSDN-SD].

Authentication

Specifies the authentication method that is used to authenticate a user. The value of this key MUST be one of the following:

  • Sql Password: Indicates that a user connects by using SQL Server authentication. If this value is specified, the User ID and Password keys MUST also be specified, unless the user name and the password are passed as a secure string by using SqlClient programming interfaces.

  • Active Directory Password: Indicates that a user MAY<3> connect by using a user name and password. If this value is specified, the User ID and Password keys MUST also be specified, unless the user name and the password are passed as a secure string by using SqlClient programming interfaces. In this case, SqlClient contacts a security token service (STS) to obtain a security token for the database. The STS validates the user name and password in Azure Active Directory (Azure AD), which acts as an identity provider. Subsequently, SqlClient uses the security token to connect to the database.

  • Active Directory Integrated: Indicates that a user SHOULD<4> connect with a domain account and its domain credentials ([MS-NRPC] section 2.2.1.3.4) by using either Kerberos [RFC4120] or another platform-specific authentication process, such as NTLM [MSDN-NTLM].<5> If this value is set, the User ID and Password keys MUST NOT be set.

  • Active Directory Interactive: Indicates that a user MAY<6> connect by using Microsoft Azure Multi-Factor Authentication for Azure SQL Database and by using Azure AD. This method supports native and federated Azure AD users and all guest users from other accounts. When this value is specified, the User ID key MUST also be specified and the Password key MUST NOT be specified. For a given user ID, an additional sign-in pop-up authentication window that is supported by Azure AD requires users to enter a password manually. Due to its interactive nature, this method is not recommended for use with an automated workflow.

If the Authentication key is specified, the Integrated Security key is ignored if it is set to "true", "yes", or "sspi".

Column Encryption Setting

When this key is set to "enabled" and column encryption is supported, SqlClient SHOULD<7> transparently encrypt the values of input query parameters that correspond to transparently encrypted columns in the database, before sending the values to the server. Similarly, SqlClient transparently decrypts any values from encrypted columns that are received from the server in query results.

If this key is set to "disabled" and the query contains any parameters that correspond to transparently encrypted columns and/or the query requires enclave computations, the query will fail.

If this key is set to "disabled" and the query retrieves any values from transparently encrypted columns, the user will receive the values in cypher text. In other words, SqlClient will not decrypt these values.

The value of this key MUST be "enabled" or "disabled".

The default value of this key is "disabled".

Connection Lifetime

The minimum time, in seconds, for the connection to live in the connection pool before it is destroyed.

Valid values MUST be unsigned integers that range from greater than or equal to 0 to less than or equal to 2147483647.

The default value of this key is 0, which means no pool usage at all.

Connection Reset

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "true", and "false" is ignored.

ConnectionRetryCount

Specifies the number of reconnection attempts if an idle connection failure is detected.

Valid values MUST be unsigned integers that range from greater than or equal to 0 to less than or equal to 255.

The default value of this key is 1.

ConnectionRetryInterval

Specifies the amount of time, in seconds, between each reconnection attempt.

Valid values MUST be unsigned integers that range from greater than or equal to 1 to less than or equal to 60.

The default value of this key is 10.

Connection Timeout

Specifies the amount of time, in seconds, to wait for a connection to complete.

Valid values MUST be unsigned integers that range from greater than or equal to 0 to less than or equal to 2147483647.

The default value of this key is 15.

Connect Timeout

Synonym of the Connection Timeout key.

Context Connection

The value of this key MUST be "true" to open an in-process connection to the server.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Current Language

Sets the language used for database server warning or error messages as specified by the ibLanguage and cchLanguage fields in [MS-TDS] section 2.2.6.4.

For more information about default language, see [MSDN-DLO].

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

Database

Synonym of the Initial Catalog key.

Data Source

Specifies the network address of an instance of the database server.<8>

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

Data Source MUST be the TCP format, the Named Pipes format, or the LocalDB format.

TCP format is as follows:

  • tcp:<host name>\<instance name>

  • tcp:<host name>,<TCP/IP port number>

The TCP format MUST start with the prefix "tcp:" and is followed by the database instance, as specified by a host name and an instance name.

The host name MUST be specified in one of the following ways:

The instance name is used to resolve to a particular TCP/IP port number [RFC793] on which a database instance is hosted. Alternatively, specifying a TCP/IP port number directly is also allowed. If both instance name and port number are not present, the default database instance is used.

For more information about instance name, see [MSDN-UNI].

The Named Pipes format is as follows:

  • np:\\<host name>\pipe\<pipe name>

The Named Pipes format MUST start with the prefix "np:" and is followed by a named pipe name.

The host name MUST be specified in one of the following ways:

  • NetBIOSName [RFC1002]

  • IPv4Address [RFC791]

  • IPv6Address [RFC2460]

The pipe name is used to identify the database instance to which the .NET Framework application will be connected.

If the value of the Network key is specified, the prefixes "tcp:" and "np:" SHOULD NOT<9> be specified.

The LocalDB format MUST start with "(localdb)" followed by a "\" and either the instance name or the LocalDB version number in the format "vXX.X".  The format is as follows:

  • (localdb)\<instance name>, where <instance name> MUST be case insensitive and MUST NOT contain the terms Default, MSSQLServer, or other reserved keywords. If a reserved keyword is used in an instance name, an error will occur. Also, <instance name> MUST be limited to 16 characters, where the first character MUST be a letter or an underscore (_). Acceptable letters are those that are defined by the Unicode Standard 2.0 [UNICODE2.0.0], including Latin characters a-z and A-Z, and letter characters from other languages. Subsequent characters MUST be letters defined by the Unicode Standard 2.0, decimal numbers from Basic Latin or other national scripts, the dollar sign ($), or an underscore (_). Embedded spaces of other special characters MUST NOT be allowed in instance names. The backslash (\), comma (,), colon (:), semicolon (;), single quotation mark ('), ampersand (&), number sign (#), or at sign (@) also MUST NOT be allowed in instance names.

  • (localdb)\vXX.X, for the default instance, where X MUST be any valid decimal number from Basic Latin or other national scripts.

For more information about the format of the Data Source key, see [MSKB-313295].

For more information about named pipes, see [MSDN-NP].

Enclave Attestation Url

Specifies an endpoint of an enclave attestation service. This key SHOULD<10> identify the service that is used to verify whether the enclave, which is configured in the SQL Server instance for computations on encrypted database columns, is valid and secure.

If the value of this key is "" and SqlClient sends a query that requires enclave computations, the query will fail.

The default value of this key is "".

Encrypt

Specifies whether encryption is used as specified by [MS-TDS] section 2.2.6.5.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated as a value of "false".

If the Authentication key is specified, the default value of this key is "true". Otherwise, the default value of this key SHOULD<11> be "false".

Enlist

When the value of this key is set to "true", the connection MUST be automatically enlisted in current transaction context.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key MAY<12> be "false".

Extended Properties

Synonym of the AttachDBFilename key.

Failover Partner<13>

The name of the failover partner server where database mirroring is configured. This parameter is optional.

If the value of this key is "", then Initial Catalog MUST be present, and its value MUST NOT be "".

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

Initial Catalog

Sets the name of the initial or default database of a data source as specified by the ibDatabase and cchDatabase fields in [MS-TDS] section 2.2.6.4.

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

For more information about default databases, see [MSDN-SD].

Initial File Name

Synonym of the AttachDBFilename key.

Integrated Security

The value of this key MUST be "sspi", "true", "false", "yes", or "no".

The value of "sspi", "true", or "yes" indicates that a user connects by using either Kerberos [RFC4120] or another platform-specific authentication process, such as NTLM [MSDN-NTLM].<14>

If the value of this key is "yes", "sspi", or "true", the User ID and Password keys MUST be ignored.

A value of "yes" or "sspi" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Language

Synonym of the Current Language key.

Load Balance Timeout

Synonym of the Connection Lifetime key.

Max Pool Size

The maximum number of connections that are allowed in the pool.

Max Pool Size does not impose any restrictions other than those implied or explicitly stated in this section. Examples of such restrictions can be derived from limitations on available resources or of a targeted system.

Valid values MUST be unsigned integers that are greater than or equal to 1. Values that are less than Min Pool Size MUST raise an error.

The default value of this key is 100.

Min Pool Size

The minimum number of connections that are allowed in the pool.

Valid values MUST be unsigned integers that are greater than or equal to 0. Zero (0) in this field means that no minimum connections are initially opened.

Values that are greater than Max Pool Size MUST raise an error.

The default value of this key is 0.

MultipleActiveResultSets<15>

When the value of this key is set to "true", the application MUST maintain Multiple Active Result Sets (MARS). When the value of this key is set to "false", the application MUST process or cancel all result sets from one batch before it can execute any other batch on that connection.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

MultiSubnetFailover

The value of this key MUST be "true", "false", "yes", or "no".<16>

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Net

Synonym of the Network Library key.

Network

Synonym of the Network Library key.

Network Address

Synonym of the Data Source key.

Network Library

Specifies the network component used in communication between the client and the data source. The behavior is platform-dependent.

The supported values for this key include the following. There are several of these named components (values), each of which implements a specific protocol behavior.<17>

  • dbnmpntw (Named Pipes [MSDN-NETLIB])

  • dbmsrpcn (Multiprotocol [MSDN-NETLIB], Windows remote procedure call (RPC) [MSDN-NETLIB])

  • dbmsadsn (Apple Talk [MSDN-NETLIB])

  • dbmsgnet (VIA [MSDN-NETLIB])

  • dbmslpcn (Shared Memory [MSDN-NETLIB])

  • dbmsspxn (IPX/SPX [MSDN-NETLIB])

  • dbmssocn (TCP/IP [RFC793])

  • Dbmsvinn (Banyan Vines [MSDN-NETLIB])

The corresponding network library MUST be installed in the client system.

If a network is not specified to connect to a local server, the shared memory library MUST be used.

The default value of this key is "".

Packet Size

Sets the network packet size in bytes (as specified by the PacketSize field in [MS-TDS] section 2.2.6.4) to be used for data exchange between the data source object and the database.

Valid values MUST be unsigned integers that range from greater than or equal to 512 to less than or equal to 32767.

The default packet size is 8000 bytes.

Password

Specifies the password associated with User ID.

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

Persist Security Info

When the value of this key is set to "false", security-sensitive information, such as the password, MUST NOT be returned as part of the connection if the connection is open or has ever been in an open state.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

PersistSecurityInfo

Synonym of the Persist Security Info key.

PoolBlockingPeriod<18>

Specifies the blocking period behavior for a connection pool.

The possible values of this key are the following:

  • Auto: The connection pool blocking period is determined automatically based on the type of server instance. The connection pool blocking period of an on-premises SQL Server instance is enabled.

  • AlwaysBlock: The connection pool blocking period is always enabled.

  • NeverBlock: The connection pool blocking period is always disabled.

The default value of this key is "Auto".

Pooling

When the value of this key is set to "true", any newly created connection MUST be added to the pool when closed by the application. In a next attempt to open the same connection, that connection MUST be drawn from the pool.

Connections are considered the same if they have the same connection string. Different connections MUST have different connection strings.

Connection strings MUST be compared as is.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "true".

PWD

Synonym of the Password key.

Replication

When the value of this key is set to "true", replication MUST be supported using the connection.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Server

Synonym of the Data Source key.

Timeout

Synonym of the Connection Timeout key.

Transaction Binding

Controls a connection association with an enlisted transaction.

The value of this key MUST be one of the following:

  • Transaction Binding=Implicit Unbind

  • Transaction Binding=Explicit Unbind

The Implicit Unbind value MUST cause the connection to detach from the transaction when it ends. After the connection detaches and/or after the transaction ends, additional requests on the connection MUST be committed automatically.

The Explicit Unbind value MUST cause the connection to remain attached to the transaction until the connection is closed or until an explicit call to the SqlConnection.EnlistTransaction(null) method [MSDOCS-SCEnTran] is made.

The default value of this key is "none".

TransparentNetworkIPResolution

When the value of this key is set to "true", the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.

If the MultiSubnetFailover key is set to "true", TransparentNetworkIPResolution MUST be ignored.

If the Failover Partner key is set, TransparentNetworkIPResolution MUST be ignored.

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "true".

Trusted Connection

Synonym of the Integrated Security key.

TrustServerCertificate

When the value of this key is set to "true", or when the value of this key set to "false" and the Encrypt key is set to "false" and the Authentication key is not set, SqlClient bypasses the step of walking the certificate chain to validate trust. The channel MUST NOT be encrypted if TrustServerCertificate is set to "true" and Encrypt is set to "false".

The value of this key MUST be "true", "false", "yes", or "no".

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Type System Version

A string value that indicates the type system that the .NET Framework application expects.<19>

When the value of this key is set to "Latest", the latest version that can be handled by the client-server pair MUST be used. The value of this key MUST automatically move forward as the client and server components are upgraded.

The default value of this key is "none".

UID

Synonym of the User ID key.

User

Synonym of the User ID key.

User ID

Specifies the user identification to be used when connecting to the data source.

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "".

User Instance

The value of this key MUST be "true", "false", "yes", or "no".<20>

A value of "yes" MUST be treated the same as a value of "true".

A value of "no" MUST be treated the same as a value of "false".

The default value of this key is "false".

Workstation ID

Sets the workstation identifier as specified by the ibHostName and cchHostName fields in [MS-TDS] section 2.2.6.4. The default value is the name of the workstation that is running the ODBC application.

The value of this key MUST be a string that has a maximum length of 128 characters.

The default value of this key is "none".

WSID

Synonym of the Workstation ID key.