@mastra/dsql 0.0.0-ag-example-20260516005230

package/dist/shared/batch.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Batch utilities for Aurora DSQL.
+ *
+ * Aurora DSQL has transaction limits:
+ * - Maximum 3,000 rows per transaction
+ * - Maximum 10 MiB per transaction
+ *
+ * This utility only enforces the row-count limit.
+ * The 10 MiB limit depends on the size of each record, so please enforce it
+ * in the caller if needed.
+ */
+/**
+ * Default maximum rows per batch.
+ * Aurora DSQL limits transactions to 3,000 rows.
+ */
+export declare const DEFAULT_MAX_ROWS_PER_BATCH = 3000;
+/**
+ * Options for batch splitting.
+ */
+export interface BatchOptions {
+    /**
+     * Maximum number of rows per batch.
+     * @default 3000 (Aurora DSQL limit)
+     */
+    maxRows?: number;
+}
+/**
+ * Result of batch splitting.
+ */
+export interface BatchResult<T> {
+    /** The batched records */
+    batches: T[][];
+    /** Total number of records */
+    totalRecords: number;
+    /** Number of batches created */
+    batchCount: number;
+}
+/**
+ * Split an array of records into batches that respect Aurora DSQL's transaction limits.
+ *
+ * @param records - Array of records to split
+ * @param options - Batch splitting options
+ * @returns BatchResult containing the batched records and metadata
+ *
+ * @example
+ * ```typescript
+ * const records = generateRecords(5000);
+ * const result = splitIntoBatches(records);
+ * // result.batches.length === 2
+ * // result.batches[0].length === 3000
+ * // result.batches[1].length === 2000
+ * ```
+ */
+export declare function splitIntoBatches<T>(records: T[], options?: BatchOptions): BatchResult<T>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/shared/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/shared/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,0BAA0B;IAC1B,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;IACf,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAAC,CAAC,CAAC,CAyB5F"}

package/dist/shared/config.d.ts

