signalk-parquet/dist/utils/duckdb-pool.d.ts

Vessel data Parquet file archive with automated value and geospatial triggers. History API compliant with cloud backups and queries.

/**
 * Singleton DuckDB instance with connection pooling
 * Loads spatial extension once on initialization
 *
 * This eliminates the performance overhead of creating new DuckDB instances
 * for every request and repeatedly loading the spatial extension.
 *
 * @example
 * ```typescript
 * // During plugin startup
 * await DuckDBPool.initialize();
 *
 * // In request handlers
 * const connection = await DuckDBPool.getConnection();
 * const result = await connection.runAndReadAll("SELECT * FROM ...");
 * // ... process result
 * // Note: DuckDB connections close automatically when no longer referenced
 *
 * // During plugin shutdown
 * await DuckDBPool.shutdown();
 * ```
 */
export interface S3Config {
    accessKeyId: string;
    secretAccessKey: string;
    region: string;
    endpoint?: string;
    useSSL?: boolean;
    urlStyle?: 'path' | 'vhost';
}
export declare class DuckDBPool {
    private static instance;
    private static initialized;
    private static s3Initialized;
    private static sqliteDbPath;
    private static sqliteInitialized;
    /**
     * Initialize the DuckDB instance and load extensions
     * Call this once during plugin startup
     *
     * @throws Error if initialization fails
     */
    static initialize(homeBaseDir?: string): Promise<void>;
    /**
     * Get a connection from the pool
     * The connection shares the same instance, so spatial extension is already loaded
     *
     * @returns A new connection (closes automatically when no longer referenced)
     * @throws Error if pool is not initialized
     */
    static getConnection(): Promise<import("@duckdb/node-api").DuckDBConnection>;
    /**
     * Store the SQLite buffer database path for federated queries.
     * Call this after initialize() and after the SQLiteBuffer is created.
     *
     * The path is used only as a "buffer exists" signal and for diagnostics —
     * DuckDB must NEVER open buffer.db itself (see buffer-staging.ts for why
     * the old ATTACH approach crashed the server).
     *
     * @param dbPath Absolute path to the SQLite buffer.db file
     */
    static initializeSQLiteBuffer(dbPath: string): void;
    /**
     * Check if the SQLite buffer path has been configured
     */
    static isSQLiteBufferInitialized(): boolean;
    /**
     * Get the configured SQLite buffer path (or null)
     */
    static getSQLiteBufferPath(): string | null;
    /**
     * Cleanup on plugin shutdown
     * Sets the instance to null to allow garbage collection
     */
    static shutdown(): Promise<void>;
    /**
     * Check if pool is ready
     * @returns true if the pool has been initialized
     */
    static isInitialized(): boolean;
    /**
     * Initialize S3 credentials for DuckDB
     * This allows DuckDB to query S3 parquet files directly
     *
     * @param config S3 configuration with credentials and region
     * @throws Error if pool is not initialized or S3 setup fails
     */
    static initializeS3(config: S3Config): Promise<void>;
    /**
     * Check if S3 credentials have been initialized
     * @returns true if S3 is ready for queries
     */
    static isS3Initialized(): boolean;
}
//# sourceMappingURL=duckdb-pool.d.ts.map