This is the documentation for CDH 5.0.x. Documentation for other versions is available at Cloudera Documentation.

Apache HBase Incompatible Changes

Upgrading from CDH 4 to CDH 5

Rolling upgrades from CDH 4 to CDH 5 are not possible because existing CDH 4 HBase clients cannot make requests to CDH 5 servers and CDH 5 HBase clients cannot make requests to CDH 4 servers. Replication between CDH 4 and CDH 5 is not currently supported. Exposed JMX metrics in CDH 4 have been refactored and some have been removed.

The upgrade from CDH 4 HBase to CDH 5 HBase is irreversible and requires HBase to be shutdown completely.

As of CDH4.2, the default Split Policy changed from ConstantSizeRegionSplitPolicy to IncreasingToUpperBoundRegionSplitPolicy (ITUBRSP). This affects upgrades from CDH 4.1 or earlier only.

Upgrading from CDH 5 Beta 1 to CDH 5 Beta 2:

The HBase client from CDH 5 Beta 1 is not wire compatible with CDH 5 Beta 2 due to changes introduced in HBASE-9612. As a consequence, CDH 5 Beta 1 users will not be able to execute a rolling upgrade to CDH 5 Beta 2 (or later). This patch unifies the way the the HBase clients make requests and simplifies the internals, but breaks wire compatibility. Developers may need to recompile applications built upon the CDH 5 Beta 1 API.

Compatibility between CDH and Apache releases:

  • Apache HBase 0.95.2 is not wire compatible with CDH 5 Beta 1 HBase 0.95.2.
  • Apache HBase 0.96.x should be wire compatible with CDH 5 Beta 2 HBase 0.96.1.1.

Developer Interface Changes:

The set of exposed APIs has been solidified. If you are using APIs outside of the user API, we cannot guarantee compatibility with future minor versions.

HBASE-4336 introduces a new layout for build artifacts and requires POM changes.

Previously, in CDH 4 you would only need to pull in the HBase JAR: 
<dependency>
<groupId> org.apache.hbase </groupId>
<artifactId> hbase </artifactId>
<optional> true </optional>
</dependency>
Now, when building against CDH 5 you will need to pull in the hbase-client JAR.
<dependency>
<groupId>org.apache.hbase</groupId>
<artifactId>hbase-client</artifactId>
<version>${hbase.version}</version>
</dependency>
If your code uses the HBase minicluster, you can pull in this dependency:
<dependency>
<groupId>org.apache.hbase</groupId>
<artifactId>hbase-testing-util</artifactId>
<version>${cdh.hbase.version}</version>
</dependency>

HTablePool Deprecated in CDH 5:

The HConnection object is now a replacement for HTablePool. You create the connection once and pass it around, like the old table pool.
HConnection connection = HConnectionManager.createConnection(config);
HTableInterface table = connection.getTable(tableName);
table.put(put);
table.close();
connection.close();
You can use the hbase.hconnection.threads.max property to control the pool size or you can pass an ExecutorService to HConnectionManager.createConnection().
ExecutorService pool = ...;
HConnection connection = HConnectionManager.createConnection(conf, pool);
API Removals

Operator Interface Changes:

  • Many of the default configurations from CDH 4 in hbase-default.xml have been changed to new values in CDH 5. See HBASE-8450 for a complete list of changes.
  • HBASE-6553 - Removed Avro Gateway. This feature was less robust and not used as much as the Thrift gateways. It has been removed upstream.
  • Metrics have been regularized and rationalized but have changed significantly in an incompatible way.

HBase User API Incompatibility:

The HBase User API (Get, Put, Result, Scanner etc; see Apache HBase API documentation) has evolved and attempts have been made to make sure the HBase Clients are source code compatible and thus should recompile without needing any source code modifications. This cannot be guaranteed however, since with the conversion to ProtoBufs, some relatively obscure APIs have been removed. Rudimentary efforts have also been made to preserve recompile compatibility with advanced APIs such as Filters and Coprocessors. These advanced APIs are still evolving and our guarantees for API compatibility are weaker here.

As of 0.96, the User API has been marked and all attempts at compatibility in future versions will be made. A version of the javadoc that only contains the User API can be found here.

Other changes to CDH 5 HBase that require the upgrade include:
  • HBASE-8015: The HBase Namespaces feature has changed HBase’s HDFS file layout.
  • HBASE-4451: Renamed ZooKeeper nodes.
  • HBASE-3171: The META table in CDH 4 has been renamed to be hbase:meta. Similarly the ACL table has been renamed to hbase:acl. The .ROOT table has been removed.
  • HBASE-8352: HBase snapshots are now saved to the /<hbase>/.hbase-snapshot dir instead of the /.snapshot dir. This should be handled before upgrading HDFS.
  • HBASE-7660: Removed support for HFile V1. All internal HBase files in the HFile v1 format must be converted to the HFile v2 format.
  • HBASE-6170/HBASE-8909 - The hbase.regionserver.lease.period configuration parameter has been deprecated. Use hbase.client.scanner.timeout.period instead.

HBase Metrics Changes

HBase provides a metrics framework based on JMX beans. Between HBase 0.94 and 0.96, the metrics framework underwent many changes. Some beans were added and removed, some metrics were moved from one bean to another, and some metrics were renamed or removed. Click here to download the CSV spreadsheet which provides a mapping.

Page generated September 3, 2015.