Configuring and Using the JDBC Driver

In this Topic:

JDBC Driver Class

Use net.snowflake.client.jdbc.SnowflakeDriver as the driver class in your JDBC application.

Note

  • Don’t reference any other Snowflake classes or methods in your application code as they are subject to change in the future to implement improvements and fixes.
  • The previous driver class, com.snowflake.client.jdbc.SnowflakeDriver, is still supported but is deprecated (i.e. it will be removed in a future release, TBD). As such, any code that references the previous class name will continue to work, but you should update the code to reference the new class name now that the change has been implemented.

JDBC Driver Connection String

Using the JDBC driver to connect to Snowflake requires a connection string with the following syntax.

Syntax

US West Region

jdbc:snowflake://<account_name>.snowflakecomputing.com/?<connection_params>

US East Region

jdbc:snowflake://<account_name>.us-east-1.snowflakecomputing.com/?<connection_params>

EU (Frankfurt) Region

jdbc:snowflake://<account_name>.eu-central-1.snowflakecomputing.com/?<connection_params>

Connection Parameters

account_name
Specifies the name assigned to your account by Snowflake. In the URL you received from Snowflake, your account name is the first segment in the domain (e.g. abc123 in https://abc123.snowflakecomputing.com).
connection_params

Specifies a series of one or more parameters, in the form of <param>=<value>, with each parameter separated by the ampersand character &, and no spaces anywhere in the connection string:

user=<login_name>
Specifies the login name of the user for the connection.
password=<string>

Specifies the password for the specified user.

Attention

We strongly recommend that you do not include the user password 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.

authenticator=<string>

Specifies the authenticator (snowflake or https:://<your_octa_account_name>.okta.com) to use for authenticating the user.

Only set this parameter to https://<your_okta_account_name>.okta.com if you are enabling Okta as the federated authentication IdP for your account. For more information, see Enabling Federated Authentication and SSO.

Default is snowflake.

role=<name>

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.

After connecting, the USE ROLE command can be executed to set a different role for the session.

For more information about roles and access control, see Understanding Access Control in Snowflake.

db=<name>

Specifies the default database to use once connected, or nodb. The specified database should be an existing database for which the specified default role has privileges.

After connecting, the USE DATABASE command can be executed to set a different database for the session.

schema=<name>

Specifies the default schema to use for the specified database once connected, or noschema. The specified schema should be an existing schema for which the specified default role has privileges.

After connecting, the USE SCHEMA command can be executed to set a different schema for the session.

warehouse=<name>

Specifies the virtual warehouse to use once connected, or nowarehouse. The specified warehouse should be an existing warehouse for which the specified default role has privileges.

After connecting, the USE WAREHOUSE command can be executed to set a different warehouse for the session.

tracing=<string>

Specifies the log level for the driver. The driver uses the standard Java log utility. Valid values for log level are:

OFF , SEVERE , WARNING , INFO , CONFIG , FINE , FINER , FINEST , ALL.

Default value is INFO.

passcode=<string>

Specifies the passcode to use for multi-factor authentication.

For more information about multi-factor authentication, see Understanding Multi-Factor Authentication.

passcodeInPassword=<string>

Specifies whether the passcode for multi-factor authentication is appended to the password:

  • on (or true) specifies the passcode is appended.
  • off (or false) or any other value specifies the passcode is not appended.

Default is off.

loginTimeout

Specifies how long to wait for a response when connecting to the Snowflake service before returning a login failure error.

Default is 60 seconds.

networkTimeout

Specifies how long to wait for a response when interacting with the Snowflake service before returning an error. Zero (0) indicates no network timeout is set.

Default is 0 seconds.

queryTimeout=<number>

Specifies how long to wait for a query to complete before returning an error. Zero (0) indicates to wait indefinitely.

Default is 0 seconds.

Other Parameters

Any session parameter can be included in the connection string. For example:

CLIENT_SESSION_KEEP_ALIVE=<Boolean>

Specifies whether to keep the current session active after a period of inactivity, or to force the user to login again. If the value is true, Snowflake keeps the session active indefinitely, even if there is no activity from the user. If the value is false, the user must log in again after four hours of inactivity.

Default is false.

For descriptions of all the session parameters, see Parameters.

Examples

jdbc:snowflake://abc123.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public

Configuring Logging

Starting with version 3.0.4, the JDBC driver supports two logging frameworks:

  • Java Core Logging Facilities
  • Simple Logging Facade for Java

Java Core Logging Facilities (java.util.logging)

To use this logger, specify the following option for the JVM:

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.JDK14Logger

Then, you can customize the logging configuration using the API for the logger. For more details, see the java.util.logging Package documentation.

Simple Logging Facade for Java (org.slf4j)

If a logger implementation package (i.e. org.sl4j:sl4j-jdk14 or org.sl4j:slf4j-log4j12) or a custom logger (i.e. your own org.slf4j.impl.StaticLoggerBinder class) has been defined on the classpath, then the driver automatically uses this logger.

You can also explicitly choose to use this logger by specifying the following JVM option:

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.SLF4JLogger.

For more information, see the Simple Logging Facade for Java (SLF4J) documentation.

Note

If you do not explicitly specify a logger for the driver using either of the JVM options described above and you do not have a custom logger defined on the classpath (or you are using a driver version earlier than 3.0.4), the driver uses java.util.logging by default. However, the following default behavior applies:

  • You cannot specify where the log file is written. It is always written to the directory specified by the java.io.tmpDir system property:
    • In Linux and Mac OS environments, the default directory is usually either /tmp or /var/tmp.
    • In Windows environments, the default directory is usually C:\temp.
  • The logging level is determined by the tracing connection parameter (see above).

Connecting Through a Proxy Server

To connect through a proxy server, add the following parameters to your client application configuration file:

-Dhttp.useProxy=true
-Dhttps.proxyHost=<proxy_host>
-Dhttp.proxyHost=<proxy_host>
-Dhttps.proxyPort=<proxy_port>
-Dhttp.proxyPort=<proxy_port>

Java Sample Program

For a working sample written in Java, right-click the name of the file, SnowflakeJDBCExample.java, and save the link/file to your local file system.