Cloudera Docs

Understanding the Phoenix JDBC URL

Know the usage and different parts of the Phoenix JDBC URL.

The Phoenix URL contains two main parts. The first one describes the connection to the HBase cluster, while the second part can specify additional options for Phoenix.

jdbc:<protocol variant>[:<server list>[:<port>[:<zk root node>[:<principal>[:<keytab file>]]]]][;<option>=<value>]*

For example,
jdbc : phoenix:cod-1ijq6ne9nicgn-leader0.cod-7218.xcu2-8y8x.dev.cldr.work,cod-1ijq6ne9nicgn-master0.cod-7218.xcu2-8y8x.dev.cldr.work,cod-1ijq6ne9nicgn-master1.cod-7218.xcu2-8y8x.dev.cldr.work:2181:/hbase
  • protocol variant: The HBase connection registry to use.
  • server list: A comma-separated list of hostnames or IPv4 addresses. It is also possible to specify the port in ZK quorum string for each host. For more information, see HBASE-12706. In this case the colon ‘:’ characters must be escaped with a backslash ‘\’. It may be necessary to repeat the escape character, for example in the Java source code.
  • port: An integer number specifying a port. Ports specified in the server list take precedence.
  • zk root node: The root ZNode for the HBase instance. Must be empty for non-ZK registries.
  • principal: The Kerberos principal to use for authentication.

    If only the principal is specified, then this defines the user name with each distinct user having their own dedicated HBase connection (HConnection). This provides a means of having multiple, different connections, each with different configuration properties on the same JVM.

  • keytab: The Kerberos keytab to be used for authentication. Must be specified together with the principal.
  • option: A connection option. This can be any additional JDBC parameter. This is optional.
  • value: Value for the connection option.

Parameters from the end of the connection definition can be omitted. Use empty strings for missing parameters in the middle of the URL. For example, the jdbc:phoenix::::principal:/home/user/keytab URL can be used to specify the Kerberos principal and keytab while using the default connection specified in the hbase-site.xml file.

The default connection

This section highlights the client configurations and dependencies connecting to an HBase cluster.

The underlying HBase client identifies the HBase cluster based on parameters specified in the hbase-site.xml file. While Phoenix makes it possible to override this, in the majority of cases it is advisable not to do that, and to use the cluster connection definition from the hbase-site.xml file. You must specify the connection directly only when switching between identically configured HBase instances, for example, a production and a disaster recovery cluster.

To use the defaults from the hbase-site.xml file, use the jdbc:phoenix URL or jdbc:phoenix;option=value if additional options are needed.

For more information, see HBase documentation on Client configuration and dependencies.

The jdbc:phoenix: protocol variant

If the default protocol variant is specified, then Phoenix selects the variant based on the value of the hbase.client.registry.impl property.

If the hbase.client.registry.impl property is not defined, then it chooses a default value based on the version of the HBase client it includes.

The jdbc:phoenix+zk: protocol variant

This uses the original Zookeeper-based HBase connection registry, which is always available in HBase. The server list and port specify the ZooKeeper (ZK) quorum. For more information, see HBASE-12706, this is supported now. In this case the colon ‘:’ characters must be escaped with a backslash ’'.

Following are a few examples:

  • jdbc:phoenix+zk:localhost:2181:/hbase:principal:keytab: Fully specified.
  • jdbc:phoenix+zk:host1\:2181,host1\:2182,host2\:2183 : Heterogeneous ports, default ZooKeeper node.
  • jdbc:phoenix+zk : Use the default ZooKeeper parameters from the hbase-site.xml file or the HBase defaults. (using jdbc:phoenix is preferred in most scenarios).

The jdbc:phoenix+master: protocol variant

This uses the master-based connection registry that is added by providing an option for clients to find the server hosting META that does not involve the ZooKeeper client, and is available from HBase 2.3.0. The "zk root node" parameter must never be specified. For more information, see HBASE-18095.

Following are a few examples:

  • jbdc:phoenix+master:master1\:16001,master2\:16002::principal:/path/to/keytab : Fully specified.
  • jbdc:phoenix+master:master1,master2 : Uses master1 and master2 with the default port.