feat(jdbc): add managed Apache Phoenix profile

This commit is contained in:
Guoyu Su authored and GitHub committed 2026-08-06 23:16:12 +08:00
1 parent c835deb3f9
commit 69f4450aee
38 files changed
+1651 -77

No files matched your search

@@ -0,0 +1,163 @@
import { describe, expect, it, vi } from "vitest";
import {
createJdbcProductConnectionFieldsByMode,
createJdbcProductProfileRegistry,
ensureJdbcProductRuntimeDrivers,
isJdbcProductDefaultDriverClass,
jdbcProductManagedRuntimePaths,
rememberJdbcProductConnectionFields,
validateJdbcProductManagedDriver,
type JdbcProductProfileDefinition,
} from "@/lib/database/jdbcProductProfile";
import type { ManagedJdbcDriverDefinition } from "@/lib/database/managedJdbcDriver";
import type { ConnectionConfig, JdbcMavenBundleInfo } from "@/types/database";
const directCoordinate = "com.example:fixture-direct:1.0.0";
const proxyCoordinate = "com.example:fixture-proxy:1.0.0";
const profile: JdbcProductProfileDefinition = {
id: "fixture",
label: "Fixture JDBC",
icon: "fixture",
category: "analytics",
port: 0,
user: "",
match: { dbType: "jdbc", driverProfile: "fixture" },
managedDriverId: "fixture",
runtimeLabelKey: "connection.fixtureRuntime",
driverManagerHintPrefixKey: "connection.fixtureHintPrefix",
driverManagerHintSuffixKey: "connection.fixtureHintSuffix",
docsLabelKey: "connection.fixtureDocs",
docsUrl: "https://example.com/docs",
missingDriverError: "Fixture driver is not installed.",
missingPluginError: "JDBC plugin is not installed.",
modes: [
{
id: "direct",
labelKey: "connection.fixtureDirect",
hintKey: "connection.fixtureDirectHint",
defaultConnectionString: "jdbc:fixture:direct",
defaultDriverClass: "com.example.DirectDriver",
managedCoordinates: [directCoordinate],
},
{
id: "proxy",
labelKey: "connection.fixtureProxy",
hintKey: "connection.fixtureProxyHint",
defaultConnectionString: "jdbc:fixture:proxy",
defaultDriverClass: "com.example.ProxyDriver",
managedCoordinates: [proxyCoordinate],
},
],
detectMode: (config) => (config.connection_string?.includes(":proxy") ? "proxy" : "direct"),
isCompatibleRuntimePath: (path, mode) => path.endsWith(`fixture-${mode}.jar`),
};
function config(mode: "direct" | "proxy" = "direct"): ConnectionConfig {
return {
id: "fixture-1",
name: "Fixture",
db_type: "jdbc",
driver_profile: "fixture",
host: "",
port: 0,
username: "",
password: "",
connection_string: `jdbc:fixture:${mode}`,
jdbc_driver_class: mode === "direct" ? "com.example.DirectDriver" : "com.example.ProxyDriver",
jdbc_driver_paths: [],
};
}
function bundle(coordinate: string): JdbcMavenBundleInfo {
const [groupId, artifactId, version] = coordinate.split(":");
return {
id: coordinate.replaceAll(":", "_"),
coordinate,
scope: "runtime",
repositories: ["https://repo.example.com/"],
installed_at: "2026-08-06T00:00:00Z",
path: `/drivers/${artifactId}`,
artifacts: [
{
group_id: groupId,
artifact_id: artifactId,
version,
classifier: "",
extension: "jar",
file_name: `${artifactId}-${version}.jar`,
path: `/drivers/${artifactId}-${version}.jar`,
size: 1,
sha256: coordinate,
},
],
};
}
describe("jdbcProductProfile", () => {
it("rejects duplicate profile ids and matchers", () => {
expect(() => createJdbcProductProfileRegistry([{ ...profile, id: "" }])).toThrow(/id must not be empty/);
expect(() => createJdbcProductProfileRegistry([profile, { ...profile }])).toThrow(/Duplicate JDBC product profile id/);
expect(() => createJdbcProductProfileRegistry([profile, { ...profile, id: "fixture-copy" }])).toThrow(/Duplicate JDBC product profile matcher/);
});
it("requires every profile runtime coordinate to be owned by its managed driver", () => {
const driver: ManagedJdbcDriverDefinition = {
id: "fixture",
label: "Fixture JDBC",
version: "1.0.0",
jre: "21",
bundles: [
{ coordinate: directCoordinate, repositories: [] },
{ coordinate: proxyCoordinate, repositories: [] },
],
};
expect(() => validateJdbcProductManagedDriver(profile, driver)).not.toThrow();
expect(() => validateJdbcProductManagedDriver(profile, undefined)).toThrow(/unknown managed driver/);
expect(() => validateJdbcProductManagedDriver(profile, { ...driver, bundles: driver.bundles.slice(0, 1) })).toThrow(/requires coordinate not owned/);
});
it("provides reusable per-mode defaults and field memory", () => {
let fields = createJdbcProductConnectionFieldsByMode(profile);
fields = rememberJdbcProductConnectionFields(profile, fields, "direct", {
connectionString: "jdbc:fixture:custom",
driverClass: "com.example.CustomDriver",
});
expect(fields.direct).toEqual({ connectionString: "jdbc:fixture:custom", driverClass: "com.example.CustomDriver" });
expect(fields.proxy).toEqual({ connectionString: "jdbc:fixture:proxy", driverClass: "com.example.ProxyDriver" });
expect(isJdbcProductDefaultDriverClass(profile, "com.example.ProxyDriver")).toBe(true);
expect(isJdbcProductDefaultDriverClass(profile, "com.example.CustomDriver")).toBe(false);
});
it("selects the registered mode runtime while preserving unrelated paths", async () => {
const direct = bundle(directCoordinate);
const proxy = bundle(proxyCoordinate);
const connection = config("proxy");
connection.jdbc_driver_paths = [direct.artifacts[0].path, "/etc/fixture"];
const api = {
jdbcPluginStatus: vi.fn(async () => ({ installed: true, compatible: true })),
listJdbcMavenBundles: vi.fn(async () => [direct, proxy]),
};
const result = await ensureJdbcProductRuntimeDrivers(profile, connection, api);
expect(jdbcProductManagedRuntimePaths(profile, [direct, proxy], "proxy")).toEqual([proxy.artifacts[0].path]);
expect(result?.paths).toEqual(["/etc/fixture", proxy.artifacts[0].path]);
expect(result?.runtimeSelectionId).toBe("fixture:proxy");
});
it("preserves an explicitly selected compatible custom runtime", async () => {
const connection = config();
connection.jdbc_driver_paths = ["/opt/fixture-direct.jar", "/etc/fixture"];
const result = await ensureJdbcProductRuntimeDrivers(profile, connection, {
jdbcPluginStatus: vi.fn(async () => ({ installed: true, compatible: true })),
listJdbcMavenBundles: vi.fn(async () => []),
});
expect(result?.paths).toEqual(connection.jdbc_driver_paths);
expect(result?.runtimeSelectionId).toBeUndefined();
});
});
@@ -0,0 +1,125 @@
import { describe, expect, it, vi } from "vitest";
import {
createManagedJdbcDriverRegistry,
installManagedJdbcDriver,
managedJdbcDriverBundles,
managedJdbcDriverPaths,
managedJdbcDriverRow,
missingManagedJdbcDriverBundles,
uninstallManagedJdbcDriver,
type ManagedJdbcDriverApi,
type ManagedJdbcDriverDefinition,
} from "@/lib/database/managedJdbcDriver";
import type { JdbcDriverInfo, JdbcMavenBundleInfo, JdbcPluginStatus } from "@/types/database";
const definition: ManagedJdbcDriverDefinition = {
id: "fixture",
label: "Fixture JDBC",
version: "1.0.0",
jre: "21",
bundles: [
{ coordinate: "com.example:fixture-core:1.0.0", repositories: ["https://repo.example.com/"] },
{ coordinate: "com.example:fixture-extra:1.0.0", repositories: ["https://repo.example.com/"] },
],
};
function bundle(coordinate: string, size = 10): JdbcMavenBundleInfo {
const [groupId, artifactId, version] = coordinate.split(":");
return {
id: coordinate.replaceAll(":", "_"),
coordinate,
scope: "runtime",
repositories: ["https://repo.example.com/"],
installed_at: "2026-08-06T00:00:00Z",
path: `/drivers/${artifactId}`,
artifacts: [
{
group_id: groupId,
artifact_id: artifactId,
version,
classifier: "",
extension: "jar",
file_name: `${artifactId}-${version}.jar`,
path: `/drivers/${artifactId}-${version}.jar`,
size,
sha256: coordinate,
},
],
};
}
function pluginStatus(installed = true): JdbcPluginStatus {
return {
installed,
version: installed ? "1.0.0" : null,
protocol_version: installed ? 1 : null,
compatible: installed,
latest_version: null,
latest_protocol_version: null,
update_available: false,
path: "/plugins/jdbc",
};
}
function api(overrides: Partial<ManagedJdbcDriverApi> = {}): ManagedJdbcDriverApi {
return {
installJdbcPlugin: vi.fn(async () => pluginStatus()),
installJdbcDriverFromMaven: vi.fn(async () => [] as JdbcDriverInfo[]),
listJdbcMavenBundles: vi.fn(async () => []),
deleteJdbcMavenBundle: vi.fn(async () => [] as JdbcDriverInfo[]),
...overrides,
};
}
describe("managedJdbcDriver", () => {
it("rejects duplicate ids and ambiguous Maven bundle ownership", () => {
expect(() => createManagedJdbcDriverRegistry([{ ...definition, id: "" }])).toThrow(/id must not be empty/);
expect(() => createManagedJdbcDriverRegistry([definition, { ...definition }])).toThrow(/Duplicate managed JDBC driver id/);
expect(() => createManagedJdbcDriverRegistry([definition, { ...definition, id: "fixture-copy" }])).toThrow(/is owned by both/);
});
it("derives exact bundle state, paths, size, and plugin-aware installation", () => {
const core = bundle(definition.bundles[0].coordinate, 12);
const extra = bundle(definition.bundles[1].coordinate, 18);
const unrelated = bundle("com.example:unrelated:1.0.0", 999);
expect(managedJdbcDriverBundles(definition, [unrelated, extra, core])).toEqual([core, extra]);
expect(missingManagedJdbcDriverBundles(definition, [core])).toEqual([definition.bundles[1]]);
expect(managedJdbcDriverPaths(definition, [core, extra])).toEqual([core.artifacts[0].path, extra.artifacts[0].path]);
expect(managedJdbcDriverPaths(definition, [core])).toEqual([]);
expect(managedJdbcDriverRow(definition, [core, extra], pluginStatus())).toMatchObject({ installed: true, size: 30, installed_version: "1.0.0" });
expect(managedJdbcDriverRow(definition, [core, extra])).toMatchObject({ installed: false, size: 30, installed_version: null });
expect(managedJdbcDriverRow(definition, [core, extra], pluginStatus(false))).toMatchObject({ installed: false, size: 30, installed_version: null });
});
it("ensures the plugin and installs only missing coordinates", async () => {
const core = bundle(definition.bundles[0].coordinate);
const extra = bundle(definition.bundles[1].coordinate);
const installJdbcPlugin = vi.fn(async () => pluginStatus());
const installJdbcDriverFromMaven = vi.fn(async () => [] as JdbcDriverInfo[]);
const listJdbcMavenBundles = vi.fn(async () => [core, extra]);
const runtimeApi = api({ installJdbcPlugin, installJdbcDriverFromMaven, listJdbcMavenBundles });
const result = await installManagedJdbcDriver(definition, [core], pluginStatus(false), runtimeApi);
expect(installJdbcPlugin).toHaveBeenCalledOnce();
expect(installJdbcDriverFromMaven).toHaveBeenCalledOnce();
expect(installJdbcDriverFromMaven).toHaveBeenCalledWith(definition.bundles[1].coordinate, ["https://repo.example.com/"]);
expect(result.bundles).toEqual([core, extra]);
expect(result.pluginStatus?.installed).toBe(true);
});
it("uninstalls only bundles owned by the selected definition", async () => {
const core = bundle(definition.bundles[0].coordinate);
const extra = bundle(definition.bundles[1].coordinate);
const unrelated = bundle("com.example:unrelated:1.0.0");
const deleteJdbcMavenBundle = vi.fn(async () => [] as JdbcDriverInfo[]);
const listJdbcMavenBundles = vi.fn(async () => [unrelated]);
const runtimeApi = api({ deleteJdbcMavenBundle, listJdbcMavenBundles });
const result = await uninstallManagedJdbcDriver(definition, [unrelated, core, extra], runtimeApi);
expect(deleteJdbcMavenBundle.mock.calls).toEqual([[core.id], [extra.id]]);
expect(result.bundles).toEqual([unrelated]);
});
});
@@ -0,0 +1,48 @@
import { describe, expect, it, vi } from "vitest";
import { installRegisteredManagedJdbcDriver, managedJdbcDriverDefinition, managedJdbcDriverRows } from "@/lib/database/managedJdbcDrivers";
import { PHOENIX_MANAGED_MAVEN_COORDINATES } from "@/lib/database/phoenixBuiltinDriver";
import { PRESTOSQL_JDBC_DRIVER_COORDINATE } from "@/lib/database/prestoSqlBuiltinDriver";
import type { JdbcDriverInfo, JdbcMavenBundleInfo, JdbcPluginStatus } from "@/types/database";
function pluginStatus(): JdbcPluginStatus {
return {
installed: true,
version: "1.0.0",
protocol_version: 1,
compatible: true,
latest_version: null,
latest_protocol_version: null,
update_available: false,
path: "/plugins/jdbc",
};
}
describe("managedJdbcDrivers", () => {
it("registers Phoenix and PrestoSQL through the same row model", () => {
expect(managedJdbcDriverDefinition("phoenix")?.bundles.map(({ coordinate }) => coordinate)).toEqual(PHOENIX_MANAGED_MAVEN_COORDINATES);
expect(managedJdbcDriverDefinition("prestosql")?.bundles.map(({ coordinate }) => coordinate)).toEqual([PRESTOSQL_JDBC_DRIVER_COORDINATE]);
expect(managedJdbcDriverRows([], pluginStatus()).map(({ db_type }) => db_type)).toEqual(["prestosql", "phoenix"]);
});
it("installs PrestoSQL through the generic Maven resolver", async () => {
const installed: JdbcMavenBundleInfo = {
id: "io.prestosql_presto-jdbc_350",
coordinate: PRESTOSQL_JDBC_DRIVER_COORDINATE,
scope: "runtime",
repositories: ["https://repo.maven.apache.org/maven2/"],
installed_at: "2026-08-06T00:00:00Z",
path: "/drivers/presto",
artifacts: [],
};
const installJdbcDriverFromMaven = vi.fn(async () => [] as JdbcDriverInfo[]);
const result = await installRegisteredManagedJdbcDriver("prestosql", [], pluginStatus(), {
installJdbcPlugin: vi.fn(async () => pluginStatus()),
installJdbcDriverFromMaven,
listJdbcMavenBundles: vi.fn(async () => [installed]),
deleteJdbcMavenBundle: vi.fn(async () => [] as JdbcDriverInfo[]),
});
expect(installJdbcDriverFromMaven).toHaveBeenCalledWith(PRESTOSQL_JDBC_DRIVER_COORDINATE, ["https://repo.maven.apache.org/maven2/"]);
expect(result?.bundles).toEqual([installed]);
});
});
@@ -0,0 +1,73 @@
import { describe, expect, it } from "vitest";
import { PHOENIX_JDBC_DRIVER_VERSION, PHOENIX_MANAGED_JDBC_DRIVER, PHOENIX_MANAGED_MAVEN_COORDINATES } from "@/lib/database/phoenixBuiltinDriver";
import { PHOENIX_MAVEN_REPOSITORY } from "@/lib/database/phoenixConnection";
import { managedJdbcDriverBundles, managedJdbcDriverRow, missingManagedJdbcDriverBundles } from "@/lib/database/managedJdbcDriver";
import type { JdbcMavenBundleInfo } from "@/types/database";
function bundle(coordinate: string, size = 100): JdbcMavenBundleInfo {
const [groupId, artifactId, version] = coordinate.split(":");
return {
id: `bundle:${coordinate}`,
coordinate,
scope: "runtime",
repositories: [PHOENIX_MAVEN_REPOSITORY],
installed_at: "2026-08-05T00:00:00Z",
path: "drivers/jdbc",
artifacts: [
{
group_id: groupId,
artifact_id: artifactId,
version,
classifier: "",
extension: "jar",
file_name: `${artifactId}-${version}.jar`,
path: `drivers/jdbc/${artifactId}-${version}.jar`,
size,
sha256: coordinate,
},
],
};
}
describe("phoenixBuiltinDriver", () => {
it("shows one uninstalled Apache Phoenix JDBC row when no managed bundle exists", () => {
const row = managedJdbcDriverRow(PHOENIX_MANAGED_JDBC_DRIVER, []);
expect(row.db_type).toBe("phoenix");
expect(row.label).toBe("Apache Phoenix JDBC");
expect(row.version).toBe(PHOENIX_JDBC_DRIVER_VERSION);
expect(row.installed).toBe(false);
expect(row.installed_version).toBeNull();
expect(row.jre).toBe("21");
expect(missingManagedJdbcDriverBundles(PHOENIX_MANAGED_JDBC_DRIVER, []).map(({ coordinate }) => coordinate)).toEqual(PHOENIX_MANAGED_MAVEN_COORDINATES);
});
it("stays uninstalled for a partial runtime and reports only missing coordinates", () => {
const direct = bundle(PHOENIX_MANAGED_MAVEN_COORDINATES[0], 120);
const row = managedJdbcDriverRow(PHOENIX_MANAGED_JDBC_DRIVER, [direct]);
expect(row.installed).toBe(false);
expect(row.size).toBe(120);
expect(managedJdbcDriverBundles(PHOENIX_MANAGED_JDBC_DRIVER, [direct])).toEqual([direct]);
expect(missingManagedJdbcDriverBundles(PHOENIX_MANAGED_JDBC_DRIVER, [direct]).map(({ coordinate }) => coordinate)).toEqual(PHOENIX_MANAGED_MAVEN_COORDINATES.slice(1));
});
it("is installed only when Direct, logging, and PQS bundles are all present", () => {
const unrelated = bundle("com.mysql:mysql-connector-j:9.2.0", 999);
const managed = PHOENIX_MANAGED_MAVEN_COORDINATES.map((coordinate, index) => bundle(coordinate, index + 1));
const row = managedJdbcDriverRow(PHOENIX_MANAGED_JDBC_DRIVER, [unrelated, ...managed], { installed: true, compatible: true });
expect(row.installed).toBe(true);
expect(row.installed_version).toBe(PHOENIX_JDBC_DRIVER_VERSION);
expect(row.size).toBe(6);
expect(managedJdbcDriverBundles(PHOENIX_MANAGED_JDBC_DRIVER, [unrelated, ...managed])).toEqual(managed);
expect(missingManagedJdbcDriverBundles(PHOENIX_MANAGED_JDBC_DRIVER, [unrelated, ...managed])).toEqual([]);
});
it("stays uninstalled when all bundles exist but the shared JDBC plugin is unavailable", () => {
const managed = PHOENIX_MANAGED_MAVEN_COORDINATES.map((coordinate) => bundle(coordinate));
expect(managedJdbcDriverRow(PHOENIX_MANAGED_JDBC_DRIVER, managed, { installed: false, compatible: true }).installed).toBe(false);
expect(managedJdbcDriverRow(PHOENIX_MANAGED_JDBC_DRIVER, managed, { installed: true, compatible: false }).installed).toBe(false);
});
});
@@ -1,5 +1,6 @@
import { describe, expect, it } from "vitest";
import { PRESTOSQL_JDBC_DRIVER_COORDINATE, prestoSqlBuiltinDriverPaths, prestoSqlBuiltinDriverRow, prestoSqlMavenBundle } from "@/lib/database/prestoSqlBuiltinDriver";
import { PRESTOSQL_JDBC_DRIVER_COORDINATE, PRESTOSQL_MANAGED_JDBC_DRIVER, prestoSqlBuiltinDriverPaths } from "@/lib/database/prestoSqlBuiltinDriver";
import { managedJdbcDriverBundles, managedJdbcDriverRow } from "@/lib/database/managedJdbcDriver";
import type { JdbcMavenBundleInfo } from "@/types/database";
function bundle(coordinate: string, version = "350"): JdbcMavenBundleInfo {
@@ -28,7 +29,7 @@ function bundle(coordinate: string, version = "350"): JdbcMavenBundleInfo {
describe("prestoSqlBuiltinDriver", () => {
it("adds an uninstalled PrestoSQL row when the Maven bundle is absent", () => {
const row = prestoSqlBuiltinDriverRow([]);
const row = managedJdbcDriverRow(PRESTOSQL_MANAGED_JDBC_DRIVER, []);
expect(row.db_type).toBe("prestosql");
expect(row.label).toBe("PrestoSQL");
@@ -40,9 +41,9 @@ describe("prestoSqlBuiltinDriver", () => {
it("marks PrestoSQL installed when its Maven coordinate is present", () => {
const installed = bundle(PRESTOSQL_JDBC_DRIVER_COORDINATE);
const row = prestoSqlBuiltinDriverRow([bundle("com.mysql:mysql-connector-j:9.2.0"), installed]);
const row = managedJdbcDriverRow(PRESTOSQL_MANAGED_JDBC_DRIVER, [bundle("com.mysql:mysql-connector-j:9.2.0"), installed], { installed: true, compatible: true });
expect(prestoSqlMavenBundle([installed])?.id).toBe(installed.id);
expect(managedJdbcDriverBundles(PRESTOSQL_MANAGED_JDBC_DRIVER, [installed])[0]?.id).toBe(installed.id);
expect(prestoSqlBuiltinDriverPaths([installed])).toEqual(["drivers/jdbc/presto-jdbc-350.jar"]);
expect(row.installed).toBe(true);
expect(row.installed_version).toBe("350");