@@ -0,0 +1,129 @@
+import type { AwsCredentialIdentityProvider } from '@aws-sdk/types';
+import type { CreateIndexOptions } from '@mastra/core/storage';
+import type { Pool } from 'pg';
+/**
+ * Default connection pool settings optimized for Aurora DSQL.
+ *
+ * Aurora DSQL has a 60-minute maximum connection duration limit,
+ * so maxLifetimeSeconds is set to 55 minutes to ensure connections
+ * are rotated before hitting that limit.
+ */
+export declare const DSQL_POOL_DEFAULTS: {
+    /** Maximum connections in the pool */
+    readonly max: 10;
+    /** Minimum connections in the pool */
+    readonly min: 0;
+    /** Close idle connections after 10 minutes */
+    readonly idleTimeoutMillis: 600000;
+    /** Force connection rotation before DSQL's 60-minute limit */
+    readonly maxLifetimeSeconds: 3300;
+    /** Connection acquisition timeout */
+    readonly connectionTimeoutMillis: 5000;
+    /** Allow process to exit when idle */
+    readonly allowExitOnIdle: true;
+};
+/**
+ * Base configuration options shared across Aurora DSQL configs.
+ */
+export interface DSQLBaseConfig {
+    /** Unique identifier for this store instance */
+    id: string;
+    /** Schema name (default: "public") */
+    schemaName?: string;
+    /**
+     * If true, the store will not be initialized automatically when used with Mastra.
+     * Use this when you want to manage initialization timing yourself.
+     */
+    disableInit?: boolean;
+    /** Skip creation of default indexes (default: false) */
+    skipDefaultIndexes?: boolean;
+    /** Custom index definitions to create */
+    indexes?: CreateIndexOptions[];
+}
+/**
+ * Aurora DSQL host-based configuration.
+ *
+ * Aurora DSQL uses IAM authentication, so password is not required.
+ * The connector automatically generates IAM tokens for authentication.
+ */
+export interface HostConfig extends DSQLBaseConfig {
+    /** DSQL cluster endpoint (e.g., "abc123.dsql.us-east-1.on.aws") */
+    host: string;
+    /** Database user (default: "admin") */
+    user?: string;
+    /** Database name (default: "postgres", Aurora DSQL supports only one database per cluster) */
+    database?: string;
+    /** AWS region (auto-detected from host if not provided) */
+    region?: string;
+    /** Custom AWS credentials provider (optional, uses default credential chain if not provided) */
+    customCredentialsProvider?: AwsCredentialIdentityProvider;
+    /** Maximum number of connections in the pool (default: 10) */
+    max?: number;
+    /** Minimum number of connections in the pool (default: 0) */
+    min?: number;
+    /** Close idle connections after this many milliseconds (default: 600000 = 10 minutes) */
+    idleTimeoutMillis?: number;
+    /** Maximum connection lifetime in seconds (default: 3300 = 55 minutes, must be < 60 minutes due to DSQL limit) */
+    maxLifetimeSeconds?: number;
+    /** Connection timeout in milliseconds (default: 5000) */
+    connectionTimeoutMillis?: number;
+    /** Allow the process to exit when all connections are idle (default: true) */
+    allowExitOnIdle?: boolean;
+}
+/**
+ * Pre-configured pg.Pool configuration for Aurora DSQL.
+ */
+export interface PoolInstanceConfig extends DSQLBaseConfig {
+    /**
+     * Pre-configured pg.Pool instance.
+     * Use this for direct control over the connection pool, or for
+     * integration with libraries that expect a pg.Pool.
+     *
+     * @example
+     * ```typescript
+     * import { Pool } from 'pg';
+     * import { AuroraDSQLClient } from '@aws/aurora-dsql-node-postgres-connector';
+     *
+     * const pool = new Pool({
+     *   host: 'abc123.dsql.us-east-1.on.aws',
+     *   Client: AuroraDSQLClient,
+     *   region: 'us-east-1',
+     * });
+     * const store = new DSQLStore({ id: 'my-store', pool });
+     *
+     * // Use store.pool for other libraries that need a pg.Pool
+     * ```
+     */
+    pool: Pool;
+}
+/**
+ * Aurora DSQL configuration type.
+ *
+ * Accepts either:
+ * - A pre-configured pg.Pool: `{ id, pool, schemaName? }`
+ * - Host-based config: `{ id, host, ... }`
+ */
+export type DSQLStoreConfig = PoolInstanceConfig | HostConfig | DSQLBaseConfig;
+/**
+ * Type guard for pre-configured pg.Pool config
+ */
+export declare const isPoolConfig: (cfg: DSQLStoreConfig) => cfg is PoolInstanceConfig;
+/**
+ * Type guard for host-based config
+ */
+export declare const isHostConfig: (cfg: DSQLStoreConfig) => cfg is HostConfig;
+/**
+ * Validates the DSQLStoreConfig and throws an error if invalid.
+ */
+export declare const validateConfig: (config: DSQLStoreConfig) => void;
+/**
+ * Extracts AWS region from DSQL host endpoint.
+ * DSQL endpoints follow the pattern: <cluster-id>.dsql.<region>.on.aws
+ */
+export declare const extractRegionFromHost: (host: string) => string | undefined;
+/**
+ * Returns the effective region, either from config or extracted from host.
+ * Only applicable for host-based config (not pre-configured pool).
+ */
+export declare const getEffectiveRegion: (config: HostConfig) => string;
+//# sourceMappingURL=config.d.ts.map

package/dist/shared/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;IAC7B,sCAAsC;;IAEtC,sCAAsC;;IAEtC,8CAA8C;;IAE9C,8DAA8D;;IAE9D,qCAAqC;;IAErC,sCAAsC;;CAE9B,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IAEX,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,yCAAyC;IACzC,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IAEb,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gGAAgG;IAChG,yBAAyB,CAAC,EAAE,6BAA6B,CAAC;IAE1D,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,yDAAyD;IACzD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,8EAA8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,UAAU,GAAG,cAAc,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,eAAe,KAAG,GAAG,IAAI,kBAE1D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,eAAe,KAAG,GAAG,IAAI,UAE1D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,eAAe,KAAG,IA6BxD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAG7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,UAAU,KAAG,MAavD,CAAC"}

