@gizmodata/gizmosql-client

中文文档
2.2.3发布于 2026/10/16Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 5513

GizmoSQL 和 Apache 箭头飞行 SQL 的 TypeScript/ JavaScript 客户端

中文使用文档
文档目录26 节
  1. 特征
  2. 安装
  3. 快速启动
  4. 用 TLS 连接到 GizmoSQL
  5. 连接选项
  6. 使用 Bearer Token 认证
  7. OAuth/SSO URL 发现
  8. 正在连接 OAuth/ SSO 托肯
  9. 纯文本连接( 只开发)
  10. 正在启动 GizmoSQL 服务器
  11. 正在挂载您自己的数据库
  12. API 参考
  13. 查询执行
  14. 流出结果
  15. 取消查询和超时
  16. 参数绑定
  17. 数据库元数据
  18. OAuth/SSO 发现
  19. 发言稿
  20. 使用箭头表格工作
  21. 依赖关系
  22. 移动到 2. 0
  23. 所需资源
  24. 许可证
  25. 鸣谢
  26. 链接

JavaScript/ TypeScript 的 GizmoSQL 客户端

GitHub npm

一个类型脚本/ JavaScript 客户端 GizmoSQL 游戏 和 Apache 箭头飞行 SQL 服务器.

特征

2.0中新建 : 客户端由 本地 Go GizmoSQL 亚行驱动程序 (安装时自动下载)通过 @apache-arrow/adbc-driver-manager ——同为Python,Go,C/C++,和R使用的共享驱动程序库. 您可以得到 GizmoSQL 的 DDL/ DML 立即执行( 不需要获取) , INSERT/UPDATE/DELETE ... RETURNING, (中文(简体) ), gizmosql:// TLS 逐一默认 运输,和几何保存 散装摄入,都是一样的 公共API为 1.x. 见 移动到 2. 0 见下文.

  • 完全支持 Apache 箭头飞行 SQL 协议
  • 带有证书验证的 TLS 跳过自签名证书选项
  • 基本认证(用户名/密码)
  • 持有者证书认证
  • OAuth/SSO URL发现
  • 用 Apache 箭头表结果查询执行
  • 成果流动(executeStream作为箭头记录的批次,提前取消
  • 查询取消和客户端截止日期 AbortSignal (服务器中断语句)
  • 参数绑定( E)? 编号 : $1 占位符),键入箭头值
  • 数据库元数据操作(目录、计划、表格)
  • 发言稿支助

安装

npm install @gizmodata/gizmosql-client

快速启动

用 TLS 连接到 GizmoSQL

import { FlightSQLClient } from "@gizmodata/gizmosql-client";

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  tlsSkipVerify: true,  // Skip certificate verification for self-signed certs
  username: "gizmosql",
  password: "your-password",
});

// Execute a query - returns an Apache Arrow Table
const table = await client.execute("SELECT * FROM my_table LIMIT 10");

// Convert to array of row objects
console.log(table.toArray());
// Output: [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, ... ]

await client.close();

连接选项

interface FlightClientConfig {
  host: string;           // Server hostname
  port: number;           // Server port (default: 31337 for GizmoSQL)
  plaintext?: boolean;    // Use unencrypted connection (default: false)
  tlsSkipVerify?: boolean; // Skip TLS certificate verification (default: false)
  username?: string;      // Username for basic auth
  password?: string;      // Password for basic auth
  token?: string;         // Bearer token for token auth
  oauthPort?: number;     // OAuth HTTP port for discoverOAuthUrl() (default: 31339)
  adbcOptions?: Record<string, string>; // Extra driver options (see below)
}

adbcOptions 直接传递给本地的 GizmoSQL ADBC 驱动程序 从以上字段产生的选项(以便它们能够覆盖它们)。 使用 用于驱动程序,例如输入字段不覆盖 每个请求呼叫信头(adbc.flight.sql.rpc.call_header.<name>),自定义 根证书( e)adbc.flight.sql.client_option.tls_root_certs),或 驱动程序内置 OAuth / SSO 流量( 以adbc.gizmosql.auth_type: "external") (中文(简体) ). 完整名单在 gizmosql-adbc 读取。 。 。 .

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  username: "gizmosql",
  password: "your-password",
  adbcOptions: {
    "adbc.flight.sql.rpc.call_header.x-request-id": "abc-123",
  },
});

