Heuristic:Heibaiying BigData Notes HBase Connection Thread Safety Tip
| Knowledge Sources | |
|---|---|
| Domains | NoSQL_Database, Concurrency |
| Last Updated | 2026-02-10 10:00 GMT |
Overview
HBase `Connection` objects are thread-safe and should be shared; `Table` and `Admin` objects are NOT thread-safe and must be created per-thread and closed after use.
Description
In HBase Java API programming, understanding the thread-safety model is critical for correct multi-threaded applications. The `Connection` object is heavyweight (establishes Zookeeper sessions and caches region locations) but thread-safe, making it suitable as a singleton shared across the application. In contrast, `Table` and `Admin` objects are lightweight to create but NOT thread-safe. They should be obtained from the `Connection` per-thread and explicitly closed after each operation. A custom connection pool is unnecessary because `getTable()` and `getAdmin()` are lightweight operations.
Usage
Use this heuristic when writing HBase Java client code with multiple threads or in server applications. Apply when:
- Designing HBase data access layers
- Encountering intermittent data corruption or `ConcurrentModificationException`
- Deciding whether to pool HBase connections
The Insight (Rule of Thumb)
- Action: Create one `Connection` per application process (singleton pattern with static initialization). Obtain `Table` and `Admin` objects per-thread via `connection.getTable()` and `connection.getAdmin()`.
- Value: Always call `table.close()` and `admin.close()` after use (use try-with-resources in Java 7+).
- Trade-off: No performance penalty. `getTable()` and `getAdmin()` are lightweight; no need for object pooling.
- Anti-pattern: Do NOT share `Table` or `Admin` objects between threads. Do NOT create multiple `Connection` objects unnecessarily.
Reasoning
The HBase `Connection` object establishes a session with Zookeeper and maintains a cache of region locations. Creating multiple connections wastes resources and Zookeeper sessions. The `Table` and `Admin` objects maintain internal state that is not synchronized for concurrent access. The official HBase documentation states: "Connection instances are fully thread-safe" and "Table and Admin instances are NOT thread-safe." The BigData-Notes HBaseUtils class demonstrates this pattern with a static `Connection` and per-method `Table`/`Admin` creation.