genkitx-cloud-sql-pg/lib/engine.d.mts

Genkit AI framework plugin for Cloud SQL for PostgreSQL.

import { IpAddressTypes, Connector } from '@google-cloud/cloud-sql-connector';
export { IpAddressTypes } from '@google-cloud/cloud-sql-connector';
import knex from 'knex';
import { BaseIndex } from './indexes.mjs';

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Defines the arguments for configuring a PostgreSQL engine.
 */
interface PostgresEngineArgs {
    /** The IP address type to use for the connection (e.g., PUBLIC, PRIVATE). */
    ipType?: IpAddressTypes;
    /** The PostgreSQL username for basic authentication. */
    user?: string;
    /** The PostgreSQL password for basic authentication. */
    password?: string;
    /** The IAM service account email for IAM database authentication. */
    iamAccountEmail?: string;
}
/**
 * Defines the arguments for configuring a vector store table.
 */
interface VectorStoreTableArgs {
    /** The schema name for the table. Defaults to "public". */
    schemaName?: string;
    /** The name of the column to store document content. Defaults to "content". */
    contentColumn?: string;
    /** The name of the column to store vector embeddings. Defaults to "embedding". */
    embeddingColumn?: string;
    /** An optional list of `Column` objects to create for custom metadata. Defaults to []. */
    metadataColumns?: Column[];
    /** The column to store extra metadata in JSON format. Defaults to "json_metadata". */
    metadataJsonColumn?: string;
    /**
     * The column to store IDs. Can be a string (column name) or a `Column` object
     * for more detailed configuration. Defaults to "id" with data type UUID.
     */
    idColumn?: string | Column;
    /** Whether to drop the existing table if it already exists. Defaults to false. */
    overwriteExisting?: boolean;
    /** Whether to store metadata in the table. Defaults to true. */
    storeMetadata?: boolean;
    /**
     * Whether to build the index concurrently (allowing concurrent operations on the table).
     * Defaults to false.
     */
    concurrently?: boolean;
    /** The name of the index. If not provided, a default name will be generated. */
    indexName?: string;
}
/**
 * Represents a database table column.
 */
declare class Column {
    /** The name of the column. */
    name: string;
    /** The data type of the column (e.g., 'TEXT', 'INT', 'UUID'). */
    dataType: string;
    /** Whether the column can be nullable. */
    nullable: boolean;
    /**
     * Creates an instance of Column.
     * @param {string} name - The name of the column.
     * @param {string} dataType - The data type of the column.
     * @param {boolean} [nullable=true] - Whether the column can be nullable. Defaults to true.
     */
    constructor(name: string, dataType: string, nullable?: boolean);
    private postInitilization;
}
/**
 * Manages connections and operations for a PostgreSQL database,
 * particularly for vector store functionalities.
 */
declare class PostgresEngine {
    private static _createKey;
    pool: knex.Knex<any, any[]>;
    static connector: Connector;
    constructor(key: Symbol, pool: knex.Knex<any, any[]>);
    /**
     * @param projectId Required - GCP Project ID
     * @param region Required - Postgres Instance Region
     * @param instance Required - Postgres Instance name
     * @param database Required - Database name
     * @param ipType Optional - IP address type. Defaults to IPAddressType.PUBLIC
     * @param user Optional - Postgres user name. Defaults to undefined
     * @param password Optional - Postgres user password. Defaults to undefined
     * @param iamAccountEmail Optional - IAM service account email. Defaults to undefined
     * @returns PostgresEngine instance
     */
    static fromInstance(projectId: string, region: string, instance: string, database: string, { ipType, user, password, iamAccountEmail, }?: PostgresEngineArgs): Promise<PostgresEngine>;
    /**
     * Create a PostgresEngine instance from an Knex instance.
     *
     * @param engine knex instance
     * @returns PostgresEngine instance from a knex instance
     */
    static fromEngine(engine: knex.Knex<any, any[]>): Promise<PostgresEngine>;
    /**
     * Create a PostgresEngine instance from arguments.
     *
     * @param url URL use to connect to a database
     * @param poolConfig Optional - Configuration pool to use in the Knex configuration
     * @returns PostgresEngine instance
     */
    static fromEngineArgs(url: string | knex.Knex.StaticConnectionConfig, poolConfig?: knex.Knex.PoolConfig): Promise<PostgresEngine>;
    /**
     * Create a table for saving of vectors to be used with PostgresVectorStore.
     *
     * @param tableName Postgres database table name
     * @param vectorSize Vector size for the embedding model to be used.
     * @param schemaName The schema name to store Postgres database table. Default: "public".
     * @param contentColumn Name of the column to store document content. Default: "content".
     * @param embeddingColumn Name of the column to store vector embeddings. Default: "embedding".
     * @param metadataColumns Optional - A list of Columns to create for custom metadata. Default: [].
     * @param metadataJsonColumn Optional - The column to store extra metadata in JSON format. Default: "json_metadata".
     * @param idColumn Optional - Column to store ids. Default: "id" column name with data type UUID.
     * @param overwriteExisting Whether to drop existing table. Default: False.
     * @param storeMetadata Whether to store metadata in the table. Default: True.
     */
    initVectorstoreTable(tableName: string, vectorSize: number, { schemaName, contentColumn, embeddingColumn, metadataColumns, metadataJsonColumn, idColumn, overwriteExisting, storeMetadata, }?: VectorStoreTableArgs): Promise<void>;
    /**
     *  Dispose of connection pool
     */
    closeConnection(): Promise<void>;
    /**
     * Just to test the connection to the database.
     * @returns A Promise that resolves to a row containing the current timestamp.
     */
    testConnection(): Promise<{
        currentTimestamp: Date;
    }[]>;
    /**
     * Create an index on the vector store table
     * @param {string} tableName
     * @param {BaseIndex} index
     * @param {VectorStoreTableArgs}
     */
    applyVectorIndex(tableName: string, index: BaseIndex, { schemaName, embeddingColumn, concurrently, }?: VectorStoreTableArgs): Promise<void>;
    /**
     * Check if index exists in the table.
     * @param {string} tableName
     * @param VectorStoreTableArgs Optional
     */
    isValidIndex(tableName: string, { indexName, schemaName }?: VectorStoreTableArgs): Promise<boolean>;
    /**
     * Drop the vector index
     * @param {string} tableName
     * @param {string} indexName Optional - index name
     */
    dropVectorIndex(params: {
        tableName?: string;
        indexName?: string;
    }): Promise<void>;
    /**
     * Re-index the vector store table
     * @param {string} tableName
     * @param {string} indexName Optional - index name
     */
    reIndex(params: {
        tableName?: string;
        indexName?: string;
    }): Promise<void>;
}

export { Column, PostgresEngine, type PostgresEngineArgs, type VectorStoreTableArgs };