# @gizmodata/gizmosql-client 中文文档

规范地址：https://npmcn.com/package/%40gizmodata/gizmosql-client/

版本：2\.2\.3
npm 元数据更新时间：2026-10-15T16:43:22.647Z
中文译文更新时间：2026-11-16T15:00:54.098Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gizmodata/gizmosql-client
原文对照：https://npmcn.com/package/%40gizmodata/gizmosql-client/?lang=original
项目主页：https://github.com/gizmodata/gizmosql-client-js#readme
源码仓库：https://github.com/gizmodata/gizmosql-client-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：132 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2026-01-07T00:18:13.177Z
- 最新版本发布：2026-10-15T16:43:22.265Z
- 近 30 天下载量：5513（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

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

## 安装

```sh
npm install @gizmodata/gizmosql-client
```

也可以使用：`pnpm add @gizmodata/gizmosql-client`、`yarn add @gizmodata/gizmosql-client`、`bun add @gizmodata/gizmosql-client`

## README

# JavaScript/ TypeScript 的 GizmoSQL 客户端

[![GitHub](https://img.shields.io/badge/GitHub-gizmodata%2Fgizmosql--client--js-blue.svg?logo=Github)](https://github.com/gizmodata/gizmosql-client-js) [![npm](https://img.shields.io/badge/npm-@gizmodata%2Fgizmosql--client-red.svg?logo=npm)](https://www.npmjs.com/package/@gizmodata/gizmosql-client)

一个类型脚本/ JavaScript 客户端 [GizmoSQL 游戏](https://github.com/gizmodata/gizmosql) 和 Apache 箭头飞行 SQL 服务器.

## 特征

> **2.0中新建 :** 客户端由 [本地 Go GizmoSQL 亚行驱动程序](https://github.com/gizmodata/gizmosql-adbc) (安装时自动下载)通过 [`@apache-arrow/adbc-driver-manager`](https://www.npmjs.com/package/@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` 占位符),键入箭头值
-   数据库元数据操作(目录、计划、表格)
-   发言稿支助

## 安装

```bash
npm install @gizmodata/gizmosql-client
```

## 快速启动

### 用 TLS 连接到 GizmoSQL

```typescript
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();
```

### 连接选项

```typescript
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 读取](https://github.com/gizmodata/gizmosql-adbc#configuration)。 。 。 .

```typescript
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 认证

```typescript
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 :

```typescript
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 使用身份符号连接:

```typescript
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");
```

### 纯文本连接( 只开发)

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

## 正在启动 GizmoSQL 服务器

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

```bash
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 存储器](https://github.com/gizmodata/gizmosql)。 。 。 .

### 正在挂载您自己的数据库

```bash
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 参考

### 查询执行

```typescript
// 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 箭头 `RecordBatch`as that are pulled from the server as you) 从服务器上提取的像您一样 电极。 提前离开循环(或呼叫) `cancel()`释放 服务器侧流,客户端仍然可用.

```typescript
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`,则 客户端仍然可用.

```typescript
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文本.

```typescript
// 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` 每个占位符各一栏而不是 数组 :

```typescript
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; 旧服务器通过它的 文本形式.

### 数据库元数据

```typescript
// 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 发现

```typescript
// 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.
```

### 发言稿

```typescript
// 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 文档](https://arrow.apache.org/docs/js/) 详细情况.

```typescript
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);
```

## 依赖关系

-   [`@apache-arrow/adbc-driver-manager`](https://www.npmjs.com/package/@apache-arrow/adbc-driver-manager) 装入本地 GizmoSQL 驱动程序库
-   [`apache-arrow`](https://www.npmjs.com/package/apache-arrow) 箭头表/结果和约束参数计划

本地驱动程序库`libadbc_driver_gizmosql`在 从被钉起安装时间 [gizmosql-adbc 发布](https://github.com/gizmodata/gizmosql-adbc/releases) 经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](https://github.com/firetiger-oss/flight-sql-client-js) 最初开发者 [Firetiger 公司](https://github.com/firetiger-oss)我们感谢他们为这个客户所做的基本工作.

## 链接

-   [GizmoSQL 游戏](https://github.com/gizmodata/gizmosql) - 高性能SQL服务器,配有"箭"飞行SQL
-   [GizmoData 数据](https://gizmodata.com/) - GizmoSQL后面的公司
-   [Apache 箭头](https://arrow.apache.org/) - 内栏数据格式
-   [箭头飞行 SQL](https://arrow.apache.org/docs/format/FlightSql.html) - SQL协议规格

## 常见问题

### @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 和提交记录判断。

