Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

feat(connection): support Kafka deep-link prefills

Leondung Chow6ac251673f95
diff --git a/apps/desktop/src/components/connection/ConnectionDialog.vue b/apps/desktop/src/components/connection/ConnectionDialog.vue
index 1bd0b163ef..d31538eebf 100644
--- a/apps/desktop/src/components/connection/ConnectionDialog.vue
+++ b/apps/desktop/src/components/connection/ConnectionDialog.vue
@@ -6437,6 +6437,7 @@ function prefillDraftKey(draft: ConnectionDeepLinkDraft) {
draft.oracleConnectionType,
draft.useMongoUrl,
draft.serviceConfig,
+ draft.mqConfig,
]);
}
@@ -6498,6 +6499,7 @@ function applyConnectionDraftToForm(draft: ConnectionDeepLinkDraft) {
} else if (draft.serviceConfig?.kind === "nacos") {
hydrateNacosFields(connectionDeepLinkServiceHydrationValue(draft.serviceConfig));
}
+ if (draft.mqConfig) hydrateMqFields(draft.mqConfig);
oracleTnsAdminPath.value = parseOracleTnsConnectionString(form.value.connection_string)?.tnsAdmin || "";
selectedType.value = draft.driverProfile;
if (form.value.db_type === "h2") {
diff --git a/apps/desktop/src/components/connection/__tests__/ConnectionDialog.deepLinkEdit.spec.ts b/apps/desktop/src/components/connection/__tests__/ConnectionDialog.deepLinkEdit.spec.ts
index 4a4d626f90..f9b2c8e4c9 100644
--- a/apps/desktop/src/components/connection/__tests__/ConnectionDialog.deepLinkEdit.spec.ts
+++ b/apps/desktop/src/components/connection/__tests__/ConnectionDialog.deepLinkEdit.spec.ts
@@ -296,6 +296,56 @@ describe.each([
});
describe("ConnectionDialog deep-link edit confirmation", () => {
+ it.each([false, true])("prefills Kafka brokers and only saves on confirmation (SASL: %s)", async (sasl) => {
+ store.connect.mockResolvedValue(undefined);
+ backend.listInstalledAgentsLocal.mockResolvedValue([{ db_type: "kafka", installed: true }]);
+ const brokers = "broker-a.example.com:9092,[2001:db8::1]:19092";
+ const params = new URLSearchParams({ type: "kafka", name: "Example Kafka", bootstrap_servers: brokers });
+ if (sasl) {
+ params.set("security_protocol", "SASL_SSL");
+ params.set("sasl_mechanism", "SCRAM-SHA-512");
+ params.set("user", "app");
+ params.set("password", " secret+& ");
+ }
+ await mountNewDialog(`dbx://connection/new?${params}`);
+ expect([...document.querySelectorAll("input")].some((input) => input.value === brokers)).toBe(true);
+ if (sasl) expect([...document.querySelectorAll("input")].some((input) => input.value === " secret+& ")).toBe(true);
+ expect(store.addConnection).not.toHaveBeenCalled();
+ expect(store.connect).not.toHaveBeenCalled();
+ expect(backend.testConnectionWithInfo).not.toHaveBeenCalled();
+ const save = [...document.querySelectorAll("button")].find((button) => button.textContent?.trim() === i18n.global.t("connection.saveAndConnect"));
+ expect(save).toBeTruthy();
+ save!.click();
+ await settle();
+ expect(store.addConnection).toHaveBeenCalledWith(
+ expect.objectContaining({
+ db_type: "mq",
+ driver_profile: "kafka",
+ host: "broker-a.example.com",
+ port: 9092,
+ ssl: sasl,
+ username: "",
+ password: "",
+ external_config: expect.objectContaining({
+ systemKind: "kafka",
+ adminUrl: "",
+ auth: sasl ? { kind: "basic", username: "app", password: " secret+& " } : { kind: "none" },
+ extra: expect.objectContaining({ bootstrapServers: brokers, securityProtocol: sasl ? "SASL_SSL" : "PLAINTEXT", ...(sasl ? { saslMechanism: "SCRAM-SHA-512" } : {}) }),
+ }),
+ }),
+ null,
+ );
+ });
+
+ it("replaces a Kafka prefill when only the later broker changes", async () => {
+ const first = "dbx://connection/new?type=kafka&bootstrap_servers=a:9092,b:9092";
+ const props = await mountNewDialog(first);
+ props.prefillConfig = parseConnectionDeepLink("dbx://connection/new?type=kafka&bootstrap_servers=a:9092,c:9092");
+ await settle();
+ expect([...document.querySelectorAll("input")].some((input) => input.value === "a:9092,c:9092")).toBe(true);
+ expect(store.addConnection).not.toHaveBeenCalled();
+ });
+
it("saves a new OceanBase connection with its explicitly entered port after switching mode", async () => {
backend.listInstalledAgentsLocal.mockResolvedValue([{ db_type: "oceanbase-oracle", installed: true }]);
await mountNewDialog();
diff --git a/apps/desktop/src/lib/__tests__/connection/connectionDeepLink.kafka.spec.ts b/apps/desktop/src/lib/__tests__/connection/connectionDeepLink.kafka.spec.ts
new file mode 100644
index 0000000000..18446a1337
--- /dev/null
+++ b/apps/desktop/src/lib/__tests__/connection/connectionDeepLink.kafka.spec.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { parseConnectionDeepLink } from "@/lib/connection/connectionDeepLink";
+
+function parse(fields: Record<string, string>) {
+ return parseConnectionDeepLink(`dbx://connection/new?${new URLSearchParams({ v: "1", type: "kafka", ...fields })}`)!;
+}
+
+describe("Kafka connection deep links", () => {
+ it("uses the existing MQ Kafka profile and defaults", () => {
+ expect(parse({ name: "Example Kafka" })).toEqual({
+ name: "Example Kafka",
+ dbType: "mq",
+ driverProfile: "kafka",
+ driverLabel: "Apache Kafka",
+ host: "127.0.0.1",
+ port: 9092,
+ ssl: false,
+ mqConfig: { systemKind: "kafka", adminUrl: "", auth: { kind: "none" }, extra: { bootstrapServers: "127.0.0.1:9092", securityProtocol: "PLAINTEXT" } },
+ });
+ });
+ it("accepts host/port and bracketed or bare IPv6 hosts", () => {
+ for (const host of ["broker.example.com", "::1", "[::1]"]) {
+ const draft = parse({ host, port: "19092" });
+ expect(draft.host).toBe(host.replace(/^\[|\]$/g, ""));
+ expect(draft.port).toBe(19092);
+ }
+ });
+ it("preserves all brokers and maps the first endpoint to host/port", () => {
+ const draft = parse({ bootstrap_servers: "broker-a.example.com:9092; [2001:db8::1]:19092", one_time: "true" });
+ expect(draft).toMatchObject({ host: "broker-a.example.com", port: 9092, oneTime: true, mqConfig: { extra: { bootstrapServers: "broker-a.example.com:9092,[2001:db8::1]:19092" } } });
+ });
+ it("preserves SASL credential whitespace and maps SCRAM plus TLS", () => {
+ const draft = parse({ bootstrap_servers: "broker.example.com:9093", security_protocol: "sasl_ssl", sasl_mechanism: "scram-sha-512", user: " user ", password: " +& secret ", ssl: "true" });
+ expect(draft.ssl).toBe(true);
+ expect(draft.mqConfig).toMatchObject({ auth: { kind: "basic", username: " user ", password: " +& secret " }, extra: { securityProtocol: "SASL_SSL", saslMechanism: "SCRAM-SHA-512" } });
+ });
+ it("infers SASL from username and permits a password to be entered in DBX", () => {
+ expect(parse({ user: "app" }).mqConfig).toMatchObject({ auth: { kind: "basic", username: "app", password: "" }, extra: { securityProtocol: "SASL_PLAINTEXT", saslMechanism: "PLAIN" } });
+ });
+ it("uses SSL from the bootstrap prefix without downgrading it", () => {
+ expect(parse({ bootstrap_servers: "SSL://broker.example.com:9093" })).toMatchObject({ ssl: true, mqConfig: { extra: { securityProtocol: "SSL", bootstrapServers: "broker.example.com:9093" } } });
+ });
+ it.each([
+ { bootstrap_servers: "" },
+ { bootstrap_servers: "broker.example.com" },
+ { bootstrap_servers: "broker.example.com:65536" },
+ { host: "broker.example.com/path" },
+ { port: "0" },
+ { ssl: "invalid" },
+ { password: "secret" },
+ { bootstrap_servers: "a:9092", host: "b" },
+ { security_protocol: "INVALID" },
+ { sasl_mechanism: "GSSAPI" },
+ { security_protocol: "PLAINTEXT", user: "app" },
+ { security_protocol: "SSL", ssl: "false" },
+ { bootstrap_servers: "SSL://a:9093", security_protocol: "PLAINTEXT" },
+ { bootstrap_servers: "SSL://a:9093,SASL_SSL://b:9093" },
+ { url: "kafka://broker.example.com:9092" },
+ { zookeeper_servers: "zk:2181" },
+ { name: "x".repeat(4097) },
+ ])("rejects invalid or unsupported input: %j", (fields) => {
+ expect(() => parse(fields)).toThrow();
+ });
+ it("rejects duplicate Kafka parameters and unsupported versions", () => {
+ expect(() => parseConnectionDeepLink("dbx://connection/new?type=kafka&bootstrap_servers=a:9092&bootstrap_servers=b:9092")).toThrow(/Duplicate/);
+ expect(() => parse({ v: "2" })).toThrow(/version/);
+ });
+});
diff --git a/apps/desktop/src/lib/connection/connectionDeepLink.ts b/apps/desktop/src/lib/connection/connectionDeepLink.ts
index 80a996bc09..338565b1dd 100644
--- a/apps/desktop/src/lib/connection/connectionDeepLink.ts
+++ b/apps/desktop/src/lib/connection/connectionDeepLink.ts
@@ -1,6 +1,9 @@
import type { DatabaseType } from "@/types/database";
+import type { MqAdminConfig } from "@/types/mq";
import type { DeepLinkConnectionConfirmMode } from "@/stores/settingsStore";
import { connectionProfileForScheme, parseConnectionUrl } from "@/lib/connection/connectionUrl";
+import { buildMqKafkaConnectionExtra, mqKafkaConnectionTarget } from "@/lib/connection/mqKafkaConnection";
+import { parseKafkaBootstrapServers } from "@/lib/connection/kafkaBootstrapServers";
export type ConnectionDeepLinkServiceConfig =
| { kind: "consul"; serverAddr: string }
@@ -31,6 +34,7 @@ export interface ConnectionDeepLinkDraft {
useMongoUrl?: boolean;
oneTime?: boolean;
serviceConfig?: ConnectionDeepLinkServiceConfig;
+ mqConfig?: MqAdminConfig;
}
export interface ConnectionDeepLinkUpdatePatch {
@@ -271,6 +275,51 @@ function draftFromConnectionUrl(value: string, preferredProfile?: string): Conne
};
}
+/** Kafka needs the full bootstrap list and MQ authentication, not SQL URL fields. */
+function kafkaConnectionDraft(params: URLSearchParams): ConnectionDeepLinkDraft {
+ const allowed = new Set(["v", "type", "name", "host", "port", "user", "password", "ssl", "one_time", "bootstrap_servers", "security_protocol", "sasl_mechanism"]);
+ for (const key of params.keys()) {
+ if (!allowed.has(key)) throw new Error(`Unsupported Kafka connection parameter: ${key}`);
+ if (params.getAll(key).length !== 1) throw new Error(`Duplicate Kafka connection parameter: ${key}`);
+ if (params.get(key)!.length > CONNECTION_UPDATE_MAX_PARAM_LENGTH) throw new Error(`Kafka connection ${key} is too long`);
+ }
+ if (params.toString().length > CONNECTION_UPDATE_MAX_URL_LENGTH) throw new Error("Kafka connection parameters are too long");
+ if (params.has("bootstrap_servers") && (params.has("host") || params.has("port"))) {
+ throw new Error("Use bootstrap_servers or host/port for Kafka, not both");
+ }
+ const host = optionalParam(params, "host") || "127.0.0.1";
+ const port = optionalPortParam(params, "port") ?? 9092;
+ const authority = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+ const parsed = parseKafkaBootstrapServers(params.has("bootstrap_servers") ? params.get("bootstrap_servers")! : `${authority}:${port}`);
+ // Credentials are opaque; unlike labels and addresses, spaces must survive.
+ const username = params.get("user") ?? "";
+ const password = params.get("password") ?? "";
+ if (password && !username.trim()) throw new Error("Kafka username is required when a password is provided");
+ const mechanism = optionalParam(params, "sasl_mechanism")?.toUpperCase();
+ if (mechanism && !["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"].includes(mechanism)) throw new Error("Unsupported Kafka SASL mechanism");
+ const ssl = optionalBooleanParam(params, "ssl");
+ const configuredProtocol = optionalParam(params, "security_protocol")?.toUpperCase();
+ const protocol = configuredProtocol || parsed.inferredSecurityProtocol || (username || password || mechanism ? (ssl ? "SASL_SSL" : "SASL_PLAINTEXT") : ssl ? "SSL" : "PLAINTEXT");
+ if (!["PLAINTEXT", "SSL", "SASL_PLAINTEXT", "SASL_SSL"].includes(protocol)) throw new Error("Unsupported Kafka security protocol");
+ if (configuredProtocol && parsed.inferredSecurityProtocol && configuredProtocol !== parsed.inferredSecurityProtocol) throw new Error("Conflicting Kafka security protocols");
+ const tls = protocol === "SSL" || protocol === "SASL_SSL";
+ if (ssl !== undefined && ssl !== tls) throw new Error("Kafka ssl conflicts with security protocol");
+ const sasl = protocol.startsWith("SASL_");
+ if (!sasl && (username || password || mechanism)) throw new Error("Kafka credentials and SASL mechanism require a SASL security protocol");
+ const input = { connectionSource: "bootstrap" as const, bootstrapServers: parsed.bootstrapServers, zookeeperServers: "", securityProtocol: protocol };
+ const extra = buildMqKafkaConnectionExtra(input);
+ if (sasl) extra.saslMechanism = mechanism || "PLAIN";
+ return {
+ name: optionalParam(params, "name"),
+ dbType: "mq",
+ driverProfile: "kafka",
+ driverLabel: "Apache Kafka",
+ ...mqKafkaConnectionTarget(input),
+ ...(params.has("one_time") ? { oneTime: optionalBooleanParam(params, "one_time") } : {}),
+ mqConfig: { systemKind: "kafka", adminUrl: "", auth: sasl ? { kind: "basic", username, password } : { kind: "none" }, extra },
+ };
+}
+
export function parseConnectionDeepLink(value: string): ConnectionDeepLinkDraft | null {
let url: URL;
try {
@@ -286,6 +335,7 @@ export function parseConnectionDeepLink(value: string): ConnectionDeepLinkDraft
if (params.has("id")) throw new Error("Connection update link cannot create a new connection");
validateProtocolVersion(params);
const preferredProfile = optionalParam(params, "type")?.toLowerCase();
+ if (preferredProfile === "kafka") return kafkaConnectionDraft(params);
const rawConnectionUrl = optionalParam(params, "url");
let serviceType = normalizeServiceType(preferredProfile);
if (!serviceType && rawConnectionUrl) {
diff --git a/docs/content/docs/cli.cn.mdx b/docs/content/docs/cli.cn.mdx
index 26766314d2..bf33555231 100644
--- a/docs/content/docs/cli.cn.mdx
+++ b/docs/content/docs/cli.cn.mdx
@@ -250,6 +250,22 @@ open 'dbx://connection/new?type=r-nacos&url=http%3A%2F%2F127.0.0.1%3A8848%2Fnaco
`nacos` 是 `nacos-v2` 的别名,`rnacos` 是 `r-nacos` 的别名。URL 模式会保留服务端点路径,顶层 `host`、`port`、`user`、`password`、`ssl` 会覆盖 `url` 中的对应值。Consul 的 `password` 表示 ACL token;Nacos 传入 `password` 时必须同时传入 `user`。省略 `v` 或使用 `v=1` 表示当前深链协议,其他版本会被拒绝。
+Kafka 连接预填示例:
+
+```bash
+open 'dbx://connection/new?v=1&type=kafka&name=ExampleKafka&host=broker.example.com&port=9092'
+open 'dbx://connection/new?v=1&type=kafka&bootstrap_servers=broker-a.example.com%3A9092%2Cbroker-b.example.com%3A9092'
+open 'dbx://connection/new?v=1&type=kafka&bootstrap_servers=broker.example.com%3A9093&security_protocol=SASL_SSL&sasl_mechanism=SCRAM-SHA-512&user=app'
+```
+
+Kafka 会打开已有的 **Apache Kafka** 连接表单。使用 `host` / `port`(默认 `127.0.0.1` / `9092`),或用 `bootstrap_servers` 提供完整 Broker 列表,两种形式不能混用。列表中每个地址都必须有端口,IPv6 需加方括号,例如 `[2001:db8::1]:9092`。请使用 `URLSearchParams` 等工具编码参数值,尤其是逗号、`+`、`&` 和凭据。
+
+- `security_protocol`:`PLAINTEXT`、`SSL`、`SASL_PLAINTEXT` 或 `SASL_SSL`。省略时先使用 Broker 列表中的协议前缀,否则根据 `user` / `sasl_mechanism` 推断 SASL,根据 `ssl` 推断 TLS。
+- `sasl_mechanism`:`PLAIN`(SASL 默认值)、`SCRAM-SHA-256` 或 `SCRAM-SHA-512`。`user` / `password` 回填 Kafka 认证字段,密码可不传,稍后在 DBX 内填写;凭据中的空格会保留。请避免在共享链接中放入密码。
+- TLS 与协议冲突、重复参数或不支持的 Kafka 字段会被拒绝。此预填入口不支持 Kafka `url`、ZooKeeper、Kerberos 或任意 Agent 属性。
+
+默认确认设置下,普通链接只打开表单供用户检查;已有的自动确认设置及 `one_time` 行为保持生效,此功能不会发送 Kafka 消息。Kafka 专用参数仅用于新建连接,下方按 ID 更新的入口仍采用原有参数白名单。
+
### 按 ID 更新已保存连接
在同一个 `dbx://connection/new` 路由上增加 `id`,即可打开指定的已保存连接进行编辑。例如,堡垒机可以为已有连接传入新的登录凭据:
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx
index 63a0f1408b..df98099514 100644
--- a/docs/content/docs/cli.mdx
+++ b/docs/content/docs/cli.mdx
@@ -250,6 +250,22 @@ open 'dbx://connection/new?type=r-nacos&url=http%3A%2F%2F127.0.0.1%3A8848%2Fnaco
`nacos` is an alias for `nacos-v2`, and `rnacos` is an alias for `r-nacos`. In URL mode, service endpoint paths are preserved; top-level `host`, `port`, `user`, `password`, and `ssl` fields override values from `url`. For Consul, `password` is the ACL token. Nacos requires `user` when `password` is present. Omitting `v` or using `v=1` selects the current deep-link protocol; other versions are rejected.
+Kafka connection prefills:
+
+```bash
+open 'dbx://connection/new?v=1&type=kafka&name=ExampleKafka&host=broker.example.com&port=9092'
+open 'dbx://connection/new?v=1&type=kafka&bootstrap_servers=broker-a.example.com%3A9092%2Cbroker-b.example.com%3A9092'
+open 'dbx://connection/new?v=1&type=kafka&bootstrap_servers=broker.example.com%3A9093&security_protocol=SASL_SSL&sasl_mechanism=SCRAM-SHA-512&user=app'
+```
+
+Kafka uses the existing **Apache Kafka** connection form. Use either `host` / `port` (defaults: `127.0.0.1` / `9092`) or `bootstrap_servers` with the complete broker list. Each bootstrap entry requires a port; IPv6 entries use brackets, such as `[2001:db8::1]:9092`. URL-encode query values with `URLSearchParams` or equivalent, especially commas, `+`, `&`, and credentials.
+
+- `security_protocol`: `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, or `SASL_SSL`. Without it, DBX uses any protocol prefix in the broker list, otherwise infers SASL from `user` / `sasl_mechanism` and TLS from `ssl`.
+- `sasl_mechanism`: `PLAIN` (default for SASL), `SCRAM-SHA-256`, or `SCRAM-SHA-512`. `user` / `password` populate Kafka authentication; an omitted password can be entered in DBX. Credential whitespace is preserved. Avoid putting passwords in shared URLs.
+- Conflicting TLS/protocol settings, duplicate parameters and unsupported Kafka fields are rejected. Kafka `url`, ZooKeeper, Kerberos and arbitrary agent properties are not supported by this prefill route.
+
+Normal links open the form for review under the default confirmation setting. Existing automatic-confirmation settings and `one_time` behavior still apply. This addition does not send Kafka messages. Kafka-specific fields are for new connections; the saved-connection update route below retains its existing parameter whitelist.
+
### Update a saved connection by ID
Add `id` to the same `dbx://connection/new` route to open an existing saved connection for editing. For example, a bastion host can provide fresh credentials for a saved connection:
diff --git a/docs/public/images/kafka-connection-prefill.png b/docs/public/images/kafka-connection-prefill.png
new file mode 100644
index 0000000000..ad72862c3c
Binary files /dev/null and b/docs/public/images/kafka-connection-prefill.png differ