JavaScript/ TypeScript 的 GizmoSQL 客户端
一个类型脚本/ 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);
依赖关系
@apache-arrow/adbc-driver-manager装入本地 GizmoSQL 驱动程序库apache-arrow箭头表/结果和约束参数计划
本地驱动程序库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 公司我们感谢他们为这个客户所做的基本工作.
链接
- GizmoSQL 游戏 - 高性能SQL服务器,配有"箭"飞行SQL
- GizmoData 数据 - GizmoSQL后面的公司
- Apache 箭头 - 内栏数据格式
- 箭头飞行 SQL - SQL协议规格