Phoenix JDBC 使用教程

更新时间：2026-07-21

功能概述

Apache Phoenix 是构建在 HBase 之上的 SQL 引擎，允许开发者使用标准的 JDBC API 和 SQL 语句来操作 HBase 中的数据，从而降低 HBase 的使用门槛。

需要特别注意的一点：Phoenix 使用 UPSERT 语句写入数据，而非标准 SQL 的 INSERT。

前提条件

已创建 HBase 类型集群，且集群版本为 BMR HBase 2.4.18 及以上。创建集群详情请参考创建集群。
已获取集群 Master 节点的登录方式（内网 IP、绑定 EIP 或 VNC 控制台登录），SSH 登录方式请参考SSH连接到集群。
本地代码编译环境
- JDK 1.8 及以上
- Maven 构建工具
- 可连通集群 Zookeeper 节点（默认端口 2181）的网络环境

一、新建 Maven 工程

在目标目录下运行以下命令创建 Maven 项目：

                Shell
                
                mvn archetype:generate -DgroupId=$yourgroupID -DartifactId=$yourartifactID -DarchetypeArtifactId=maven-archetype-quickstart

参数说明：

$yourgroupID：包名（groupId）
$yourartifactID：项目名称（artifactId）
maven-archetype-quickstart：表示创建标准 Maven Java 项目

生成的工程结构中，重点关注：

根目录下的 pom.xml：依赖与打包配置
src/main/java：源码目录

二、添加 Phoenix 依赖

编辑 pom.xml，添加 Phoenix 相关依赖。版本需与集群保持一致，这里使用 5.1.2。

2.1 properties 与 dependencies

                XML
                
            

                <properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <phoenix.version>5.2.1</phoenix.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.apache.phoenix</groupId>
    <artifactId>phoenix-hbase-compat-2.4.1</artifactId>
    <version>${phoenix.version}</version>
  </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-1.2-api</artifactId>
      <version>2.20.0</version>
    </dependency>
</dependencies>
            

2.2 打包配置（build 部分）

使用 maven-assembly-plugin 将依赖一起打入 jar 包，便于在集群节点上直接运行。

                XML
                
            

                <build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
        <encoding>utf-8</encoding>
      </configuration>
    </plugin>
    <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
      <configuration>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
      </configuration>
      <executions>
        <execution>
          <id>make-assembly</id>
          <phase>package</phase>
          <goals>
            <goal>single</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
            

三、JDBC 连接字符串格式

Phoenix JDBC 连接 URL 的组成如下：

Plain Text

1jdbc:phoenix:<zk_ip1>,<zk_ip2>,<zk_ip3>:2181:<znodeParent>

参数说明，可从 BMR 集群 Master 节点 /opt/bmr/hbase/conf/hbase-site.xml 配置文件中获取

参数	说明
`zk_ip1`、`zk_ip2`、`zk_ip3`	Zookeeper 节点的内网 IP，对应 HBase 配置文件 `hbase-site.xml` 中 `hbase.zookeeper.quorum` 参数的值
`2181`	Zookeeper 默认监听端口
`znodeParent`	对应 HBase 配置文件 `hbase-site.xml` 中 `zookeeper.znode.parent` 参数的值

驱动类为：org.apache.phoenix.jdbc.PhoenixDriver

四、编写示例代码

在 src/main/java 下创建类，示例演示了：注册驱动、创建连接、建表、插入（UPSERT）数据、查询数据。

                Java
                
            

                package Phoenix;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class PhoenixJdbc {

    // 静态代码块中注册 Phoenix JDBC 驱动
    static {
        try {
            Class.forName("org.apache.phoenix.jdbc.PhoenixDriver");
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        String createSql = "create table if not exists user_tb("
                + "id VARCHAR,"
                + "uname VARCHAR "
                + "CONSTRAINT pk PRIMARY KEY (id))";

        Connection connection = null;
        try {
            // 拼接连接字符串：jdbc:phoenix:<zk节点>:2181:<znodeParent>
            String ipList = "${zk_ip1},${zk_ip2},${zk_ip3}:2181";
            String znodeParent = "${znodeParent}";
            String url = "jdbc:phoenix:" + ipList + ":" + znodeParent;

            connection = DriverManager.getConnection(url);
            Statement statement = connection.createStatement();

            // 建表
            statement.executeUpdate(createSql);

            // 插入数据：注意 Phoenix 使用 upsert 而非 insert
            statement.executeUpdate("upsert into user_tb values ('1','张三')");
            statement.executeUpdate("upsert into user_tb values ('2','李四')");

            // DML 操作后需要提交事务
            connection.commit();

            // 查询数据
            ResultSet rs = statement.executeQuery("select * from user_tb");
            while (rs.next()) {
                System.out.println(rs.getString("id") + "\t" + rs.getString("uname"));
            }

            rs.close();
            statement.close();
        } catch (SQLException throwables) {
            throwables.printStackTrace();
        } finally {
            if (connection != null) {
                try {
                    connection.close();
                } catch (SQLException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}
            

关键操作说明：

建表：create table if not exists user_tb(...)
主键：通过 CONSTRAINT pk PRIMARY KEY (id) 指定
插入数据：Phoenix 使用 upsert into，语义为「存在则更新，不存在则插入」
提交事务：执行 DML 后需调用 connection.commit()
查询数据：使用标准 statement.executeQuery("select * from user_tb")

五、编译打包与上传

5.1 编译打包

Shell

1mvn package

打包成功后，会在 target 目录下生成带依赖的 jar 包（*-jar-with-dependencies.jar）。

5.2 上传到集群节点

将 jar 包上传到 BMR 集群的 Master 节点（同 VPC 拷贝/绑定公网 IP/Bos 上传下载等方式）

                Shell
                
                scp $localfile root@公网IP地址:$remotefolder

六、运行样例

                Shell
                
                su hadoop
java -cp "/opt/bmr/hbase/conf/hbase-site.xml:$jar包名" $类全限定名