JDBC Driver Connection Parameter Reference¶
This topic lists the connection parameters that you can use to configure the JDBC driver.
You can set these parameters in the JDBC connection string or in a Java Properties
object.
Required Parameters¶
This section lists the parameters that you must set in the connection string or in the Map
of properties.
Note
You must also set the parameters for authentication.
user
¶
- Description
Specifies the login name of the user for the connection.
Authentication Parameters¶
allowUnderscoresInHost
¶
- Description
Specifies whether to allow underscores in account names. The JDBC Driver does not support underscores in URLs, which include the account name, so the JDBC Driver automatically converts underscores to hyphens. The default value is
false
.Note
Beginning with version 3.13.25, the Snowflake JDBC driver changes the default value of the
allowUnderscoresInHost
parameter tofalse
. This change impacts PrivateLink customers whose account names contain underscores. In this situation, you must override the default value by settingallowUnderscoresInHost
totrue
.
authenticator
¶
- Description
Specifies the authenticator to use for verifying user login credentials. You can set this to one of the following values:
snowflake
to use the internal Snowflake authenticator.
externalbrowser
to use your web browser to authenticate with Okta, AD FS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.
https://<okta_account_name>.okta.com
(i.e. the URL endpoint for your Okta account) to authenticate through native Okta (only supported if your IdP is Okta).
oauth
to authenticate using OAuth. When OAuth is specified as the authenticator, you must also set thetoken
parameter to specify the OAuth token (see below).
snowflake_jwt
to authenticate using key pair authentication. For more details about key pair authentication, see Using Key Pair Authentication & Key Rotation.
username_password_mfa
to authenticate with MFA token caching. For more details, see Using Multi-Factor AuthenticationIf the connection string specifies a key pair, then key pair authentication will be used even if the
authenticator
parameter is unset or is set to ‘snowflake’.For more information on authentication, see Managing/Using Federated Authentication and Clients, Drivers, and Connectors.
- Default
snowflake
passcode
¶
- Description
Specifies the passcode to use for multi-factor authentication.
For more information about multi-factor authentication, see Multi-Factor Authentication (MFA).
passcodeInPassword
¶
- Description
Specifies whether the passcode for multi-factor authentication is appended to the password:
on
(ortrue
) specifies the passcode is appended.
off
(orfalse
) or any other value specifies the passcode is not appended.- Default
off
password
¶
- Description
Specifies the password for the specified user.
There are two ways to specify the password:
The first way is to pass the user ID and password directly to the
getConnection
method:String user = "<user>"; // replace "<user>" with your user name String password = "<password>"; // replace "<password>" with your password Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", user, password);The second way is to create a
Properties
object, update the object with the password, and pass the object to thegetConnection
method:String user = "<user>"; // replace "<user>" with your user name String password = "<password>"; // replace "<password>" with your password Properties props = new Properties(); props.put("user", user); props.put("password", password); Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", props);Attention
We strongly recommend that you do not include the user password directly in the JDBC connection string because the password could be inadvertently exposed by the client application that uses the string to connect to Snowflake. Instead, use the interface(s) provided by the application to specify the user password.
privatekey
¶
- Description
Specifies the private key for the specified user. See Using Key Pair Authentication & Key Rotation.
private_key_file
¶
- Description
Specifies the path to the private key file for the specified user. See Using Key Pair Authentication & Key Rotation.
private_key_file_pwd
¶
- Description
Specifies the passphrase to decrypt the private key file for the specified user. See Using Key Pair Authentication & Key Rotation.
token
¶
- Description
Specifies the OAuth token to use for authentication, where
<string>
is the token. This parameter is required only when setting the authenticator parameter tooauth
, except as noted below.Note
Beginning with version 3.13.24, the Snowflake JDBC Driver lets you send the OAuth token in the connection password in addition to including it in the
token
configuration parameter. If thetoken
configuration parameter is not specified, theDriver.connect()
method expects the token to be stored in the connection password.This feature primarily supports using OAuth authentication for connection pools, allowing you to pass refreshed tokens as needed instead of being restricted by an expired token specified in the
token
configuration parameter.For example, instead of setting he
token
configuration parameter, you can pass the token as the password in thegetConnection()
method properties, similar to the following:Properties props = new Properties(); props.put("user", "myusername"); props.put("authenticator", "oauth"); props.put("role", "myrole"); props.put("password", "xxxxxxxxxxxxx"); // where xxxxxxxxxxxxx is the token string Connection myconnection = DriverManager.getConnection(url, props);- Default
None
Parameters for the Default Database, Role, Schema, and Warehouse¶
db
¶
- Description
Specifies the default database to use once connected, or specifies an empty string. The specified database should be an existing database for which the specified default role has privileges.
If you need to use a different database after connecting, execute the USE DATABASE command.
role
¶
- Description
Specifies the default access control role to use in the Snowflake session initiated by the driver. The specified role should be an existing role that has already been assigned to the specified user for the driver. If the specified role has not already been assigned to the user, the role is not used when the session is initiated by the driver.
If you need to use a different role after connecting, execute the USE ROLE command.
For more information about roles and access control, see Overview of Access Control.
schema
¶
- Description
Specifies the default schema to use for the specified database once connected, or specifies an empty string. The specified schema should be an existing schema for which the specified default role has privileges.
If you need to use a different schema after connecting, execute the USE SCHEMA command.
warehouse
¶
- Description
Specifies the virtual warehouse to use once connected, or specifies an empty string. The specified warehouse should be an existing warehouse for which the specified default role has privileges.
If you need to use a different warehouse after connecting, execute the USE WAREHOUSE command can be executed to set a different warehouse for the session.
Proxy Parameters¶
disableSocksProxy
¶
- Description
Specifies whether the driver should ignore the SOCKS proxy configuration specified in the Java system options:
on
(ortrue
) specifies to ignore the proxy.
off
(orfalse
) or any other value specifies to use the proxy.Note
Setting this connection parameter alters the behavior for all connections on the same JVM (Java virtual machine).
- Default
off
nonProxyHosts
¶
- Description
Specifies the lists of hosts that the driver should connect to directly, bypassing the proxy server. See Specifying a Proxy Server in the JDBC Connection String for details.
proxyHost
¶
- Description
Specifies the hostname of the proxy server to use. See Specifying a Proxy Server in the JDBC Connection String for details.
proxyPassword
¶
- Description
Specifies the password for authenticating to the proxy server. See Specifying a Proxy Server in the JDBC Connection String for details.
proxyPort
¶
- Description
Specifies the port number of the proxy server to use. See Specifying a Proxy Server in the JDBC Connection String for details.
proxyProtocol
¶
- Description
Specifies the protocol used to connect to the proxy server. See Specifying a Proxy Server in the JDBC Connection String for details.
- Default
http
proxyUser
¶
- Description
Specifies the user name for authenticating to the proxy server. See Specifying a Proxy Server in the JDBC Connection String for details.
useProxy
¶
- Description
Specifies whether the driver should use a proxy:
on
(ortrue
) specifies that the driver should use a proxy.
off
(orfalse
) or any other value specifies that the driver should not use a proxy.See Specifying a Proxy Server in the JDBC Connection String for details.
- Default
off
Timeout Parameters¶
loginTimeout
¶
- Description
Specifies the number of seconds to wait for a response when connecting to the Snowflake service before returning a login failure error.
- Default
60
networkTimeout
¶
- Description
Specifies the number of milliseconds to wait for a response when interacting with the Snowflake service before returning an error.
0
(zero) specifies that no network timeout is set.- Default
0
queryTimeout
¶
- Description
Specifies the number of seconds to wait for a query to complete before returning an error.
0
(zero) specifies that the driver should wait indefinitely.- Default
0
Other Parameters¶
application
¶
- Description
Snowflake partner use only: Specifies the name of a partner application to connect through JDBC.
maxHttpRetries
¶
- Description
Specifies the maximum number of times to retry failed HTTP requests before returning an error.
- Default
7
client_config_file
¶
- Description
Specifies the path of a logging configuration file that you can use to define the logging level and directory for saving log files.
net.snowflake.jdbc.max_connections
¶
- Description
Specifies the total maximum connections available in the connection pool.
- Default
300
net.snowflake.jdbc.max_connections_per_route
¶
- Description
Specifies the maximum number of connections allowed for a single port or URL. The value cannot exceed the net.snowflake.jdbc.max_connections value.
- Default
300
ocspFailOpen
¶
- Description
Specifies that the driver should “fail open” if unable reach the OCSP server to verify the certificate. See OCSP.
putGetMaxRetries
¶
- Description
Specifies the maximum number of times to retry PUT/GET exceptions for storage clients.
- Default
25
stringsQuotedForColumnDef
¶
- Description
If this parameter is set to
true
, then whenDatabaseMetaData.getColumns()
andDatabaseMetaData.getProcedureColumns()
return a value of typeString
in the COLUMN_DEF column, that value is embedded in single quotes. (If the data type of the value is notString
, then the value is not quoted, regardless of the setting of this parameter.)
true
specifies that string values should be embedded in single quotes (the quotes are part of the string, not delimiters). This complies with the JDBC standard.
false
specifies that string values are not embedded in single quotes.- Default
false
tracing
¶
- Description
Specifies the log level for the driver. The driver uses the standard Java log utility. you can set this parameter to one of the following log levels:
OFF
SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST
ALL
- Default
INFO