使用 Bearer Token 认证

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  tlsSkipVerify: true,
  token: "your-bearer-token",
});

OAuth/SSO URL 发现

如果 GizmoSQL 服务器配置了 OAuth/ SSO, 您可以发现 OAuth 基础 URL( 客户端在 HTTPS 上探测服务器的 OAuth HTTP 端点, 然后设定 HTTP ) oauthPort 在配置中, 如果服务器使用非默认端口; 默认 31339 :

import { FlightSQLClient } from "@gizmodata/gizmosql-client";

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  tlsSkipVerify: true,
});

// Discover the OAuth URL (no credentials needed)
const oauthUrl = await client.discoverOAuthUrl();

if (oauthUrl) {
  console.log(`OAuth server URL: ${oauthUrl}`);
  // Use oauthUrl to initiate OAuth flow:
  //   GET ${oauthUrl}/oauth/initiate → { session_uuid, auth_url }
  //   Direct user to auth_url for IdP login
  //   Poll GET ${oauthUrl}/oauth/token/${session_uuid} for the token
  //   Connect with username="token", password=<identity_token>
} else {
  console.log("Server does not have OAuth configured");
}

await client.close();

正在连接 OAuth/ SSO 托肯

在完成 OAuth 流后,通过 Basic Auth 使用身份符号连接:

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  tlsSkipVerify: true,
  username: "token",
  password: identityToken,  // JWT from the OAuth flow
});

const table = await client.execute("SELECT * FROM my_table LIMIT 10");

纯文本连接( 只开发)

const client = new FlightSQLClient({
  host: "localhost",
  port: 31337,
  plaintext: true,  // No TLS encryption
  username: "gizmosql",
  password: "your-password",
});

正在启动 GizmoSQL 服务器

要使用此客户端, 您需要运行的 GizmoSQL 服务器 。 最简单的方法是通过多克:

docker run --name gizmosql \
  --detach --tty --init \
  --publish 31337:31337 \
  --env TLS_ENABLED="1" \
  --env GIZMOSQL_USERNAME="gizmosql" \
  --env GIZMOSQL_PASSWORD="your-password" \
  gizmodata/gizmosql:latest

关于更多选项和配置,见 GizmoSQL 存储器。 。 。 .

正在挂载您自己的数据库

docker run --name gizmosql \
  --detach --tty --init \
  --publish 31337:31337 \
  --mount type=bind,source=$(pwd)/data,target=/opt/gizmosql/data \
  --env TLS_ENABLED="1" \
  --env GIZMOSQL_USERNAME="gizmosql" \
  --env GIZMOSQL_PASSWORD="your-password" \
  --env DATABASE_FILENAME="data/mydb.duckdb" \
  gizmodata/gizmosql:latest

API 参考

查询执行

// Execute a SQL query
const table = await client.execute("SELECT * FROM users WHERE active = true");

// Get results as array
const rows = table.toArray();

// Statements without a result set: returns the affected-row count
const deleted = await client.executeUpdate("DELETE FROM users WHERE active = false");

流出结果

execute() 实现了整个结果。 用于大宗成果 executeStream()时返回 a QueryStream: 具有 Apache 箭头 RecordBatchas that are pulled from the server as you) 从服务器上提取的像您一样 电极。 提前离开循环(或呼叫) cancel()释放 服务器侧流,客户端仍然可用.

const stream = await client.executeStream("SELECT * FROM events ORDER BY ts");
console.log(stream.schema.fields.map((f) => f.name));

let rows = 0;
for await (const batch of stream) {
  rows += batch.numRows;
  if (rows >= 10_000) break; // stop early; no further batches are fetched
}

// Or collect what remains into a Table
const table = await (await client.executeStream("SELECT * FROM small")).toTable();

参数的工作方式与 execute()数字 : client.executeStream("SELECT * FROM t WHERE id > ?", [100])。 。 。 .

executeStream() 一旦服务器完成就解决 执行 页:1 语句; 用于获取行。 执行期间取消,通过 signal (下节.

取消查询和超时

execute(), (中文(简体) ), executeStream() 财务报告和审定财务报表 executeUpdate() 选择 { signal } (标准) AbortSignal) (中文(简体) ). 在服务器时中止它 仍然执行关闭基本的 ADBC 语句; Go 驱动程序继电器 作为航班SQL取消,而GizmoSQL(XQ 1.3.8.0)中断运行 DuckDB 语句. 在获取行时中止 释放结果 流线。 不管是哪种方式 电话拒绝 QueryCancelledError,则 客户端仍然可用.

