JDBC connection string syntax

The JDBC connection string for connecting to a remote Hive client requires a host, port, and Hive database name. You can optionally specify a transport type and authentication.

jdbc:hive2://<host>:<port>/<dbName>;<sessionConfs>?<hiveConfs>#<hiveVars>

Connection string parameters

The following table describes the parameters for specifying the JDBC connection.

JDBC Parameter Description Required

host

The cluster node hosting HiveServer.

yes

port

The port number to which HiveServer listens.

yes

dbName

The name of the Hive database to run the query against.

yes

sessionConfs

Optional configuration parameters for the JDBC/ODBC driver in the following format: <key1>=<value1>;<key2>=<key2>...;

no

hiveConfs

Optional configuration parameters for Hive on the server in the following format: <key1>=<value1>;<key2>=<key2>; ...

The configurations last for the duration of the user session.

no

hiveVars

Optional configuration parameters for Hive variables in the following format: <key1>=<value1>;<key2>=<key2>; ...

The configurations last for the duration of the user session.

no

TCP and HTTP Transport

The following table shows variables for use in the connection string when you configure HiveServer. The JDBC client and HiveServer can use either HTTP or TCP-based transport to exchange RPC messages. Because the default transport is TCP, there is no need to specify transportMode=binary if TCP transport is desired.

transportMode Variable Value Description

http

Connect to HiveServer2 using HTTP transport.

binary

Connect to HiveServer2 using TCP transport.

The syntax for using these parameters is:
jdbc:hive2://<host>:<port>/<dbName>;transportMode=http;httpPath=<http_endpoint>;<otherSessionConfs>?<hiveConfs>#<hiveVars>

User Authentication

If configured in remote mode, HiveServer supports Kerberos, LDAP, Pluggable Authentication Modules (PAM), and custom plugins for authenticating the JDBC user connecting to HiveServer. The format of the JDBC connection URL for authentication with Kerberos differs from the format for other authentication models. The following table shows the variables for Kerberos authentication.

User Authentication Variable Description

principal

A string that uniquely identifies a Kerberos user.

saslQop

Quality of protection for the SASL framework. The level of quality is negotiated between the client and server during authentication. Used by Kerberos authentication with TCP transport.

user

Username for non-Kerberos authentication model.

password

Password for non-Kerberos authentication model.

The syntax for using these parameters is:
jdbc:hive://<host>:<port>/<dbName>;principal=<HiveServer2_kerberos_principal>;<otherSessionConfs>?<hiveConfs>#<hiveVars> 

Transport Layer Security

HiveServer2 supports SSL and Sasl QOP for transport-layer security. The format of the JDBC connection string for SSL uses these variables:

SSL Variable Description

ssl

Specifies whether to use SSL

sslTrustStore

The path to the SSL TrustStore.

trustStorePassword

The password to the SSL TrustStore.

The syntax for using the authentication parameters is:

jdbc:hive2://<host>:<port>/<dbName>;\
ssl=true;sslTrustStore=<ssl_truststore_path>;trustStorePassword=<truststore_password>;\
<otherSessionConfs>?<hiveConfs>#<hiveVars> 

When using TCP for transport and Kerberos for security, HiveServer2 uses Sasl QOP for encryption rather than SSL.

Sasl QOP Variable Description

principal

A string that uniquely identifies a Kerberos user.

saslQop

The level of protection desired. For authentication, checksum, and encryption, specify auth-conf. The other valid values do not provide encryption.

The JDBC connection string for Sasl QOP uses these variables.

jdbc:hive2://fqdn.example.com:10000/default;principal=hive/_HOST@EXAMPLE.COM;saslQop=auth-conf

The _HOST is a wildcard placeholder that gets automatically replaced with the fully qualified domain name (FQDN) of the server running the HiveServer daemon process.