package/dist/shared/retry.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Retry utilities for Aurora DSQL (PostgreSQL + OCC).
+ *
+ * Aurora DSQL uses optimistic concurrency control (OCC) and may return
+ * serialization errors (SQLSTATE 40001) that require retry. This module
+ * provides utilities for handling such errors with exponential backoff
+ * and full jitter.
+ *
+ * **Scope**: By default, this utility only retries OCC-related failures
+ * identified by PostgreSQL SQLSTATE codes. Network-level or OS-level errors
+ * are out of scope for the default implementation. Callers can provide a
+ * custom `isRetriable` function to extend retriable conditions if needed.
+ *
+ * @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+ */
+/**
+ * PostgreSQL SQLSTATE codes that may be retriable.
+ *
+ * By default, `isRetriableError` only retries `SERIALIZATION_FAILURE` (40001),
+ * which is the primary OCC conflict error from Aurora DSQL.
+ *
+ * Other codes are provided for reference and can be used with a custom
+ * `isRetriable` function if needed.
+ *
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+export declare const RETRIABLE_ERROR_CODES: {
+    /** Serialization failure - OCC conflict in Aurora DSQL (default retriable) */
+    readonly SERIALIZATION_FAILURE: "40001";
+    /** Deadlock detected (not retriable by default) */
+    readonly DEADLOCK_DETECTED: "40P01";
+    /** Connection failure - may be transient (not retriable by default) */
+    readonly CONNECTION_FAILURE: "08006";
+    /** Connection does not exist (not retriable by default) */
+    readonly CONNECTION_DOES_NOT_EXIST: "08003";
+    /** Admin shutdown - server is restarting (not retriable by default) */
+    readonly ADMIN_SHUTDOWN: "57P01";
+    /** Crash shutdown (not retriable by default) */
+    readonly CRASH_SHUTDOWN: "57P02";
+    /** Cannot connect now (not retriable by default) */
+    readonly CANNOT_CONNECT_NOW: "57P03";
+};
+/**
+ * Options for retry behavior.
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts (including the initial attempt).
+     * Must be >= 1.
+     * @default 5
+     */
+    maxAttempts?: number;
+    /**
+     * Initial delay in milliseconds before first retry.
+     * Must be >= 0.
+     * @default 100
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds between retries.
+     * Must be > 0 and >= initialDelayMs.
+     * @default 2000
+     */
+    maxDelayMs?: number;
+    /**
+     * Multiplier for exponential backoff.
+     * Must be >= 1.
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Whether to add jitter to retry delays.
+     * When true, uses "full jitter" algorithm: delay is uniformly random in [0, cappedDelay].
+     * @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+     * @default true
+     */
+    jitter?: boolean;
+    /**
+     * Optional callback invoked before each retry.
+     * @param error - The error that triggered the retry
+     * @param attempt - The attempt number that failed (1-based)
+     * @param delayMs - The delay before the next attempt
+     */
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+    /**
+     * Custom function to determine if an error is retriable.
+     * If not provided, uses the default `isRetriableError` function which only
+     * retries on SQLSTATE 40001 (OCC serialization failure).
+     */
+    isRetriable?: (error: unknown) => boolean;
+}
+/**
+ * Default retry options.
+ *
+ * Note: maxDelayMs is set to 2000ms as the standard for most operations.
+ * For batch operations that may need more recovery time, override with 5000ms.
+ */
+export declare const DEFAULT_RETRY_OPTIONS: Required<Omit<RetryOptions, 'onRetry' | 'isRetriable'>>;
+/**
+ * Interface for PostgreSQL errors (from pg library).
+ */
+export interface PostgresError extends Error {
+    code?: string;
+    severity?: string;
+    detail?: string;
+    hint?: string;
+    position?: string;
+    internalPosition?: string;
+    internalQuery?: string;
+    where?: string;
+    schema?: string;
+    table?: string;
+    column?: string;
+    dataType?: string;
+    constraint?: string;
+    file?: string;
+    line?: string;
+    routine?: string;
+}
+/**
+ * Check if an error is a PostgreSQL error with a code.
+ */
+export declare function isPostgresError(error: unknown): error is PostgresError;
+/**
+ * Get the PostgreSQL error code from an error, if available.
+ */
+export declare function getErrorCode(error: unknown): string | undefined;
+/**
+ * Check if an error is retriable based on its PostgreSQL SQLSTATE code.
+ *
+ * This function is designed for Aurora DSQL's OCC (Optimistic Concurrency Control).
+ * By default, only SQLSTATE 40001 (serialization failure) is considered retriable.
+ *
+ * **Important**: This function does NOT retry on:
+ * - Network errors (ECONNRESET, ECONNREFUSED, etc.)
+ * - Timeout errors
+ * - Other connection-level errors
+ *
+ * If you need to retry on additional error types, provide a custom `isRetriable`
+ * function to `withRetry`.
+ *
+ * @param error - The error to check
+ * @returns True if the error has a retriable SQLSTATE code (40001 by default)
+ *
+ * @example
+ * ```typescript
+ * // Create a PostgreSQL-like error
+ * const createPgError = (code: string, message: string): PostgresError => {
+ *   const err = new Error(message) as PostgresError;
+ *   err.code = code;
+ *   return err;
+ * };
+ *
+ * // Default: only retries on 40001
+ * isRetriableError(createPgError('40001', 'serialization failure')); // true
+ * isRetriableError(createPgError('40P01', 'deadlock detected'));     // false
+ * isRetriableError(new Error('connection timeout'));                 // false
+ *
+ * // Custom retriable check with additional codes:
+ * const customIsRetriable = (error: unknown) => {
+ *   const code = getErrorCode(error);
+ *   return code === '40001' || code === '40P01';
+ * };
+ * ```
+ */
+export declare function isRetriableError(error: unknown): boolean;
+/**
+ * Result of a retry operation.
+ */
+export interface RetryResult<T> {
+    /** The result if successful */
+    result: T;
+    /** Number of attempts made */
+    attempts: number;
+    /** Total time spent (including delays) in milliseconds */
+    totalTimeMs: number;
+}
+/**
+ * Execute a function with automatic retry on retriable errors.
+ *
+ * Uses exponential backoff with optional full jitter to avoid thundering herd.
+ * By default, only retries on PostgreSQL SQLSTATE 40001 (OCC serialization failure),
+ * which is the primary conflict error from Aurora DSQL.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry options
+ * @returns The result of the function along with metadata
+ * @throws The original error if all attempts fail or the error is not retriable
+ * @throws Error if retry options are invalid
+ *
+ * @example
+ * ```typescript
+ * const { result, attempts, totalTimeMs } = await withRetry(
+ *   async () => {
+ *     return await db.query('INSERT INTO users ...');
+ *   },
+ *   {
+ *     maxAttempts: 3,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms: ${error.message}`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/shared/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/shared/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;IAChC,8EAA8E;;IAE9E,mDAAmD;;IAEnD,uEAAuE;;IAEvE,2DAA2D;;IAE3D,uEAAuE;;IAEvE,gDAAgD;;IAEhD,oDAAoD;;CAE5C,CAAC;AAQX;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnE;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,aAAa,CAAC,CAMzF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK/D;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQxD;AAqFD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,+BAA+B;IAC/B,MAAM,EAAE,CAAC,CAAC;IACV,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoD5G"}

package/dist/storage/client.d.ts

@@ -0,0 +1,91 @@
+import type { Pool, PoolClient, QueryResult } from 'pg';
+export type { Pool, PoolClient, QueryResult } from 'pg';
+/**
+ * Values array for parameterized queries.
+ */
+export type QueryValues = unknown[];
+/**
+ * Common interface for database clients.
+ * DsqlPoolAdapter implements this interface by wrapping a pg.Pool.
+ */
+export interface DbClient {
+    /**
+     * The underlying connection pool.
+     */
+    readonly $pool: Pool;
+    /**
+     * Acquire a client from the pool for manual query execution.
+     * Remember to call client.release() when done.
+     */
+    connect(): Promise<PoolClient>;
+    /**
+     * Execute a query that returns no data.
+     * Use for INSERT, UPDATE, DELETE without RETURNING.
+     */
+    none(query: string, values?: QueryValues): Promise<null>;
+    /**
+     * Execute a query that returns exactly one row.
+     * @throws Error if zero or more than one row is returned
+     */
+    one<T = any>(query: string, values?: QueryValues): Promise<T>;
+    /**
+     * Execute a query that returns zero or one row.
+     * @returns The row, or null if no rows returned
+     * @throws Error if more than one row is returned
+     */
+    oneOrNone<T = any>(query: string, values?: QueryValues): Promise<T | null>;
+    /**
+     * Execute a query that returns any number of rows (including zero).
+     * Alias for manyOrNone.
+     */
+    any<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    /**
+     * Execute a query that returns zero or more rows.
+     */
+    manyOrNone<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    /**
+     * Execute a query that returns at least one row.
+     * @throws Error if no rows are returned
+     */
+    many<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    /**
+     * Execute a raw query, returning the full result object.
+     */
+    query(query: string, values?: QueryValues): Promise<QueryResult>;
+    /**
+     * Execute a function within a transaction.
+     * Automatically handles BEGIN, COMMIT, and ROLLBACK.
+     */
+    tx<T>(callback: (t: TxClient) => Promise<T>): Promise<T>;
+}
+/**
+ * Transaction client interface for executing queries within a transaction.
+ */
+export interface TxClient {
+    none(query: string, values?: QueryValues): Promise<null>;
+    one<T = any>(query: string, values?: QueryValues): Promise<T>;
+    oneOrNone<T = any>(query: string, values?: QueryValues): Promise<T | null>;
+    any<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    manyOrNone<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    many<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    query(query: string, values?: QueryValues): Promise<QueryResult>;
+    /** Execute multiple promises in parallel */
+    batch<T>(promises: Promise<T>[]): Promise<T[]>;
+}
+/**
+ * Adapter that wraps a pg.Pool to implement DbClient.
+ */
+export declare class PoolAdapter implements DbClient {
+    readonly $pool: Pool;
+    constructor($pool: Pool);
+    connect(): Promise<PoolClient>;
+    none(query: string, values?: QueryValues): Promise<null>;
+    one<T = any>(query: string, values?: QueryValues): Promise<T>;
+    oneOrNone<T = any>(query: string, values?: QueryValues): Promise<T | null>;
+    any<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    manyOrNone<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    many<T = any>(query: string, values?: QueryValues): Promise<T[]>;
+    query(query: string, values?: QueryValues): Promise<QueryResult>;
+    tx<T>(callback: (t: TxClient) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/storage/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/storage/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAGxD,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,EAAE,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAErB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9D;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE3E;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhE;;OAEG;IACH,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvE;;;OAGG;IACH,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEjE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEjE;;;OAGG;IACH,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3E,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAChE,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,4CAA4C;IAC5C,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAChD;AAaD;;GAEG;AACH,qBAAa,WAAY,YAAW,QAAQ;aACd,KAAK,EAAE,IAAI;gBAAX,KAAK,EAAE,IAAI;IAEvC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAIxB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAW7D,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAW1E,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAK/D,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAItE,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAQhE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAIhE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAoB/D"}

package/dist/storage/db/index.d.ts

@@ -0,0 +1,179 @@
+import { MastraBase } from '@mastra/core/base';
+import type { StorageColumn, TABLE_NAMES, CreateIndexOptions, IndexInfo, StorageIndexStats } from '@mastra/core/storage';
+import { Pool } from 'pg';
+import type { DbClient } from '../client.js';
+export type { DbClient } from '../client.js';
+/**
+ * Configuration for standalone domain usage.
+ * Accepts either:
+ * 1. An existing database client (Pool or PoolAdapter)
+ * 2. Config to create a new pool internally
+ */
+export type DsqlDomainConfig = DsqlDomainClientConfig | DsqlDomainPoolConfig | DsqlDomainRestConfig;
+/**
+ * Configuration for standalone domain usage.
+ * Accepts a database client instance.
+ */
+export interface DsqlDomainClientConfig {
+    /** The database client instance */
+    client: DbClient;
+    /** Database schema name */
+    schemaName?: string;
+    /** Skip creation of default indexes */
+    skipDefaultIndexes?: boolean;
+    /** Custom index definitions (filtered by domain's MANAGED_TABLES) */
+    indexes?: CreateIndexOptions[];
+}
+/**
+ * Pass an existing pg.Pool
+ */
+export interface DsqlDomainPoolConfig {
+    /** Pre-configured pg.Pool */
+    pool: Pool;
+    /** Optional schema name (defaults to 'public') */
+    schemaName?: string;
+    /** When true, default indexes will not be created during initialization */
+    skipDefaultIndexes?: boolean;
+    /** Custom indexes to create for this domain's tables */
+    indexes?: CreateIndexOptions[];
+}
+/**
+ * Pass config to create a new pg.Pool internally
+ */
+export type DsqlDomainRestConfig = {
+    /** Optional schema name (defaults to 'public') */
+    schemaName?: string;
+    /** When true, default indexes will not be created during initialization */
+    skipDefaultIndexes?: boolean;
+    /** Custom indexes to create for this domain's tables */
+    indexes?: CreateIndexOptions[];
+} & {
+    host: string;
+    database: string;
+    user: string;
+};
+/**
+ * Resolves DsqlDomainConfi to a database client and schema.
+ * Handles creating a new pool if config is provided.
+ */
+export declare function resolveDsqlConfig(config: DsqlDomainConfig): {
+    client: DbClient;
+    schemaName?: string;
+    skipDefaultIndexes?: boolean;
+    indexes?: CreateIndexOptions[];
+};
+/**
+ * Internal config for DsqlDB - accepts already-resolved client
+ */
+export interface DsqlDBInternalConfig {
+    client: DbClient;
+    schemaName?: string;
+    skipDefaultIndexes?: boolean;
+}
+export declare class DsqlDB extends MastraBase {
+    client: DbClient;
+    schemaName?: string;
+    skipDefaultIndexes?: boolean;
+    constructor(config: DsqlDBInternalConfig);
+    hasColumn(table: string, column: string): Promise<boolean>;
+    /**
+     * Prepares values for insertion, handling TEXT columns storing JSON by stringifying them.
+     * Aurora DSQL does not support JSONB natively, so we store JSON as TEXT.
+     */
+    private prepareValuesForInsert;
+    /**
+     * Adds timestamp Z columns to a record if timestamp columns exist
+     */
+    private addTimestampZColumns;
+    /**
+     * Prepares a value for database operations, handling Date objects and JSON serialization.
+     * This is schema-aware and stringifies objects for TEXT columns storing JSON.
+     * Aurora DSQL: We use TEXT instead of JSONB and cast to ::jsonb when filtering.
+     */
+    private prepareValue;
+    private setupSchema;
+    /**
+     * Override getSqlType to map JSONB to TEXT for Aurora DSQL compatibility.
+     * Aurora DSQL does not fully support native JSONB, so we store JSON as TEXT
+     * and cast to ::jsonb only when filtering/querying.
+     */
+    protected getSqlType(type: StorageColumn['type']): string;
+    protected getDefaultValue(type: StorageColumn['type']): string;
+    insert({ tableName, record }: {
+        tableName: TABLE_NAMES;
+        record: Record<string, any>;
+    }): Promise<void>;
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    /**
+     * Set up timestamp triggers for a table to automatically manage createdAt/updatedAt
+     * Note: Aurora DSQL doesn't support triggers, PL/pgSQL, or CREATE FUNCTION.
+     * Timestamps are managed at the application level in insert/update operations.
+     * This method is kept as a no-op for API compatibility.
+     */
+    private setupTimestampTriggers;
+    /**
+     * Migrates the spans table schema from OLD_SPAN_SCHEMA to current SPAN_SCHEMA.
+     * This adds new columns that don't exist in old schema.
+     */
+    private migrateSpansTable;
+    /**
+     * Alters table schema to add columns if they don't exist
+     * @param tableName Name of the table
+     * @param schema Schema of the table
+     * @param ifNotExists Array of column names to add if they don't exist
+     */
+    alterTable({ tableName, schema, ifNotExists, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+        ifNotExists: string[];
+    }): Promise<void>;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, string>;
+    }): Promise<R | null>;
+    batchInsert({ tableName, records }: {
+        tableName: TABLE_NAMES;
+        records: Record<string, any>[];
+    }): Promise<void>;
+    dropTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    /**
+     * Wait for an asynchronous DSQL job to complete.
+     * Aurora DSQL requires CREATE INDEX ASYNC and sys.wait_for_job() to wait for completion.
+     */
+    private waitForDSQLJob;
+    createIndex(options: CreateIndexOptions): Promise<void>;
+    dropIndex(indexName: string): Promise<void>;
+    listIndexes(tableName?: string): Promise<IndexInfo[]>;
+    describeIndex(indexName: string): Promise<StorageIndexStats>;
+    update({ tableName, keys, data, }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, any>;
+        data: Record<string, any>;
+    }): Promise<void>;
+    batchUpdate({ tableName, updates, }: {
+        tableName: TABLE_NAMES;
+        updates: Array<{
+            keys: Record<string, any>;
+            data: Record<string, any>;
+        }>;
+    }): Promise<void>;
+    batchDelete({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, any>[];
+    }): Promise<void>;
+    /**
+     * Delete all data from a table (alias for clearTable for consistency with other stores)
+     */
+    deleteData({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map