import { FlightSQLClient, QueryCancelledError } from "@gizmodata/gizmosql-client";

// Client-side deadline: 30 seconds
try {
  const table = await client.execute("SELECT ... FROM huge", undefined, {
    signal: AbortSignal.timeout(30_000),
  });
} catch (err) {
  if (err instanceof QueryCancelledError) {
    console.log("cancelled:", err.reason);
  }
}

// Manual cancellation (e.g. from a UI "stop" button)
const controller = new AbortController();
const pending = client.execute("SELECT ... FROM huge", undefined, { signal: controller.signal });
stopButton.onclick = () => controller.abort();

executeUpdate() 尊重已中止的信号 电话 终止 期间 无法到达运行中的INSER/UPDate/DELTE/DDL 驱动程序尚未: @apache-arrow/adbc-driver-manager (0.24) 释放 本地语句仅在屏蔽更新返回后, 所以该语句 并返回受影响的行数。 (捆绑) gizmosql-adbc 2.0.12 声明取消飞行中更新 因此,一旦Node.js 驱动管理器曝光,就解决了 取消或急于释放手柄。 )

服务器侧选项, 覆盖 DML/ DDL : SET gizmosql.query_timeout = <seconds> 在会话上让 GizmoSQL 中断任何正在运行的语句 长于此(呼号以"超时"拒绝) FlightSQLError) (中文(简体) ). GizmoSQL \\ 1.38.0 也中断客户端程序已失效的语句或 放弃连接.

