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。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
saveSchemaCache: vi.fn(),
loadSchemaCache: vi.fn(),
deleteSchemaCachePrefix: vi.fn(),
persisted: new Map<string, unknown>(),
}));
vi.mock("@/lib/backend/api", () => mocks);
import { cancelObjectMetadataLoadsForConnection, getObjectMetadataCacheDebugStateForTests, invalidateObjectMetadataCache, invalidateObjectMetadataFacet, loadObjectMetadataFacet } from "@/lib/metadata/objectMetadataCache";
import { isObjectCacheInvalidationError } from "@/lib/metadata/objectCacheInvalidationError";
import { clearMetadataRuntimeCache } from "@/lib/metadata/metadataRuntimeCache";
const request = { connectionId: "c1", database: "app", schema: "public", tableName: "users", catalog: "analytics" } as const;
describe("objectMetadataCache", () => {
it.each(["remote", "disk"])("settles local waiting when connection cancellation retires a never-returning %s read", async (phase) => {
if (phase === "disk") mocks.loadSchemaCache.mockReturnValueOnce(new Promise(() => undefined));
const loader = vi.fn(() => new Promise(() => undefined));
let settled = false;
const result = loadObjectMetadataFacet(request, "columns", loader).then(
() => {
settled = true;
},
() => {
settled = true;
},
);
await vi.waitFor(() => expect(phase === "remote" ? loader.mock.calls.length : getObjectMetadataCacheDebugStateForTests().activeReads).toBe(1));
cancelObjectMetadataLoadsForConnection(request.connectionId);
await vi.waitFor(() => expect(settled).toBe(true));
await result;
expect(getObjectMetadataCacheDebugStateForTests().activeReads).toBe(0);
});
beforeEach(() => {
clearMetadataRuntimeCache();
vi.clearAllMocks();
mocks.persisted.clear();
mocks.loadSchemaCache.mockImplementation(async (cacheKey: string) => mocks.persisted.get(cacheKey) ?? null);
mocks.saveSchemaCache.mockImplementation(async (cacheKey: string, payload: unknown) => {
mocks.persisted.set(cacheKey, payload);
});
mocks.deleteSchemaCachePrefix.mockImplementation(async (prefix: string) => {
for (const cacheKey of mocks.persisted.keys()) {
if (cacheKey === prefix || cacheKey.startsWith(prefix)) mocks.persisted.delete(cacheKey);
}
});
});
it("reports deletion failures only to strict callers sharing the same invalidation", async () => {
let reject!: (error: Error) => void;
mocks.deleteSchemaCachePrefix.mockReturnValueOnce(
new Promise<void>((_, fail) => {
reject = fail;
}),
);
const bestEffort = invalidateObjectMetadataCache(request);
const strict = invalidateObjectMetadataCache(request, { strict: true });
const failure = new Error("storage unavailable");
const rejected = expect(strict).rejects.toMatchObject({ name: "ObjectCacheInvalidationError", reason: failure });
await vi.waitFor(() => expect(mocks.deleteSchemaCachePrefix).toHaveBeenCalledTimes(1));
reject(failure);
await rejected;
await expect(bestEffort).resolves.toBeUndefined();
await expect(invalidateObjectMetadataCache(request, { strict: true })).resolves.toBeUndefined();
expect(mocks.deleteSchemaCachePrefix).toHaveBeenCalledTimes(2);
});
it("keeps forced facet reads best effort if deletion fails", async () => {
mocks.deleteSchemaCachePrefix.mockRejectedValueOnce(new Error("storage unavailable"));
await expect(loadObjectMetadataFacet(request, "columns", async () => ["fresh"], { force: true })).resolves.toEqual({ value: ["fresh"], cacheStatus: "remote" });
});
it("reads a facet from disk without invoking the loader", async () => {
mocks.loadSchemaCache.mockResolvedValue({ version: 1, cachedAt: new Date().toISOString(), value: [{ name: "id" }] });
const loader = vi.fn().mockResolvedValue([{ name: "remote" }]);
await expect(loadObjectMetadataFacet(request, "columns", loader)).resolves.toEqual({ value: [{ name: "id" }], cacheStatus: "disk" });
expect(loader).not.toHaveBeenCalled();
});
it("does not grant an exact baseline from legacy memory or any persisted facet", async () => {
mocks.loadSchemaCache.mockResolvedValue({ version: 1, cachedAt: new Date().toISOString(), value: ["legacy"] });
const loader = vi.fn().mockResolvedValue(["exact"]);
await loadObjectMetadataFacet(request, "indexes", loader);
await expect(loadObjectMetadataFacet({ ...request, exactIdentity: true }, "indexes", loader)).resolves.toEqual({ value: ["exact"], cacheStatus: "remote" });
expect(loader).toHaveBeenCalledOnce();
expect(mocks.loadSchemaCache).toHaveBeenCalledOnce();
expect(mocks.saveSchemaCache).not.toHaveBeenCalled();
cancelObjectMetadataLoadsForConnection("c1");
loader.mockRejectedValueOnce(new Error("exact capability unavailable"));
await expect(loadObjectMetadataFacet({ ...request, exactIdentity: true }, "indexes", loader)).rejects.toThrow("exact capability unavailable");
});
it("backfills memory after a disk hit", async () => {
mocks.loadSchemaCache.mockResolvedValue({ version: 1, cachedAt: new Date().toISOString(), value: [] });
const loader = vi.fn();
await expect(loadObjectMetadataFacet(request, "columns", loader)).resolves.toEqual({ value: [], cacheStatus: "disk" });
await expect(loadObjectMetadataFacet(request, "columns", loader)).resolves.toEqual({ value: [], cacheStatus: "memory" });
expect(mocks.loadSchemaCache).toHaveBeenCalledTimes(1);
expect(loader).not.toHaveBeenCalled();
});
it("caches null and empty-array facet values", async () => {
const nullLoader = vi.fn().mockResolvedValue(null);
const emptyLoader = vi.fn().mockResolvedValue([]);
await expect(loadObjectMetadataFacet(request, "comment", nullLoader)).resolves.toMatchObject({ value: null, cacheStatus: "remote" });
await expect(loadObjectMetadataFacet(request, "comment", nullLoader)).resolves.toMatchObject({ value: null, cacheStatus: "memory" });
await expect(loadObjectMetadataFacet(request, "indexes", emptyLoader)).resolves.toMatchObject({ value: [], cacheStatus: "remote" });
await expect(loadObjectMetadataFacet(request, "indexes", emptyLoader)).resolves.toMatchObject({ value: [], cacheStatus: "memory" });
expect(nullLoader).toHaveBeenCalledTimes(1);
expect(emptyLoader).toHaveBeenCalledTimes(1);
});
it("does not cache undefined failure sentinels", async () => {
const loader = vi.fn().mockResolvedValueOnce(undefined).mockResolvedValueOnce("fresh comment");
await expect(loadObjectMetadataFacet(request, "comment", loader)).resolves.toMatchObject({ value: undefined, cacheStatus: "remote" });
await expect(loadObjectMetadataFacet(request, "comment", loader)).resolves.toMatchObject({ value: "fresh comment", cacheStatus: "remote" });
expect(loader).toHaveBeenCalledTimes(2);
});
it("isolates facets by object type", async () => {
const tableLoader = vi.fn().mockResolvedValue(["table"]);
const viewLoader = vi.fn().mockResolvedValue(["view"]);
await loadObjectMetadataFacet({ ...request, objectType: "TABLE" }, "columns", tableLoader);
await loadObjectMetadataFacet({ ...request, objectType: "VIEW" }, "columns", viewLoader);
expect(tableLoader).toHaveBeenCalledTimes(1);
expect(viewLoader).toHaveBeenCalledTimes(1);
});
it("separates exact trigger snapshots without changing other facet keys and invalidates both modes together", async () => {
const exactRequest = { ...request, oracleTriggerContract: 1 as const };
const oldLoader = vi.fn().mockResolvedValue(["legacy-body"]);
const exactLoader = vi.fn().mockResolvedValue(["exact-metadata"]);
expect((await loadObjectMetadataFacet(request, "triggers", oldLoader)).value).toEqual(["legacy-body"]);
expect((await loadObjectMetadataFacet(exactRequest, "triggers", exactLoader)).value).toEqual(["exact-metadata"]);
expect(exactLoader).toHaveBeenCalledTimes(1);
const columns = vi.fn().mockResolvedValue(["column"]);
await loadObjectMetadataFacet(request, "columns", columns);
await loadObjectMetadataFacet(exactRequest, "columns", columns);
expect(columns).toHaveBeenCalledTimes(1);
await invalidateObjectMetadataCache(request);
await loadObjectMetadataFacet(exactRequest, "triggers", exactLoader);
await loadObjectMetadataFacet(request, "triggers", oldLoader);
expect(exactLoader).toHaveBeenCalledTimes(2);
expect(oldLoader).toHaveBeenCalledTimes(2);
});
it.each([false, true])("retires all trigger identity and contract variants from an exact=%s facet request", async (exactIdentity) => {
const variants = [request, { ...request, oracleTriggerContract: 1 as const }, { ...request, exactIdentity: true }, { ...request, exactIdentity: true, oracleTriggerContract: 1 as const }];
for (const variant of variants) await loadObjectMetadataFacet(variant, "triggers", async () => ["old"]);
await loadObjectMetadataFacet(request, "columns", async () => ["column"]);
await loadObjectMetadataFacet({ ...request, catalog: "other" }, "triggers", async () => ["other"]);
await invalidateObjectMetadataFacet({ ...request, exactIdentity }, "triggers", { strict: true });
for (const variant of variants) expect((await loadObjectMetadataFacet(variant, "triggers", async () => ["new"])).value).toEqual(["new"]);
expect((await loadObjectMetadataFacet(request, "columns", async () => ["wrong"])).value).toEqual(["column"]);
expect((await loadObjectMetadataFacet({ ...request, catalog: "other" }, "triggers", async () => ["wrong"])).value).toEqual(["other"]);
});
it("retires exact in-flight trigger loads even when persisted deletion fails", async () => {
const exact = { ...request, exactIdentity: true, oracleTriggerContract: 1 as const };
let resolve!: (value: string[]) => void;
const loader = vi.fn(
() =>
new Promise<string[]>((done) => {
resolve = done;
}),
);
const pending = loadObjectMetadataFacet(exact, "triggers", loader);
const retired = expect(pending).rejects.toThrow();
await vi.waitFor(() => expect(loader).toHaveBeenCalledOnce());
mocks.deleteSchemaCachePrefix.mockRejectedValueOnce(new Error("storage unavailable"));
await expect(invalidateObjectMetadataFacet(request, "triggers", { strict: true })).rejects.toMatchObject({ name: "ObjectCacheInvalidationError" });
await retired;
resolve(["late"]);
await Promise.resolve();
expect((await loadObjectMetadataFacet(exact, "triggers", async () => ["fresh"])).value).toEqual(["fresh"]);
});
it("persists a remote facet and force bypasses disk", async () => {
mocks.loadSchemaCache.mockResolvedValue({ version: 1, cachedAt: new Date().toISOString(), value: ["old"] });
const loader = vi.fn().mockResolvedValue(["new"]);
await expect(loadObjectMetadataFacet(request, "indexes", loader, { force: true })).resolves.toEqual({ value: ["new"], cacheStatus: "remote" });
expect(loader).toHaveBeenCalledTimes(1);
expect(mocks.loadSchemaCache).not.toHaveBeenCalled();
expect(mocks.saveSchemaCache).toHaveBeenCalledWith(expect.stringContaining("object-meta:v1:c1:app:public:users:analytics:TABLE:indexes:"), expect.objectContaining({ value: ["new"] }));
});
it("does not wait for a slow SQLite write before returning a remote facet", async () => {
let releaseWrite: () => void = () => {};
mocks.saveSchemaCache.mockReturnValue(
new Promise<void>((resolve) => {
releaseWrite = resolve;
}),
);
const loader = vi.fn().mockResolvedValue(["id"]);
await expect(loadObjectMetadataFacet(request, "columns", loader)).resolves.toMatchObject({ value: ["id"], cacheStatus: "remote" });
expect(mocks.saveSchemaCache).toHaveBeenCalledTimes(1);
releaseWrite();
});
it("deduplicates concurrent remote facet loads", async () => {
let release: (value: string[]) => void = () => {};
const loader = vi.fn().mockReturnValue(
new Promise<string[]>((resolve) => {
release = resolve;
}),
);
const first = loadObjectMetadataFacet(request, "columns", loader);
const second = loadObjectMetadataFacet(request, "columns", loader);
await vi.waitFor(() => expect(loader).toHaveBeenCalledTimes(1));
release(["id"]);
await expect(Promise.all([first, second])).resolves.toEqual([
{ value: ["id"], cacheStatus: "remote" },
{ value: ["id"], cacheStatus: "remote" },
]);
});
it("force refresh bypasses memory and replaces it", async () => {
const loader = vi.fn().mockResolvedValueOnce(["old"]).mockResolvedValueOnce(["new"]);
await expect(loadObjectMetadataFacet(request, "indexes", loader)).resolves.toMatchObject({ value: ["old"], cacheStatus: "remote" });
await expect(loadObjectMetadataFacet(request, "indexes", loader, { force: true })).resolves.toMatchObject({ value: ["new"], cacheStatus: "remote" });
await expect(loadObjectMetadataFacet(request, "indexes", loader)).resolves.toMatchObject({ value: ["new"], cacheStatus: "memory" });
expect(loader).toHaveBeenCalledTimes(2);
});
it("ignores an expired persisted facet", async () => {
mocks.loadSchemaCache.mockResolvedValue({ version: 1, cachedAt: new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString(), value: ["stale"] });
const loader = vi.fn().mockResolvedValue(["fresh"]);
await expect(loadObjectMetadataFacet(request, "indexes", loader)).resolves.toMatchObject({ value: ["fresh"], cacheStatus: "remote" });
expect(loader).toHaveBeenCalledTimes(1);
});
it("invalidates only the requested object's facets", async () => {
await invalidateObjectMetadataCache(request);
expect(mocks.deleteSchemaCachePrefix).toHaveBeenCalledWith("object-meta:v1:c1:app:public:users:");
});
it("reloads a persisted facet after table-level invalidation", async () => {
const initialLoader = vi.fn().mockResolvedValue(["old"]);
const refreshedLoader = vi.fn().mockResolvedValue(["new"]);
await expect(loadObjectMetadataFacet(request, "indexes", initialLoader)).resolves.toEqual({ value: ["old"], cacheStatus: "remote" });
await invalidateObjectMetadataCache({ connectionId: request.connectionId, database: request.database, schema: request.schema, tableName: request.tableName });
await expect(loadObjectMetadataFacet(request, "indexes", refreshedLoader)).resolves.toEqual({ value: ["new"], cacheStatus: "remote" });
expect(refreshedLoader).toHaveBeenCalledTimes(1);
});
it("does not resurrect a stale disk facet when invalidated during the read", async () => {
let releaseDiskRead: (value: unknown) => void = () => {};
mocks.loadSchemaCache.mockReturnValueOnce(
new Promise((resolve) => {
releaseDiskRead = resolve;
}),
);
const loader = vi.fn().mockResolvedValue(["fresh"]);
const load = loadObjectMetadataFacet(request, "columns", loader);
await vi.waitFor(() => expect(mocks.loadSchemaCache).toHaveBeenCalledTimes(1));
const invalidation = invalidateObjectMetadataCache(request);
releaseDiskRead({ version: 1, cachedAt: new Date().toISOString(), value: ["stale"] });
await expect(load).resolves.toEqual({ value: ["fresh"], cacheStatus: "remote" });
await invalidation;
expect(loader).toHaveBeenCalledTimes(1);
expect(mocks.saveSchemaCache).toHaveBeenCalledWith(expect.stringContaining("object-meta:v1:c1:app:public:users:"), expect.objectContaining({ value: ["fresh"] }));
});
it("refreshing object B does not invalidate object A's concurrent facet read", async () => {
const requestA = { ...request, tableName: "accounts" };
const requestB = { ...request, tableName: "billing" };
let releaseA: (value: unknown) => void = () => {};
let releaseB: (value: unknown) => void = () => {};
let diskReads = 0;
mocks.loadSchemaCache.mockImplementation((cacheKey: string) => {
diskReads += 1;
if (diskReads > 2) return Promise.resolve(null);
return new Promise((resolve) => {
if (cacheKey.includes(":accounts:")) releaseA = resolve;
if (cacheKey.includes(":billing:")) releaseB = resolve;
});
});
const loaderA = vi.fn().mockResolvedValue(["remote accounts"]);
const loaderB = vi.fn().mockResolvedValue(["remote billing"]);
const loadA = loadObjectMetadataFacet(requestA, "columns", loaderA);
const loadB = loadObjectMetadataFacet(requestB, "columns", loaderB);
await vi.waitFor(() => expect(mocks.loadSchemaCache).toHaveBeenCalledTimes(2));
const invalidation = invalidateObjectMetadataCache(requestB);
releaseA({ version: 1, cachedAt: new Date().toISOString(), value: ["cached accounts"] });
releaseB({ version: 1, cachedAt: new Date().toISOString(), value: ["stale billing"] });
await expect(loadA).resolves.toEqual({ value: ["cached accounts"], cacheStatus: "disk" });
await expect(loadB).resolves.toEqual({ value: ["remote billing"], cacheStatus: "remote" });
await invalidation;
expect(loaderA).not.toHaveBeenCalled();
expect(loaderB).toHaveBeenCalledTimes(1);
});
it("reclaims invalidation state after long-running multi-object refreshes", async () => {
for (let index = 0; index < 2_000; index += 1) {
await invalidateObjectMetadataCache({ ...request, tableName: `history_${index}` });
}
expect(getObjectMetadataCacheDebugStateForTests()).toEqual({ activeReads: 0 });
});
it("makes a concurrent normal facet read wait for a force refresh", async () => {
const loader = vi.fn().mockResolvedValueOnce(["old"]);
await loadObjectMetadataFacet(request, "indexes", loader);
let releaseRemote: (value: string[]) => void = () => {};
loader.mockReturnValueOnce(
new Promise((resolve) => {
releaseRemote = resolve;
}),
);
const force = loadObjectMetadataFacet(request, "indexes", loader, { force: true });
const normal = loadObjectMetadataFacet(request, "indexes", loader);
await vi.waitFor(() => expect(loader).toHaveBeenCalledTimes(2));
releaseRemote(["new"]);
await expect(Promise.all([force, normal])).resolves.toEqual([
{ value: ["new"], cacheStatus: "remote" },
{ value: ["new"], cacheStatus: "remote" },
]);
expect(loader).toHaveBeenCalledTimes(2);
});
it("cancels an old connection facet load without repopulating the new session cache", async () => {
let releaseOld: (value: string[]) => void = () => {};
const loader = vi.fn().mockReturnValueOnce(
new Promise((resolve) => {
releaseOld = resolve;
}),
);
const oldLoad = loadObjectMetadataFacet(request, "columns", loader);
await vi.waitFor(() => expect(loader).toHaveBeenCalledTimes(1));
cancelObjectMetadataLoadsForConnection(request.connectionId);
releaseOld(["old session"]);
await expect(oldLoad).rejects.toThrow("Metadata waiting cancelled locally.");
loader.mockResolvedValueOnce(["new session"]);
await expect(loadObjectMetadataFacet(request, "columns", loader)).resolves.toMatchObject({ value: ["new session"], cacheStatus: "remote" });
expect(loader).toHaveBeenCalledTimes(2);
expect(mocks.deleteSchemaCachePrefix).not.toHaveBeenCalledWith("object-meta:v1:c1:");
});
describe("strict invalidation", () => {
it("rejects with a marked object cache error in strict mode and stays best-effort by default", async () => {
mocks.deleteSchemaCachePrefix.mockRejectedValue(new Error("sqlite locked"));
const failure = await invalidateObjectMetadataCache({ connectionId: "c1" }, { strict: true }).then(
() => undefined,
(error: unknown) => error,
);
expect(failure).toBeInstanceOf(Error);
expect(isObjectCacheInvalidationError(failure)).toBe(true);
expect((failure as Error).message).toBe("sqlite locked");
expect(mocks.deleteSchemaCachePrefix).toHaveBeenCalledWith("object-meta:v1:c1:");
mocks.deleteSchemaCachePrefix.mockClear();
mocks.deleteSchemaCachePrefix.mockRejectedValue(new Error("sqlite locked"));
await expect(invalidateObjectMetadataCache({ connectionId: "c1" })).resolves.toBeUndefined();
expect(mocks.deleteSchemaCachePrefix).toHaveBeenCalledWith("object-meta:v1:c1:");
});
it("force facet loads tolerate a failed persisted deletion", async () => {
mocks.deleteSchemaCachePrefix.mockRejectedValue(new Error("locked"));
const loader = vi.fn().mockResolvedValue(["fresh"]);
await expect(loadObjectMetadataFacet(request, "columns", loader, { force: true })).resolves.toEqual({ value: ["fresh"], cacheStatus: "remote" });
expect(loader).toHaveBeenCalledTimes(1);
});
});
});