JavaScript 和 TypeScript 的查询硬充电机: hardcharger:// URLs,回箭头.
这是什么?
JavaScript/ TypeScript 客户端 硬充电机, (中文(简体) ),
GizmoDataTM DuckDB 2.0服务器. 硬充电器说话 电线, (中文(简体) ),
所以这个包是薄的一层 充电JavaScript 客户端
(单位:千美元)@gizmodata/chargewire),它依赖和再出口,方式
adbc-驱动硬充电器 坐在电荷线上
驱动程序 硬充电器-jdbc 在充电器 JDBC 上
驾驶员。 它补充说:
- 🏎️
hardcharger://URL( URL),以硬充电器的端口为默认值 31337 (443 a GizmoData) Cloud host),在亚投行驱动器中确切的意思; - 🪪
authType: "mtls",用于客户证书签入的亚行和JDBC驱动程序名称; - 🏷️ 硬充电器名称 用于充电客户端的班级(
HardchargerError, (中文(简体) ),HardchargerConnection, (中文(简体) ),HardchargerErrorCode:相同对象,所以instanceof工作内容 和两个名字.
其它一切,从"箭"结果和约束参数 到分裂结果,摄取,
交易,取消, TLS 和客户端证书, 是充电客户端的: 节点,浏览器,
德诺,邦和克洛德夫莱尔工人,没有本土代码. 它的整个API通过这个包裹,
所以你从不导入 @gizmodata/chargewire 你自己来 用于充电器以外的服务器
硬充电器, 使用 @gizmodata/chargewire 直接说.
状态: 2.5.0,加硬充电2.13.0. 建造在
@gizmodata/chargewire2.4.0 (电线-js)30ed33b,充电协议1.0.0hardcharger-server从硬充电器主 树枝.
| 软件包 | 这是什么 |
|---|---|
@gizmodata/hardcharger | 此客户端 : hardcharger:// URL, 硬充电器名称, 所有下方 |
@gizmodata/chargewire | 用于任何充电服务器的通用充电客户端 |
pip install adbc-driver-hardcharger | aBC 驱动程序: Python, C/C++, Go, R, Rst |
hardcharger-jdbc | jDBC 驱动程序: Java, DBeaver 和其他 JDBC 工具 |
快速启动
启动服务器(即 硬充电器 已经 多克和安装器 :
HARDCHARGER_ADMIN_PASSWORD=change-me hardcharger-server
然后,从 实例/快速启动.mjs数字 :
import { tableFromArrays } from "apache-arrow";
import { HardchargerError, connect } from "@gizmodata/hardcharger";
const conn = await connect({
url: "hardcharger://localhost?tls=false",
username: "hardcharger",
password: "change-me",
});
// A query, with bind parameters: an Arrow Table back.
const table = await conn.query("SELECT 42 AS answer, ?::VARCHAR AS greeting", ["hello"]);
console.log(table.toArray().map((row) => row.toJSON()));
// A big result, read in several partitions at once.
let rows = 0;
for await (const batch of conn.stream("SELECT * FROM range(10000000)")) rows += batch.numRows;
console.log(`streamed ${rows} rows`);
// Bulk ingest from Arrow, then a transaction (it rolls back if the function throws).
await conn.ingest("events", tableFromArrays({ id: Int32Array.from([1, 2, 3]) }), { mode: "replace" });
await conn.transaction(async (tx) => {
await tx.execute("DELETE FROM events WHERE id = ?", [1]);
});
console.log((await conn.query("SELECT count(*) AS n FROM events")).get(0).toJSON());
// Errors carry the server's code; an AbortSignal cancels the statement on the server.
try {
await conn.query("SELECT count(*) FROM range(1000000000000)", undefined, { signal: AbortSignal.timeout(1000) });
} catch (err) {
if (!(err instanceof HardchargerError)) throw err;
console.log(`${err.code}: ${err.message}`);
}
await conn.close();
[ { answer: 42, greeting: 'hello' } ]
streamed 10000000 rows
{ n: 2n }
statement_timeout: the operation timed out (its AbortSignal fired)
import * as hardcharger from "@gizmodata/hardcharger" 读作Python的驱动程序
from adbc_driver_hardcharger import dbapi as hardcharger数字 : hardcharger.connect({ url, ... })。 。 。 .
结果为: Apache 箭头 桌子和录音盒,所以
apache-arrow 21.2 或后为对等依赖:在此包旁安装.
安装中
npm install @gizmodata/hardcharger apache-arrow
@gizmodata/chargewire 随它而来; apache-arrow (21.2或后期)是同伴的依赖,所以您
应用程序和客户端共享 Arow 类的一个副本.
QQ URL 语句
| 網址 | 含义 |
|---|---|
hardcharger://host | HTTPS 改为 host:31337 (单位:千美元)host:443 为GizmoData云) |
hardcharger://host:port | HTTPS 到另一个端口 |
hardcharger://host?tls=false | Plain HTTP( 开发, 回转) |
hardcharger://host:port/custom/prefix | 服务器安装充电线 /custom/prefix |
chargewire://…, (中文(简体) ), https://…, (中文(简体) ), http://… | 充电客户端的拼写,其实是 |
hardcharger:// 确切的说就是电线 chargewire:// 除非 URL 说
?tls=false (或 tls=0· ; true 财务报告和审定财务报表 1 留着它). 这些是 URL 的 ADBC 驱动程序
接受这个建议。 拒绝之前,任何东西发送, 每一个有一个 client_invalid_argument 错误说明原因 :
hardcharger+http://…和所有别的东西hardcharger+…方案:故意设置 普通 HTTP 的拼写,?tls=false每个充电客户端都一样;jdbc:hardcharger://…,则auseEncryption参数( JDBC 驱动程序属性): 留言要丢弃jdbc:和使用情况?tls=false· ;- uRL中的证书( 通过)
username财务报告和审定财务报表password),任何其他URL参数,一个URL 没有主机或计划 客户不知道.
吉相达多云. A 类 hardcharger:// 没有端口和 GizmoData 云主机的 URL
(单位:千美元)gizmodata.com,或其中的任何名称,例如 my-cluster.us-east-1.aws.gizmodata.com,任意
case, a 线索点允许)去443号港口,GizmoData Cloud cluster 回答,而不是31337. 只有整个标签匹配,所以 evilgizmodata.com 财务报告和审定财务报表 gizmodata.com.example.org 保留31337,
和明确端口总是获胜(hardcharger://my-cluster.gizmodata.com:31337 是端口31337.
isGizmodataCloudHost(host) 财务报告和审定财务报表 gizmodataCloudPort (443)在代码中同样表示.
parseUrl(url) 显示一个 URL 站点的充电线基 URL(hardcharger://db.example.com →
https://db.example.com:31337/chargewire并抛出上述错误; schemesFor(url) 这是
方案地图 connect 手动该 URL 的充电客户端(schemes,以端口 443 表示一个
GizmoData Cloud 主机),负责解析.
QQ 选项
connect 使用充电客户端的选项, 并带有默认值: 一个证书
(单位:千美元)username 财务报告和审定财务报表 password, (中文(简体) ), token, (中文(简体) ), tokenProvider, (中文(简体) ), subjectToken 用于SSO 令牌交换,或
authType: "client_certificate", (中文(简体) ), tls (单位:千美元)ca, (中文(简体) ), cert, (中文(简体) ), key, (中文(简体) ), servername, (中文(简体) ), skipVerify· ;
节点、德诺和邦, catalog, (中文(简体) ), schema, (中文(简体) ), sessionOptions,重复和声明
缺省数(resultPartitions8个在节点,4个在浏览器; resultOrder, (中文(简体) ), async, (中文(简体) ),
retainResult, (中文(简体) ), statementTimeoutMs, (中文(简体) ), queryTag, (中文(简体) ), ipcCompression) (中文(简体) ). 这个
充电客户端的 README 描述
每一个。 不同之处:
| 选项 | 给 |
|---|---|
url | (单位:千美元) hardcharger:// URL( 以上) |
authType | (单位:千美元) "mtls",与 "client_certificate",以及 "external",与 "oauth_browser" (如亚行和JDBC驱动程序) |
schemes | 未取: URL 方案是此软件包的( 使用) @gizmodata/chargewire 方案) |
logger | 警告( 服务器丢失和客户端被替换的会话, 例如) 被打印为 [hardcharger] |
目前的目录和计划. catalog 财务报告和审定财务报表 schema 授予 connect,或稍后设置为
conn.setOptions({ catalog, schema }),是会话当前的目录和计划. 鉴于
在一个电话里 他们给目录的图案起名 以哪个为首 设置 catalog
单移动会话到目录的默认方案, 如 SQL USE 和一套计划
在它被遗忘之前: 一个新的会话取代一个丢失的会话, 懒惰的连接的第一个
会话, 在目录的默认计划中打开 。 要在另一个目录的 计划,设置两个
或者目录之后的图案.
一个正在恢复的服务器 . 正在重新开始的已停止的服务器( GizmoData Cloud 集群)
自动重现) 答案 server_resuming 带有 Retry-After。客户端等待并发送
同样的请求,包括登录,最多 resumeTimeout 秒( 默认) 600· ; 0
将第一个答复报告为: server_resuming) (中文(简体) ). onResuming 在每个等待之前叫着
与 { attempt, retryAfterMs, elapsedMs, resumeTimeoutMs, detail },所以一个应用可以说"the
服务器正在恢复“ 而不是查看被冻结; 中止 connect"或一个电话" signal 停下来
等一会儿 一个例外 onResuming 丢弃被忽略 .
import { connect } from "@gizmodata/hardcharger";
const controller = new AbortController(); // a Cancel button calls controller.abort()
const conn = await connect({
url: "hardcharger://db.example.com",
username: "joe",
password,
resumeTimeout: 300,
signal: controller.signal,
onResuming: ({ attempt, elapsedMs }) =>
console.log(`the server is resuming (attempt ${attempt}, ${Math.round(elapsedMs / 1000)} s)`),
});
QQ 只读连接
import { connect } from "@gizmodata/hardcharger";
const conn = await connect({
url,
username,
password,
sessionOptions: { read_only: true },
});
try {
console.log((await conn.query("SELECT 42 AS answer")).toArray());
} finally {
await conn.close();
}
使用您的连接细节 url, (中文(简体) ), username 财务报告和审定财务报表 password。客户端要求
options.read_only: true 在使用会话之前从服务器中跳出。 您也可以打电话
await conn.setOptions({ read_only: true }) 连接。 限制
是单向的;打开单独的连接来写入。 懒惰的连接在他们身上确认
并再次确认限制.
拒绝或忽略选项的旧服务器会造成错误, 绝不是可写回的倒置 .
省略它的连接继续和旧服务器工作. 只读不批准
添加权限或沙盒管理员-安装扩展代码.
QQ 客户端证书登录( 互通 TLS)
当服务器验证客户端证书并让他们签名时,证书就是 证书:没有用户名或密码.
HARDCHARGER_ADMIN_PASSWORD=change-me hardcharger-server --tls-cert server.pem --tls-key server-key.pem \
--mtls-ca-cert client-ca.pem --mtls-certificate-sign-in --mtls-admin-identities [email protected]
从 实例/mtls.mjs数字 :
import { readFileSync } from "node:fs";
import { connect } from "@gizmodata/hardcharger";
const conn = await connect({
url: "hardcharger://localhost",
authType: "client_certificate",
tls: {
ca: readFileSync("server-ca.pem", "utf8"), // when the server's CA is private
cert: readFileSync("client.pem", "utf8"),
key: readFileSync("client-key.pem", "utf8"),
},
});
console.log((await conn.query("SELECT HARDCHARGER_USER() AS who")).getChild("who").get(0));
await conn.close();
[email protected]
身份是证书的电子邮件 SAN,除非服务器另有说明
(单位:千美元)--mtls-identity-source它必须是其中之一 --mtls-admin-identities 或,进入
控制,商店的用户。 服务器发行的符号受证书的约束,以及
客户端打开的每一个连接( 分割结果的分区, 上传) 都会显示它 。 这个
客户端拒绝旁边的用户名、密码或代号, 丢失 tls.cert 或者说 tls.key,以及
发送任何文件前的 plain-HTTP URL 和不提供证书签名的服务器
与 not_implemented。服务器的拒绝保留其代码,每个代码都有HTTP 401:
unknown_certificate_identity, (中文(简体) ), certificate_required, (中文(简体) ), certificate_revoked, (中文(简体) ),
certificate_mismatch 财务报告和审定财务报表 certificate_identity_mismatch。在浏览器中,证书是
用户从浏览器商店中选择的,所以没有 tls 选项
充电客户端的 README
有细节.
QQ 浏览器登录( SSO)
当硬充电器-服务器将人与身份提供者签入时(--oauth-client-id, (中文(简体) ),
--oauth-client-secret,在 --token-allowed-issuer, (中文(简体) ), authType: "external"
在浏览器中显示为您 . openUrl 打开(或显示)登录的 URL; 服务器
与提供者完成签入,客户端收集Hardcharmer自己的访问符.
import { exec } from "node:child_process";
import { connect } from "@gizmodata/hardcharger";
const conn = await connect({
url: "hardcharger://db.example.com",
authType: "external",
openUrl: (url) => void exec(`open ${JSON.stringify(url)}`),
});
步骤startBrowserSignIn, (中文(简体) ), pollBrowserSignIn, (中文(简体) ), browserSignIn和网络的助手
回到自己的页面beginBrowserRedirectSignIn, (中文(简体) ), completeBrowserRedirectSignIn(中文(简体) )
是充电客户端的,拿 hardcharger:// URL 这里; 参见其
读取。服务器的登录
在其主要港口居住;没有单独的登录港.
失败的登录会丢出流码( I)access_denied 当该人或提供者拒绝的时候,
identity_provider_error, (中文(简体) ), invalid_credentials 对于服务器不允许的用户),没有
HTTP 密码 status: 决定 code。错误的或被用过的流量是 flow_not_found,而且没有
完成于 browserSignInTimeoutMs (单位:千美元)timeoutMs 页:1 browserSignIn)为
client_sign_in_timeout。 。 。 .
QQ 浏览器, Deno, Bun and Workers
每个运行时间都有一个建筑服务:这个层没有特定平台代码,它会导入
@gizmodata/chargewire 因此,你的捆绑者或运行时间 选择包自己的构建通过
出口条件node 节点、德诺和邦; default 用于浏览器和边缘运行时间.
浏览器测试此包与 esbuilt 捆绑到浏览器中, 检查捆绑是否握有
充电客户端的浏览器正在构建,然后在 Chromium 和 WebKit 中运行,以对抗服务器
允许页面的出处(hardcharger-server --cors-origins https://app.example.com),与
和Node的电话一样.
• API
| 导出 | 这是什么 |
|---|---|
connect(options) | (单位:千美元) Connection (单位:千美元)HardchargerConnection: query, (中文(简体) ), stream, (中文(简体) ), execute, (中文(简体) ), prepare, (中文(简体) ), ingest, (中文(简体) ), metadata, (中文(简体) ), transaction, (中文(简体) ), close,, , , , , , , , . |
HardchargerError (= (单位:千美元) ChargewireError(中文(简体) ) | 客户端引起的每一个错误 : code, (中文(简体) ), status, (中文(简体) ), sqlstate, (中文(简体) ), detail, (中文(简体) ), requestId,, , , , , , , , . |
HardchargerErrorCode (= (单位:千美元) ErrorCode(中文(简体) ) | 密码,例如. HardchargerErrorCode.sqlError 实值 "sql_error" |
parseUrl(url), (中文(简体) ), schemes, (中文(简体) ), schemesFor(url), (中文(简体) ), scheme, (中文(简体) ), defaultPort, (中文(简体) ), gizmodataCloudPort, (中文(简体) ), isGizmodataCloudHost(host) | 上面的 URL 翻译; "hardcharger", (中文(简体) ), 31337, (中文(简体) ), 443 和 GizmoData 云主机测试 |
version | 此软件包的版本 |
Connection, (中文(简体) ), PreparedStatement, (中文(简体) ), ResultStream, (中文(简体) ), Metadata, (中文(简体) ), Capability, (中文(简体) ), ChargewireError, (中文(简体) ), ErrorCode | 充电客户的, 以他们自己的名字 |
类型 : ConnectOptions, (中文(简体) ), CallOptions, (中文(简体) ), StatementOptions, (中文(简体) ), IngestOptions, (中文(简体) ), Parameters, (中文(简体) ), TlsOptions, (中文(简体) ), ColumnInfo, (中文(简体) ), ProblemDocument,, , , , , , , , . | 充电客户端的类型 |
这个 充电客户端的 API 表格 描述 每一个方法,和 如何表现 重试、 分拆结果、 取消和丢失会话.
QQ 错误
每个错误都是 HardchargerError 拥有稳定 code: 服务器的( x)sql_error, (中文(简体) ),
invalid_credentials, (中文(简体) ), statement_cancelled, (中文(简体) ), statement_timeout, (中文(简体) ), permission_denied,)或
客户之一的,从 client_ (单位:千美元)client_invalid_argument 在事情发生之前
发送, client_transport_error 没有HTTP的答案, client_http_error 错误答案,没有
问题文档, client_connection_closed,与 status, (中文(简体) ), sqlstate, (中文(简体) ), detail, (中文(简体) ),
requestId, (中文(简体) ), statementId, (中文(简体) ), reason 财务报告和审定财务报表 cancelReason 旁边 决定: code永远不要
留言。 运行时失败的语句是 execution_error (422); 一个取消或超时
在答复其提交之前 statement_cancelled 或者说 statement_timeout (409美元
statementId 财务报告和审定财务报表 cancelReason) (中文(简体) ).
HardchargerError.is(err, "sql_error") 立即检查阶级和密码 现场测试
维护客户端遇到的每个代码 : sql_error (400,带有SQLSTATE),, invalid_credentials
(401个), statement_cancelled, (中文(简体) ), statement_timeout, (中文(简体) ), unknown_certificate_identity (401个),
not_implemented, (中文(简体) ), execution_error (422个), client_transport_error, (中文(简体) ), client_invalid_argument, (中文(简体) ),
client_connection_closed,以及 session_ended 与 reason idle_in_transaction。 。 。 .
服务器的会话结束, 因为它的交易在服务器上闲置
idle_in_transaction_session_timeout (硬充电器2.7.0和后期) session_ended 与
reason: "idle_in_transaction":交易被卷回, 和发现它的声明
以该错误结尾失败, 并且从此不再运行, 无论交易开始于
setAutocommit(false), (中文(简体) ), transaction() 或者说 BEGIN 在 SQL 中。 连接继续进行:下一个
语句运行在新会话上,没有新的登录。 服务器丢失的会话
(单位:千美元)session_not_found:重启,闲置驱逐)也被替换了,找到它的请求也被替换了
在新会话上运行, 只有在旧会话中无法打开交易时:
自动承诺, 且无法启动交易的 SQL(BEGIN, (中文(简体) ), START TRANSACTION任何东西
命名自动承诺)运行在那里,没有第一个单词是 USE, (中文(简体) ), SET, (中文(简体) ), RESET 或者说
PRAGMA 做到了(新会话有连接的选项,而不是 SQL 设置的选项;它在
这些选项留下了旧的, 否则就失败了
与 session_not_found,然后在新的会话中发出下一个电话。 其它 session_ended 原因(killed, (中文(简体) ),
credentials_changed, (中文(简体) ), principal_dropped, (中文(简体) ), token_revoked,以及 token_expired 当标志
无法被更新) 无法被新会话治愈: 它们是错误, 而一个新的连接是
继续前进.
该类是充电客户端的,使用硬充电器名称(它) name 留下来
"ChargewireError":一个类,所以客户端任何地方的错误都是 instanceof 都一样.
建筑和测试
节点22.19或后. 为了发展和慈善协会, @gizmodata/chargewire 是从
gizmodata/充电线js 誓以犯罪
脚本/充电线-js.commit 包装到 .chargewire/时
package-lock.json 找到它了,所以测试是针对那个客户的. package.json这样
已公布的软件包,命名 npm 软件包及其范围(^2.4.0沥青球是站着的
仅供发展之用.
npm run chargewire # clone chargewire-js, build and pack the pinned commit
npm ci
npm run lint # eslint (typed rules), prettier, and the lock's shape (scripts/check-lock.mjs)
npm run typecheck # src, tests and configs
npm test # unit tests (no server)
npm run build # dist/: ESM, CJS and types
npm run check:package # the packed package: this layer only, a few KB, publint, are-the-types-wrong
HARDCHARGER_JS_CHARGEWIRE_REPO=/path/to/chargewire-js npm run chargewire 当地建筑
结账 TypeScript 保留在 6. 0 上: 键入刻录-slint 和声明构建需要
TypeScript编译器API,TypeScript 7不载运.
直播套房开始 hardcharger-server 在自由回路端口上(一个在
31337,以证明一个没有端口到达的 URL),有新的管理员密码
包含 : 财务报告和审定财务报表 @,一个空的家目录(包含 DuckDB 的秘密目录),并且只包含
PATH, (中文(简体) ), HOME, (中文(简体) ), TMPDIR 及其环境中的密码。 没有二进制,它们就会失败;
并且没有测试到服务器的运行失败。 直播套房也一样
检查协议重新命名为充电线之前释放的硬充电器(即
ghcr.io/gizmodata/hardcharger:2.2.0 图像, 已运行, 普通 HTTP) 何时
HARDCHARGER_JS_TEST_OLD_SERVER 说吧host:port,与
HARDCHARGER_JS_TEST_OLD_SERVER_PASSWORD),CI开始一个,没有它,那些测试就会失败.
export HARDCHARGER_JS_TEST_SERVER_BINARY=/path/to/hardcharger-server
npm run test:live # Node (vitest): sign-in, queries, parameters, split results, ingest,
# transactions, cancel, certificate sign-in, error codes
npm run build && npx playwright install chromium webkit && npm run test:browser
npm run build && npm run test:examples # this README's examples, on port 31337
阴性测试坚持错误代码, 在每个阳性双胞胎旁边。 线人负责一切对抗
硬充电机主分机的图像(ghcr.io/gizmodata/hardcharger:main),拉动与
工作流程 GITHUB_TOKEN; 当图像是私有时, 软件包必须授予此寄存器
读取访问(package settings,"Manage Action Access"),或活的工作失败. CI 克隆软件
(原始内容存档于2018-05-21). cherwire-js匿名通过https.
· 释出
发布后 语义版本 财务报告和审定财务报表 变动情况数字 :
更新 package.json'版本,然后在要求的检查合格后合并拉出请求.
获取 origin/main,验证其树与被测试的承诺相匹配,并标记准确的着陆承诺
vX.Y.Z。按下释放标记后不移动.
release.yml 运行标记上的全部 CI ,然后用
软件包 tarball 和 ChangeGELOG 部分, 然后在信任的情况下发布到 npm( 公开)
当寄存器变量时, 发布( OIDC, 无存储符) NPM_PUBLISH_ENABLED 实值 true。 。 。 .
Npm的工作首先检查 @gizmodata/chargewire 位于范围 npm package.json 名称;
在npmjs.com上, @gizmodata/hardcharger信任的出版商是这个仓库的 release.yml
(环境) npm) (中文(简体) ). npm publish 从笔记本电脑拒绝运行.
许可证
Apache 许可证 2.0。 。 。 .

由 GizmoDataTM 地图
硬充电TM和GizmoDataTM是GizmoData LLC的商标.
查询进度和报表元数据
onProgress 财务报告和审定财务报表 ResultStream.statement() 直接通过此软件包提供 :
const rows = conn.stream("SELECT * FROM large_table", undefined, {
onProgress: (statement) => console.log(statement.state, statement.progress?.fraction),
});
const metadata = await rows.statement();
for await (const batch of rows) {
// Consume rows as they arrive.
}
这些添加保留了现有的API和Chargewire协议版本. 进展是可选的; 没有估计的服务器报告状态时没有百分比。 在发言前可先作简要描述 补全,不重运行 SQL 或保留结果.