Flink JDBC Driver把 Flink SQL Gateway 变成“数据库”，让 BI / 工具 / 应用直接用 JDBC 跑 Flink SQL

1. 整体架构与核心概念

推荐你在文章这里放一张架构图（如果你要配图：Client/BI/App → JDBC Driver → SQL Gateway → Flink Cluster）。

核心点：

JDBC Driver ：Java 库，提供 jdbc:flink://... 协议实现
SQL Gateway：真正的"服务端"，对外暴露 REST Endpoint（或 HiveServer2 Endpoint）
Flink Cluster：真正跑 job 的地方

还有一个重要补充：

你也可以用 Hive JDBC Driver 连 Flink（当你运行 Hive dialect SQL，并且想更好用 HiveCatalog / Hive 函数时），但前提是你启动 SQL Gateway 时启用 HiveServer2 endpoint。

2. 使用前提：先启动 SQL Gateway

使用 Flink JDBC Driver 之前必须先启动 SQL Gateway，并让它连接到一个运行中的 Flink 集群。

要点就一句话：
SQL Gateway 是 JDBC 的"服务器端"，JDBC Driver 只是客户端。

你连的地址通常是（示例）：
jdbc:flink://localhost:8083

如果你在生产环境，一般是：
jdbc:flink://<sql-gateway-host>:<port>

3. 依赖与获取方式

Flink 把 JDBC Driver 的依赖都打进了一个 bundle：

GroupId：org.apache.flink
ArtifactId：flink-sql-jdbc-driver-bundle
Jar：flink-sql-jdbc-driver-bundle-{VERSION}.jar

Maven 依赖：

xml 复制代码

<dependency>
  <groupId>org.apache.flink</groupId>
  <artifactId>flink-sql-jdbc-driver-bundle</artifactId>
  <version>{VERSION}</version>
</dependency>

注意点：

Flink JDBC driver 不包含在 Flink 发行包里，需要你自己从 Maven 下载/引入
某些客户端工具还需要 slf4j-api-{slf4j.version}.jar（至少需要 API 包，具体是否需要 binding 看你的运行环境）

4. 命令行连接方式一：Beeline

Beeline 虽然是 Hive 的 CLI，但它支持通用 JDBC，所以可以直接拿来连 Flink SQL Gateway。

步骤：

1）下载 flink-jdbc-driver-bundle-{VERSION}.jar，放到 $HIVE_HOME/lib

2）运行 beeline，连接：

sql 复制代码

!connect jdbc:flink://localhost:8083

Flink SQL Gateway 当前会忽略用户名密码，所以直接回车即可。

示例流程（非常适合写在博客里）：

sql 复制代码

CREATE TABLE T(
  a INT,
  b VARCHAR(10)
) WITH (
  'connector' = 'filesystem',
  'path' = 'file:///tmp/T.csv',
  'format' = 'csv'
);

INSERT INTO T VALUES (1, 'Hi'), (2, 'Hello');

SELECT * FROM T;

你会看到：

INSERT 返回一个 job id（说明：Flink 在后台提交了作业）
SELECT 返回结果集

5. 命令行连接方式二：SQLLine

SQLLine 更轻量，也是通用 JDBC CLI。

使用要点：

先编译 SQLLine（示例：./mvnw package -DskipTests）
把两个 jar 放到 SQLLine target 目录
- flink-jdbc-driver-bundle-{VERSION}.jar
- slf4j-api-{slf4j.version}.jar
启动：./bin/sqlline
连接：!connect jdbc:flink://localhost:8083

后续执行 SQL 与 beeline 类似。

适用场景建议：

你只是想快速验证 SQL Gateway / Driver 是否可用：SQLLine 足够
你本身就有 Hive 环境：Beeline 上手更快

6. BI 工具接入：Tableau

Tableau 支持 "Other Database (JDBC)"（要求版本 >= 2018.3）。

步骤：

1）下载 flink-jdbc-driver-(VERSION).jar 放到 Tableau 驱动目录

Windows：C:\Program Files\Tableau\Drivers
Mac：~/Library/Tableau/Drivers
Linux：/opt/tableau/tableau_driver/jdbc