请注意: close() 在客户端有 没有 取消一个声明,即 仍在执行(驱动程序管理器仅在 语句完成; 使用 a signal 对于这个.

参数绑定

传递值 ? (或 $1, (中文(简体) ), $2,.)占位符作为第二个占位符 参数。 它们通过一个 ABBC 作为键入箭头数据发送给服务器 准备的声明——从未插入SQL文本.

// Positional parameters, in placeholder order
const table = await client.execute(
  "SELECT id, name FROM users WHERE id = ? AND name = ?",
  [42, "Alice"]
);

// DML with parameters; returns the affected-row count
const inserted = await client.executeUpdate(
  "INSERT INTO events (id, kind, score, seen_at, payload) VALUES (?, ?, ?, ?, ?)",
  [7, "login", 0.75, new Date(), new Uint8Array([1, 2, 3])]
);

JavaScript 映射到箭头类型的地图如下:

JS 价值发送箭头类型
string点f8
整数 number英寸 32, 或 32 位外的 Int64
其他项目 number浮点64
bigint内置64
boolean布尔
Date时间戳( 毫升秒, UTC)
Uint8Array 编号 : Buffer二进制
null 编号 : undefined无

对于箭头类型的完全控制(十进制,日期32,.),通过 a 单行 apache-arrow Table 每个占位符各一栏而不是 数组 :

import { Table, vectorFromArray, Int32, Utf8 } from "apache-arrow";

const params = new Table({
  id: vectorFromArray([42], new Int32()),
  name: vectorFromArray(["Alice"], new Utf8()),
});
const table = await client.execute(
  "SELECT id, name FROM users WHERE id = ? AND name = ?",
  params
);

注释:

  • GizmoSQL 每个执行都绑定一个参数集,所以是一个参数 Table 必须包含精确一行(多行负载使用批量吸收).
  • 服务器类型不能从上下文推断的占位符(如:. SELECT ?必须投出: SELECT ?::INTEGER。 。 。 .
  • null 参数和包含 NUL 字节的二进制需要 GizmoSQL 1.38.1; 旧服务器通过它的 文本形式.

数据库元数据

// Get all catalogs
const catalogs = await client.getCatalogs();

// Get schemas (optionally filtered by catalog)
const schemas = await client.getSchemas("my_catalog");

// Get tables (with optional filters)
const tables = await client.getTables(
  "my_catalog",    // catalog (optional)
  "my_schema",     // schema pattern (optional)
  "my_table%",     // table name pattern (optional)
  ["TABLE", "VIEW"] // table types (optional)
);

// Get table types
const tableTypes = await client.getTableTypes();

OAuth/SSO 发现

// Discover OAuth URL from server (no credentials required)
const oauthUrl = await client.discoverOAuthUrl();
// Returns the OAuth base URL (e.g., "http://localhost:31339"), or null
// if the server does not have OAuth configured.

发言稿

// Prepare a statement with placeholders
const prepared = await client.prepare("SELECT * FROM users WHERE id = ?");

// Execute it repeatedly with different parameter values
const alice = await client.executePrepared(prepared, [1]);
const bob = await client.executePrepared(prepared, [2]);

// Close the prepared statement
await client.closePrepared(prepared);

使用箭头表格工作

这个 execute() 方法返回 Apache 箭头 Table 对象。 见 Apache Arow JS 文档 详细情况.

const table = await client.execute("SELECT id, name, score FROM players");

// Get column by name
const names = table.getChild("name");

// Iterate over rows
for (const row of table) {
  console.log(row.id, row.name, row.score);
}

// Convert to array of objects
const rows = table.toArray();

// Get schema information
console.log(table.schema.fields);

依赖关系

本地驱动程序库libadbc_driver_gizmosql在 从被钉起安装时间 gizmosql-adbc 发布 经SHA-256核实(见 driver-manifest.json; 以 node scripts/pin-driver.mjs <version>) (中文(简体) ). 离线/空载安装可设置 GIZMOSQL_DRIVER_SKIP_DOWNLOAD=1 和点 GIZMOSQL_DRIVER_LIB 以美元计 当地建造的图书馆(make -C gizmosql-adbc/go lib) (中文(简体) ).

移动到 2. 0

2.0 保留 FlightSQLClient API兼容1.x. 断开 变化位于边缘:

  • 节点.js 22 需要(本地的ABBC驱动管理加通).
  • FlightClient (低层飞行RPC级)被删除,随行 与生成的原生出和 @grpc/grpc-js 依赖性。 若为 您使用原始的飞行RPC,使用 ABC API 或 GO 驱动程序直接.
  • discoverOAuthUrl() 探测服务器的 OAuth HTTP 端点 (可以通过新的 oauthPort 选项,默认为31339 使用GRPC握手头,标准部署结果相同.
  • PreparedStatement.handle 现在是一个不透明的客户端标识符 parameterSchema编号 :resultSchema 不再居住(亚银管理) 服务器侧已准备状态 .

所需资源

  • 节点.js 22 (>=22.12- require() 来自 CommunityJS 的软件包
  • 该套件作为ES模块发布. 无害环境管理: import { FlightSQLClient } from "@gizmodata/gizmosql-client"。 。 。 . 常见JS : const { FlightSQLClient } = require("@gizmodata/gizmosql-client") 在节点上工作 22.12.

许可证

Apache 许可证 2.0

鸣谢

这个项目是一个叉子 飞行-sql-客户-js 最初开发者 Firetiger 公司我们感谢他们为这个客户所做的基本工作.

版本与发布记录

@gizmodata/gizmosql-client 共发布 18 个版本,首次发布于 2026/01/07;过去 12 个月发布了 18 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.2.3latest2026/10/161 个月前
2.2.22026/10/011 个月前
2.2.12026/09/102 个月前
2.2.02026/09/042 个月前
2.1.02026/09/032 个月前
2.0.12026/08/252 个月前

关于 @gizmodata/gizmosql-client 的常见问题

@gizmodata/gizmosql-client 是什么?

GizmoSQL 和 Apache 箭头飞行 SQL 的 TypeScript/ JavaScript 客户端

如何安装 @gizmodata/gizmosql-client?

在项目目录运行 npm install @gizmodata/gizmosql-client,或使用 pnpm add / yarn add / bun add。

@gizmodata/gizmosql-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gizmodata/gizmosql-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gizmodata/gizmosql-client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gizmodata/gizmosql-client 可以商用吗?

@gizmodata/gizmosql-client 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gizmodata/gizmosql-client 的下载量有多少?

根据 npm 官方下载统计,@gizmodata/gizmosql-client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,513 次,日均约 184 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gizmodata/gizmosql-client 还在维护吗?

最新版本 2.2.3 发布于 2026/10/16(1 个月前);至今共发布 18 个版本,其中过去 12 个月发布了 18 个;首次发布于 2026/01/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。