/**
 * ConnectionCache — Ref-counted shared database connection pool
 *
 * Multiple MCP sessions on the same database share a single SQLite connection.
 * Connections are opened on first acquire and closed when refCount reaches 0.
 *
 * WHY SHARING IS SAFE:
 * - Node.js is single-threaded (event loop)
 * - better-sqlite3 operations are synchronous (blocking)
 * - Two tool handlers cannot truly execute simultaneously
 * - WAL mode supports concurrent reads on a single connection
 *
 * CRITICAL: NEVER use console.log() — stdout is JSON-RPC (IMM-02).
 * FAIL FAST: Throw on errors, never return null or default values.
 *
 * @module server/connection-cache
 */
import { DatabaseService } from '../services/storage/database/index.js';
/**
 * Metrics snapshot for diagnostics and monitoring.
 */
export interface ConnectionCacheMetrics {
    /** Number of currently open connections */
    openConnections: number;
    /** Total connections opened since cache creation */
    totalOpened: number;
    /** Total connections closed since cache creation */
    totalClosed: number;
    /** Cache hits (acquire on existing connection) */
    cacheHits: number;
    /** Cache misses (acquire required opening a new connection) */
    cacheMisses: number;
    /** Per-connection details */
    connections: Array<{
        name: string;
        path: string;
        refCount: number;
        lastAccess: number;
        createdAt: number;
    }>;
}
/**
 * ConnectionCache — shared, ref-counted database connection pool.
 *
 * acquire(name, storagePath) opens or reuses a connection and increments refCount.
 * release(name) decrements refCount and closes immediately when it reaches 0.
 * closeAll() force-closes everything for shutdown.
 */
export declare class ConnectionCache {
    private readonly connections;
    /** Cumulative counters for metrics */
    private totalOpened;
    private totalClosed;
    private cacheHits;
    private cacheMisses;
    /**
     * Acquire a database connection. Opens on first use, reuses on subsequent calls.
     *
     * @param name - Database name (used as cache key)
     * @param storagePath - Storage directory containing the .db file
     * @returns The DatabaseService instance for this database
     * @throws MCPError with DATABASE_NOT_FOUND if database does not exist
     * @throws Error if DatabaseService.open() fails
     */
    acquire(name: string, storagePath: string): DatabaseService;
    /**
     * Release a connection reference. Closes the connection when refCount reaches 0.
     *
     * @param name - Database name to release
     * @throws Error if no connection exists for this name
     */
    release(name: string): void;
    /**
     * Force-close all connections. Used during process shutdown.
     * Ignores refCounts — unconditionally closes everything.
     */
    closeAll(): void;
    /**
     * Get a snapshot of cache metrics for monitoring and health checks.
     */
    getMetrics(): ConnectionCacheMetrics;
    /**
     * Check if a connection is currently cached for the given database name.
     */
    has(name: string): boolean;
    /**
     * Get the current refCount for a cached connection (for diagnostics/testing).
     *
     * @param name - Database name
     * @returns refCount, or 0 if no connection is cached
     */
    getRefCount(name: string): number;
    /**
     * Close a connection and remove it from the cache.
     */
    private closeAndRemove;
}
//# sourceMappingURL=connection-cache.d.ts.map