Google Git
Sign in
apache/phoenix-adapters/c534b48c85deada12a7e9e81dda00a855a16034a
commit
c534b48c85deada12a7e9e81dda00a855a16034a
[log]
author
Viraj Jasani <vjasani@apache.org>
Thu Nov 06 13:42:01 2025 -0800
committer
Viraj Jasani <vjasani@apache.org>
Thu Nov 06 14:52:51 2025 -0800
tree
32ae67a100c50b18516af2c2f791731623abd856
parent
0ba8c0ac678083578a8b6e34b5b11bf507a8f539 [diff]
Configure HTTP server idle connection timeout
5 files changed
tree: 32ae67a100c50b18516af2c2f791731623abd856
  1. bin/
  2. conf/
  3. coverage-report/
  4. dev-support/
  5. phoenix-ddb-assembly/
  6. phoenix-ddb-rest/
  7. phoenix-ddb-utils/
  8. src/
  9. .gitignore
  10. pom.xml
  11. README.md
  12. sonar-project.properties
README.md

🔄 Phoenix-Shim: A Unified NoSQL Frontend for Apache Phoenix

A frontend layer that mimics NoSQL APIs for different databases while always using Salesforce Phoenix (on HBase) as the persistent store.

Building Distribution Tarball

To build a distribution tarball that includes all components:

mvn clean package

This will generate a tarball in phoenix-ddb-assembly/target/phoenix-shim-*-bin.tar.gz

Installation

  1. Extract the distribution tarball:
tar xzf phoenix-shim-<version>-bin.tar.gz
cd phoenix-shim-<version>
  1. Configure the environment variables in conf/phoenix-shim-env.sh:
export JAVA_HOME=/path/to/java
export PHOENIX_SHIM_HOME=/path/to/extracted/phoenix-shim

Configuration

Environment Variables

The following environment variables can be configured:

  • JAVA_HOME: Path to Java installation
  • PHOENIX_SHIM_HOME: Path to Phoenix Shim installation
  • PHOENIX_SHIM_CONF_DIR: Configuration directory (default: $PHOENIX_SHIM_HOME/conf)
  • PHOENIX_SHIM_LOG_DIR: Log directory (default: $PHOENIX_SHIM_HOME/logs)
  • PHOENIX_SHIM_PID_DIR: PID directory (default: /var/run/phoenix-shim)
  • PHOENIX_REST_HEAPSIZE: Maximum heap size (e.g., “2g”)
  • PHOENIX_REST_OFFHEAPSIZE: Maximum off-heap memory size (e.g., “1g”)
  • PHOENIX_REST_OPTS: Additional JVM options
  • PHOENIX_DDB_REST_OPTS: Additional JVM options for REST server

Logging Configuration

Logging can be configured in conf/log4j.properties. The default configuration includes:

  • Console logging
  • File logging with rotation
  • GC logging
  • Heap dumps on OutOfMemoryError

Running the Server

Starting the Server

To start the REST server as a daemon:

bin/phoenix-shim start rest

To start in foreground mode (for debugging):

bin/phoenix-shim rest

Checking Server Status

To check if the server is running:

bin/phoenix-shim status rest

Stopping the Server

To stop the server:

bin/phoenix-shim stop rest

Restarting the Server

To restart the server:

bin/phoenix-shim restart rest

Logs

Logs are stored in the following locations:

  • Main log: $PHOENIX_SHIM_LOG_DIR/rest.log
  • GC log: $PHOENIX_SHIM_LOG_DIR/gc.log
  • Heap dumps: $PHOENIX_SHIM_LOG_DIR/ (on OutOfMemoryError)

📖 Overview

It can be challenging for Salesforce applications/services to maintain different codebases for different substrates if they use the substrate-native NoSQL database. These databases also do not have built-in SOR or Org Migration support.

This is where Phoenix-Shim comes in. It allows developers to write new services (or port their existing services with minimal code changes) using familiar NoSQL semantics while leveraging the scalability and SOR-ness of Salesforce Phoenix.

Salesforce Phoenix, the combined solution of Apache HBase and Apache Phoenix, supported with significant additional tooling for meeting Salesforce System of Record requirements, is a horizontally scalable relational but non-transactional datastore, operating in both 1P and Hyperforce.

🧩 Supported Frontends

DynamoDB

How to use Phoenix-Shim to port their DynamoDB based service to Apache Phoenix?

  • A RESTful API Server that accepts JSON payloads similar to DynamoDB.

By using REST Service, client applications already using any AWS SDKs to connect with DynamoDB does not need to perform any code change. The client application only needs to update the REST endpoint.

Alt text

Supported APIs

  • DDL:
    • CreateTable
    • DeleteTable
    • DescribeTable
    • ListTables
    • UpdateTable
    • UpdateTimeToLive
    • DescribeTimeToLive
  • DQL:
    • Query
    • Scan
    • BatchGetItem
    • GetItem
  • DML:
    • PutItem
    • UpdateItem
    • BatchWriteItem
    • DeleteItem
  • Change Stream:
    • ListStreams
    • DescribeStreams
    • GetShardIterator
    • GetRecords

Connecting with AWS SDK

The Phoenix DynamoDB REST service is fully compatible with AWS SDKs. You can connect to it by simply configuring the endpoint URL to point to your Phoenix REST service instead of the standard DynamoDB endpoint.

📖 For detailed examples and configuration instructions, see the Phoenix DynamoDB REST Service README

How to bring up REST Server in dev env?

  1. Bring up HBase cluster locally. Refer to https://hbase.apache.org/book.html#quickstart
  2. Bring up Phoenix system tables using sqlline (bin/sqlline.py). Refer to https://phoenix.apache.org/installation.html.
  3. Clone phoenix-shim repo.
  4. Build the project with: mvn clean install -DskipTests
  5. Start the REST Server with: bin/phoenix-shim rest start -p <port> -z <zk-quorum> e.g. bin/phoenix-shim rest start -p 8842 -z localhost:2181 to start the server at port 8842 with zk-quorum localhost:2181. Alternative to -z <zk-quorum> is env variable ZOO_KEEPER_QUORUM.
  6. Optional step: To confirm the server is started and functional, run class TestWithLocalRestService by adjusting the endpoint.