Administration guide

Documentation home · API reference · Current limitations

Administration changes the cluster, not just a local object. Use a development cluster for examples, unique resource names, and explicit ownership checks before deletion. The cookbook exercises temporary table creation/deletion; snapshot restore, Region moves, and cluster-wide mutations are not part of that smoke test.

Create and inspect a table safely

TableName.value_of() takes two byte-string arguments. Build column families using ColumnFamilyDescriptorBuilder; build() returns a protobuf ColumnFamilySchema. There is no public ColumnFamilyDescriptor class.

The following standalone example creates a unique table and removes only that table after a successful creation. It never deletes a pre-existing table.

import os
from uuid import uuid4

from hbasedriver.client.client import Client
from hbasedriver.common.table_name import TableName
from hbasedriver.hbase_constants import HConstants
from hbasedriver.operations.column_family_builder import ColumnFamilyDescriptorBuilder

config = {HConstants.ZOOKEEPER_QUORUM: os.getenv("HBASE_ZK", "127.0.0.1:2181")}
name = TableName.value_of(b"default", f"docs_admin_{uuid4().hex}".encode("ascii"))
created = False
with Client(config) as client:
    with client.get_admin() as admin:
        try:
            family = ColumnFamilyDescriptorBuilder(b"cf").build()
            admin.create_table(name, [family])
            created = True
            response = admin.describe_table(name)
            print(response.table_schema[0])
            print(admin.list_tables(pattern="docs_admin_.*"))
        finally:
            if created:
                admin.disable_table(name)
                admin.delete_table(name)

If creation times out, the server may still have created the table; inspect the unique name before cleanup or retry. table_exists() currently catches all exceptions and returns False, so False is not proof of a healthy cluster or safe ownership.

list_tables() and describe_table() both return a protobuf GetTableDescriptorsResponse, not a list of names or a bare schema. Schemas are in response.table_schema. Do not copy a HappyBase loop expecting byte strings without inspecting this shape.

Namespaces and column families

The snippets below are contextual: admin and table_name must refer to a development cluster and a table you own.

namespaces = admin.list_namespaces()  # list[str]
print(namespaces)
response = admin.describe_table(table_name)
if not response.table_schema:
    raise RuntimeError("No table schema returned")
schema = response.table_schema[0]
for family in schema.column_families:
    print(family.name)

To create a namespace, use admin.create_namespace(b"analytics"). Deleting it with admin.delete_namespace(b"analytics") requires the namespace to be empty. Do not assume this driver automatically creates namespaces when creating tables.

For a controlled schema change, disable the table, modify it, then enable it:

admin.disable_table(table_name)
try:
    admin.add_column_family(table_name, b"details")
finally:
    admin.enable_table(table_name)

modify_column_family() accepts options including max_versions, min_versions, time_to_live, compression, bloom_filter, block_size, block_cache_enabled, and in_memory. The availability of a keyword is not proof that every setting is applied by the server. Inspect the resulting schema and verify TTL/version behavior in HBase; the basic examples do not certify retention settings. Removing a family with delete_column_family() removes its data and needs a separate backup/recovery plan.

Truncation is destructive

The current truncate_table(table_name, preserve_splits=False, timeout=60) implementation deletes and recreates the table. It retains column-family descriptors, but does not preserve all table metadata; preserve_splits and timeout are not implemented as their signatures imply.

Before using it:

1. Back up the data and record the schema and split boundaries.
2. Stop writers and obtain explicit approval for data loss.
3. Verify the reconstructed table and its enabled state.
4. Create a fresh Client for subsequent access; Table.invalidate_cache() alone does not clear every scan-location cache.

Do not use truncate as ordinary test cleanup for a shared table.

Snapshots and asynchronous procedures

Method	Immediate result	What it does not prove
create_snapshot(table_name, snapshot_name, snapshot_type="FLUSH")	Expected timeout in milliseconds from the response	Snapshot completion
list_snapshots(pattern=None)	List of dictionaries: name, table, creation_time, type	Restore readiness or data correctness
snapshot_exists(snapshot_name)	Boolean based on snapshot listing	Successful future restore
restore_snapshot(snapshot_name, table_name=None, restore_acl=False)	Procedure ID	Restore completion
clone_snapshot(snapshot_name, target_table, restore_acl=False)	Procedure ID	Clone completion
delete_snapshot(snapshot_name)	No useful return value	Recovery remains possible

Use unique snapshot/clone names, check operation completion with your cluster's administration tools, and verify table contents before switching traffic. Snapshot restore can overwrite data; do not paste a restore into a read-only diagnostic session. Snapshot type and disabled-table requirements must match your HBase deployment.

Regions and cluster diagnostics

Read-only entry points include:

print(admin.get_cluster_status())
print(admin.list_region_servers())
print(admin.is_balancer_enabled())

The API also exposes split_region, merge_regions, assign_region, unassign_region, balance, and set_balancer. These can move data or affect other workloads. A request returning does not necessarily mean a split or merge is complete. Obtain full Region identifiers from verified cluster metadata; do not substitute a row key or table name. This public Client does not provide get_region_locator().

There are no high-level Admin.compact() or Admin.flush() methods in this implementation. Use your cluster's supported administrative tooling for operations not exposed here.