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 * as api from "@/lib/backend/api";
import { ActiveCacheReadTracker } from "./activeCacheReadTracker";
import { metadataLoadBudgetMs, waitForMetadata } from "./metadataLoadBudget";
import type { ObjectSourceKind } from "@/types/database";
import type { MetadataCacheInvalidation } from "./metadataResultCache";
import { invalidateObjectMetadataCache } from "./objectMetadataCache";
import { toObjectCacheInvalidationError, type ObjectCacheInvalidationOptions } from "./objectCacheInvalidationError";
import { getMetadataRuntimeCache, invalidateMetadataRuntimeCachePrefix, recordMetadataCacheL2Hit, recordMetadataCacheRemoteMiss, setMetadataRuntimeCache } from "./metadataRuntimeCache";
const OBJECT_DDL_CACHE_PREFIX = "object-ddl:v1";
const MAX_PERSISTED_DDL_CHARS = 5 * 1024 * 1024;
const MAX_PERSISTED_DDL_AGE_MS = 24 * 60 * 60 * 1000;
interface ObjectDdlCacheEnvelope {
version: 1;
cachedAt: string;
ddl: string;
}
interface InFlightDdlLoad {
force: boolean;
invalidated: boolean;
promise: Promise<string>;
}
export interface ObjectDdlRequest {
connectionId: string;
queryTimeoutSecs?: number;
database: string;
schema: string;
tableName: string;
objectType?: ObjectSourceKind;
catalog?: string;
exactIdentity?: boolean;
separateIndexes?: boolean;
explicitOwner?: string;
}
export interface ObjectDdlLoadResult {
ddl: string;
cacheStatus: "memory" | "disk" | "remote";
}
const remoteLoads = new Map<string, InFlightDdlLoad>();
const activeCacheReads = new ActiveCacheReadTracker();
const activeLoads = new ActiveCacheReadTracker();
const pendingInvalidations = new Map<string, Promise<void>>();
const pendingWrites = new Map<string, Promise<void>>();
async function loadSchemaCacheSafe<T>(cacheKey: string): Promise<T | null> {
try {
return await api.loadSchemaCache<T>(cacheKey);
} catch {
return null;
}
}
async function saveSchemaCacheSafe(cacheKey: string, payload: unknown): Promise<void> {
try {
await api.saveSchemaCache(cacheKey, payload);
} catch {
// Cache persistence is best effort and must not block DDL rendering.
}
}
function cacheSegment(value: string | undefined): string {
return encodeURIComponent(value ?? "");
}
export function objectDdlCacheKey(request: ObjectDdlRequest): string {
return `${[OBJECT_DDL_CACHE_PREFIX, cacheSegment(request.connectionId), cacheSegment(request.database), cacheSegment(request.schema), cacheSegment(request.tableName), cacheSegment(request.catalog), cacheSegment(request.objectType ?? "TABLE"), ...(request.exactIdentity ? ["exact-v1"] : []), ...(request.separateIndexes ? ["separate-indexes-v1"] : []), ...(request.separateIndexes && request.explicitOwner !== undefined ? ["owner-v1", cacheSegment(request.explicitOwner)] : [])].join(":")}:`;
}
function invalidationPrefix(match: MetadataCacheInvalidation): string {
const parts = [OBJECT_DDL_CACHE_PREFIX];
if (!match.connectionId) return `${OBJECT_DDL_CACHE_PREFIX}:`;
parts.push(cacheSegment(match.connectionId ?? undefined));
if (!match.database) return `${parts.join(":")}:`;
parts.push(cacheSegment(match.database ?? undefined));
if (!match.schema) return `${parts.join(":")}:`;
parts.push(cacheSegment(match.schema ?? undefined));
if (!match.tableName) return `${parts.join(":")}:`;
parts.push(cacheSegment(match.tableName));
return `${parts.join(":")}:`;
}
function sanitizeDdl(ddl: string): string {
return ddl.includes("\0") ? ddl.replaceAll("\0", "") : ddl;
}
function decodeCachedDdl(payload: unknown): string | null {
if (!payload || typeof payload !== "object") return null;
const envelope = payload as Partial<ObjectDdlCacheEnvelope>;
const cachedAt = typeof envelope.cachedAt === "string" ? Date.parse(envelope.cachedAt) : Number.NaN;
if (envelope.version !== 1 || !Number.isFinite(cachedAt) || Date.now() - cachedAt > MAX_PERSISTED_DDL_AGE_MS || typeof envelope.ddl !== "string") return null;
return sanitizeDdl(envelope.ddl);
}
async function waitForPendingInvalidations(cacheKey: string): Promise<void> {
// Readers only wait for pending deletions to settle; the failure itself is
// reported by the caller that started the invalidation.
const pending = [...pendingInvalidations.entries()].filter(([prefix]) => cacheKey.startsWith(prefix)).map(([, promise]) => promise.catch(() => undefined));
if (pending.length) await Promise.all(pending);
}
function invalidateRemoteLoad(cacheKey: string): void {
const entry = remoteLoads.get(cacheKey);
if (!entry) return;
entry.invalidated = true;
remoteLoads.delete(cacheKey);
}
function persistSchemaCache(cacheKey: string, payload: unknown, isInvalidated: () => boolean): void {
const previous = pendingWrites.get(cacheKey);
const write = (async () => {
if (previous) await previous;
if (!isInvalidated()) await saveSchemaCacheSafe(cacheKey, payload);
})().finally(() => {
if (pendingWrites.get(cacheKey) === write) pendingWrites.delete(cacheKey);
});
pendingWrites.set(cacheKey, write);
}
async function waitForPendingWrites(prefix: string): Promise<void> {
while (true) {
const pending = [...pendingWrites.entries()].filter(([cacheKey]) => cacheKey.startsWith(prefix)).map(([, promise]) => promise);
if (!pending.length) return;
await Promise.all(pending);
}
}
function invalidatePersistedPrefix(prefix: string): Promise<void> {
const existing = pendingInvalidations.get(prefix);
if (existing) return existing;
const deletion = (async () => {
await waitForPendingWrites(prefix);
// Deletion failures propagate so strict callers can observe them;
// best-effort callers catch at their own boundary.
await api.deleteSchemaCachePrefix(prefix);
})().finally(() => {
if (pendingInvalidations.get(prefix) === deletion) pendingInvalidations.delete(prefix);
});
pendingInvalidations.set(prefix, deletion);
return deletion;
}
async function loadRemoteDdl(request: ObjectDdlRequest, cacheKey: string, force: boolean, signal: AbortSignal): Promise<string> {
signal.throwIfAborted();
const existing = remoteLoads.get(cacheKey);
if (existing && (!force || existing.force)) return existing.promise;
if (existing) invalidateRemoteLoad(cacheKey);
const entry: InFlightDdlLoad = { force, invalidated: false, promise: Promise.resolve("") };
const cancel = () => {
entry.invalidated = true;
if (remoteLoads.get(cacheKey) === entry) remoteLoads.delete(cacheKey);
};
signal.addEventListener("abort", cancel, { once: true });
recordMetadataCacheRemoteMiss(cacheKey);
const remote = request.exactIdentity
? request.separateIndexes
? api.getTableDdl(request.connectionId, request.database, request.schema, request.tableName, request.objectType, request.catalog, false, true, true, request.explicitOwner)
: api.getTableDdl(request.connectionId, request.database, request.schema, request.tableName, request.objectType, request.catalog, false, true)
: request.separateIndexes
? api.getTableDisplayDdl(request.connectionId, request.database, request.schema, request.tableName, request.objectType, request.catalog, true, request.explicitOwner)
: api.getTableDisplayDdl(request.connectionId, request.database, request.schema, request.tableName, request.objectType, request.catalog);
entry.promise = waitForMetadata(
remote.then((rawDdl) => {
const ddl = sanitizeDdl(rawDdl);
const current = !entry.invalidated;
if (current && !request.exactIdentity && ddl.length <= MAX_PERSISTED_DDL_CHARS) {
const envelope: ObjectDdlCacheEnvelope = { version: 1, cachedAt: new Date().toISOString(), ddl };
setMetadataRuntimeCache(cacheKey, ddl, request.connectionId);
persistSchemaCache(cacheKey, envelope, () => entry.invalidated);
} else if (current) {
setMetadataRuntimeCache(cacheKey, ddl, request.connectionId);
}
return ddl;
}),
metadataLoadBudgetMs(request.queryTimeoutSecs),
signal,
).finally(() => {
signal.removeEventListener("abort", cancel);
if (remoteLoads.get(cacheKey) === entry) remoteLoads.delete(cacheKey);
});
remoteLoads.set(cacheKey, entry);
return entry.promise;
}
export async function loadObjectDdl(request: ObjectDdlRequest, options?: { force?: boolean }): Promise<ObjectDdlLoadResult> {
const token = activeLoads.begin(objectDdlCacheKey(request));
try {
return await waitForMetadata(loadObjectDdlInternal(request, token.controller.signal, options), metadataLoadBudgetMs(request.queryTimeoutSecs), token.controller.signal);
} catch (error) {
token.controller.abort(error);
throw error;
} finally {
activeLoads.finish(token);
}
}
async function loadObjectDdlInternal(request: ObjectDdlRequest, signal: AbortSignal, options?: { force?: boolean }): Promise<ObjectDdlLoadResult> {
const cacheKey = objectDdlCacheKey(request);
if (options?.force) {
const existing = remoteLoads.get(cacheKey);
if (existing?.force) return { ddl: await existing.promise, cacheStatus: "remote" };
invalidateRemoteLoad(cacheKey);
activeCacheReads.invalidatePrefix(cacheKey);
invalidateMetadataRuntimeCachePrefix(cacheKey);
const priorInvalidations = waitForPendingInvalidations(cacheKey);
const deletion = invalidatePersistedPrefix(cacheKey);
// A failed prefix deletion must not fail the force load itself.
await Promise.allSettled([priorInvalidations, deletion]);
} else {
await waitForPendingInvalidations(cacheKey);
}
signal.throwIfAborted();
if (!options?.force) {
const runtime = getMetadataRuntimeCache<string>(cacheKey);
if (runtime) return { ddl: runtime.value, cacheStatus: "memory" };
if (request.exactIdentity) return { ddl: await loadRemoteDdl(request, cacheKey, false, signal), cacheStatus: "remote" };
const readToken = activeCacheReads.begin(cacheKey);
let cached: string | null;
try {
cached = decodeCachedDdl(await waitForMetadata(loadSchemaCacheSafe<unknown>(cacheKey), metadataLoadBudgetMs(request.queryTimeoutSecs), signal));
} finally {
activeCacheReads.finish(readToken);
}
signal.throwIfAborted();
if (readToken.invalidated) {
await waitForPendingInvalidations(cacheKey);
return { ddl: await loadRemoteDdl(request, cacheKey, false, signal), cacheStatus: "remote" };
}
if (cached !== null) {
recordMetadataCacheL2Hit(cacheKey, cached);
setMetadataRuntimeCache(cacheKey, cached, request.connectionId);
return { ddl: cached, cacheStatus: "disk" };
}
}
return { ddl: await loadRemoteDdl(request, cacheKey, options?.force === true, signal), cacheStatus: "remote" };
}
export async function invalidateObjectDdlCache(match: MetadataCacheInvalidation, options?: ObjectCacheInvalidationOptions): Promise<void> {
const prefix = invalidationPrefix(match);
activeCacheReads.invalidatePrefix(prefix);
for (const cacheKey of [...remoteLoads.keys()]) if (cacheKey.startsWith(prefix)) invalidateRemoteLoad(cacheKey);
invalidateMetadataRuntimeCachePrefix(prefix);
const deletion = invalidatePersistedPrefix(prefix);
const metadataInvalidation = invalidateObjectMetadataCache(match, options);
// Wait for both namespace deletions to settle before deciding, so a strict
// caller never reports failure while the other deletion is still in flight.
const [ddlSettled, metaSettled] = await Promise.allSettled([deletion, metadataInvalidation]);
if (!options?.strict) return;
// Judge by settled status, never by the rejection reason's value: a bare
// Promise.reject() has reason undefined and must still count as a failure.
if (ddlSettled.status === "rejected") throw toObjectCacheInvalidationError(ddlSettled.reason, prefix);
if (metaSettled.status === "rejected") throw toObjectCacheInvalidationError(metaSettled.reason, prefix);
}
export async function invalidateObjectDdl(request: ObjectDdlRequest, options?: ObjectCacheInvalidationOptions & { metadata?: boolean }): Promise<void> {
const cacheKey = objectDdlCacheKey(request);
activeCacheReads.invalidatePrefix(cacheKey);
invalidateRemoteLoad(cacheKey);
invalidateMetadataRuntimeCachePrefix(cacheKey);
const results = await Promise.allSettled([
invalidatePersistedPrefix(cacheKey),
options?.metadata === false
? Promise.resolve()
: invalidateObjectMetadataCache(
{
connectionId: request.connectionId,
database: request.database,
schema: request.schema,
tableName: request.tableName,
},
options,
),
]);
if (options?.strict) for (const result of results) if (result.status === "rejected") throw toObjectCacheInvalidationError(result.reason, cacheKey);
}
/** Invalidate active loads for a disconnected connection without deleting its persisted snapshot. */
export function cancelObjectDdlLoadsForConnection(connectionId: string): void {
const prefix = `${OBJECT_DDL_CACHE_PREFIX}:${cacheSegment(connectionId)}:`;
activeLoads.cancelPrefix(prefix);
activeCacheReads.invalidatePrefix(prefix);
for (const cacheKey of [...remoteLoads.keys()]) if (cacheKey.startsWith(prefix)) invalidateRemoteLoad(cacheKey);
invalidateMetadataRuntimeCachePrefix(prefix);
}
export function cancelObjectDdlLoadsForDatabase(connectionId: string, database: string): void {
const prefix = `${OBJECT_DDL_CACHE_PREFIX}:${cacheSegment(connectionId)}:${cacheSegment(database)}:`;
activeLoads.cancelPrefix(prefix);
activeCacheReads.invalidatePrefix(prefix);
for (const cacheKey of [...remoteLoads.keys()]) if (cacheKey.startsWith(prefix)) invalidateRemoteLoad(cacheKey);
invalidateMetadataRuntimeCachePrefix(prefix);
}
export function getObjectDdlCacheDebugStateForTests(): { activeReads: number } {
return { activeReads: activeCacheReads.activeCount };
}