2）Tableau 里选择：

Connect → Other Database (JDBC)
URL 填：jdbc:flink://<gateway-host>:<port>
Dialect 选 SQL92
用户名密码留空（当前 gateway 忽略）

典型落地建议：

适合做：看表、跑查询、做报表（尤其是基于 Flink SQL 的实时/近实时分析视图）
注意：持续更新的流式结果集并不适合传统 BI 交互（BI 更擅长"查询得到一个相对稳定的结果集"）

7. Java 应用接入：像连数据库一样执行 Flink SQL

7.1 DriverManager 方式

java 复制代码

try (Connection connection = DriverManager.getConnection("jdbc:flink://localhost:8083")) {
  try (Statement statement = connection.createStatement()) {

    statement.execute("CREATE TABLE T(\n" +
        "  a INT,\n" +
        "  b VARCHAR(10)\n" +
        ") WITH (\n" +
        "  'connector' = 'filesystem',\n" +
        "  'path' = 'file:///tmp/T.csv',\n" +
        "  'format' = 'csv'\n" +
        ")");

    statement.execute("INSERT INTO T VALUES (1, 'Hi'), (2, 'Hello')");

    try (ResultSet rs = statement.executeQuery("SELECT * FROM T")) {
      while (rs.next()) {
        System.out.println(rs.getInt(1) + ", " + rs.getString(2));
      }
    }
  }
}

你会得到：

复制代码

1, Hi
2, Hello

7.2 DataSource 方式

java 复制代码

DataSource dataSource = new FlinkDataSource("jdbc:flink://localhost:8083", new Properties());
try (Connection connection = dataSource.getConnection()) {
  ...
}

建议你在博客里补一句：

DataSource 方式更容易和连接池/框架集成（比如 Spring、MyBatis、JOOQ 等）。

8. 和 MyBatis / Spring Data / JOOQ 的关系：能不能直接用？

可以，原理是一样的：

这些框架本质就是走 JDBC API。只要你把 driver 换成 Flink JDBC driver，并把 JDBC URL 指向 SQL Gateway，它们就会把 SQL 发给 Flink 执行。

但要注意两点（生产很关键）：

1）不是所有 SQL 都适合

Flink SQL 有自己的语义（流式、作业提交、持续查询、动态表），你不能指望它完全等价于传统 OLTP 数据库。

2）INSERT/持续作业的返回不是"影响行数"

你更可能得到 job id，或者需要异步跟踪执行状态。

9. 常见坑与排查清单

你发 CSDN 这类博客，读者最爱看的就是"踩坑部分"，建议加上：

连接不上：先确认 SQL Gateway 端口对外可达（防火墙/反向代理/内网域名）
依赖冲突：JDBC bundle 已经打包了依赖，项目里再引入一堆 table/planner 依赖可能冲突
SLF4J 报错：缺少 slf4j binding 时会提示找不到实现（不影响功能但影响日志）
用户名密码：目前 gateway 可能忽略，但生产通常会在 gateway 前面加认证层（如 API 网关、反向代理、mTLS 等）
"SELECT 卡住"：如果你跑的是流式持续查询，结果集可能不会自然结束（CLI/BI 会表现为一直在跑）

10. 一句话总结：它解决的是"接入标准化"

Flink JDBC Driver 的定位非常明确：

对外：统一 JDBC 接入（CLI / BI / 应用 / 框架都能用）
对内：统一把 SQL 提交给 SQL Gateway，由 Gateway 管会话与作业提交
对团队：把 Flink SQL 的使用门槛降到"会 JDBC 就能用"

如果你接下来要把你前面写的 Catalog / Modules / Procedures / PTF 串起来，我建议你在本文结尾加一个"实战组合章节"：

Catalog：把 Hive / JDBC / 外部元数据接进来
Modules：把 Hive 函数/自定义函数变成系统内置函数
Procedures：把"管理/运维/调度动作"做成可 CALL 的入口
PTF：把复杂状态/定时/规则处理做成"可复用 SQL 算子"
JDBC Driver：把这整套能力开放给外部系统统一访问