@mastra/libsql 0.11.0-alpha.3 → 0.11.1-alpha.0

package/src/storage/domains/operations/index.ts

@@ -0,0 +1,296 @@
+import type { Client } from '@libsql/client';
+import { ErrorCategory, ErrorDomain, MastraError } from '@mastra/core/error';
+import { TABLE_WORKFLOW_SNAPSHOT, StoreOperations } from '@mastra/core/storage';
+import type { StorageColumn, TABLE_NAMES } from '@mastra/core/storage';
+import { parseSqlIdentifier } from '@mastra/core/utils';
+import { createExecuteWriteOperationWithRetry, prepareStatement } from '../utils';
+
+export class StoreOperationsLibSQL extends StoreOperations {
+  private client: Client;
+  /**
+   * Maximum number of retries for write operations if an SQLITE_BUSY error occurs.
+   * @default 5
+   */
+  maxRetries: number;
+  /**
+   * Initial backoff time in milliseconds for retrying write operations on SQLITE_BUSY.
+   * The backoff time will double with each retry (exponential backoff).
+   * @default 100
+   */
+  initialBackoffMs: number;
+
+  constructor({
+    client,
+    maxRetries,
+    initialBackoffMs,
+  }: {
+    client: Client;
+    maxRetries?: number;
+    initialBackoffMs?: number;
+  }) {
+    super();
+    this.client = client;
+
+    this.maxRetries = maxRetries ?? 5;
+    this.initialBackoffMs = initialBackoffMs ?? 100;
+  }
+
+  async hasColumn(table: string, column: string): Promise<boolean> {
+    const result = await this.client.execute({
+      sql: `PRAGMA table_info(${table})`,
+    });
+    return (await result.rows)?.some((row: any) => row.name === column);
+  }
+
+  private getCreateTableSQL(tableName: TABLE_NAMES, schema: Record<string, StorageColumn>): string {
+    const parsedTableName = parseSqlIdentifier(tableName, 'table name');
+    const columns = Object.entries(schema).map(([name, col]) => {
+      const parsedColumnName = parseSqlIdentifier(name, 'column name');
+      let type = col.type.toUpperCase();
+      if (type === 'TEXT') type = 'TEXT';
+      if (type === 'TIMESTAMP') type = 'TEXT'; // Store timestamps as ISO strings
+      // if (type === 'BIGINT') type = 'INTEGER';
+
+      const nullable = col.nullable ? '' : 'NOT NULL';
+      const primaryKey = col.primaryKey ? 'PRIMARY KEY' : '';
+
+      return `${parsedColumnName} ${type} ${nullable} ${primaryKey}`.trim();
+    });
+
+    // For workflow_snapshot table, create a composite primary key
+    if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
+      const stmnt = `CREATE TABLE IF NOT EXISTS ${parsedTableName} (
+                    ${columns.join(',\n')},
+                    PRIMARY KEY (workflow_name, run_id)
+                )`;
+      return stmnt;
+    }
+
+    return `CREATE TABLE IF NOT EXISTS ${parsedTableName} (${columns.join(', ')})`;
+  }
+
+  async createTable({
+    tableName,
+    schema,
+  }: {
+    tableName: TABLE_NAMES;
+    schema: Record<string, StorageColumn>;
+  }): Promise<void> {
+    try {
+      this.logger.debug(`Creating database table`, { tableName, operation: 'schema init' });
+      const sql = this.getCreateTableSQL(tableName, schema);
+      await this.client.execute(sql);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_CREATE_TABLE_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+          },
+        },
+        error,
+      );
+    }
+  }
+
+  protected getSqlType(type: StorageColumn['type']): string {
+    switch (type) {
+      case 'bigint':
+        return 'INTEGER'; // SQLite uses INTEGER for all integer sizes
+      case 'jsonb':
+        return 'TEXT'; // Store JSON as TEXT in SQLite
+      default:
+        return super.getSqlType(type);
+    }
+  }
+
+  private async doInsert({
+    tableName,
+    record,
+  }: {
+    tableName: TABLE_NAMES;
+    record: Record<string, any>;
+  }): Promise<void> {
+    await this.client.execute(
+      prepareStatement({
+        tableName,
+        record,
+      }),
+    );
+  }
+
+  public insert(args: { tableName: TABLE_NAMES; record: Record<string, any> }): Promise<void> {
+    const executeWriteOperationWithRetry = createExecuteWriteOperationWithRetry({
+      logger: this.logger,
+      maxRetries: this.maxRetries,
+      initialBackoffMs: this.initialBackoffMs,
+    });
+    return executeWriteOperationWithRetry(() => this.doInsert(args), `insert into table ${args.tableName}`);
+  }
+
+  async load<R>({ tableName, keys }: { tableName: TABLE_NAMES; keys: Record<string, string> }): Promise<R | null> {
+    const parsedTableName = parseSqlIdentifier(tableName, 'table name');
+
+    const parsedKeys = Object.keys(keys).map(key => parseSqlIdentifier(key, 'column name'));
+
+    const conditions = parsedKeys.map(key => `${key} = ?`).join(' AND ');
+    const values = Object.values(keys);
+
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${parsedTableName} WHERE ${conditions} ORDER BY createdAt DESC LIMIT 1`,
+      args: values,
+    });
+
+    if (!result.rows || result.rows.length === 0) {
+      return null;
+    }
+
+    const row = result.rows[0];
+    // Checks whether the string looks like a JSON object ({}) or array ([])
+    // If the string starts with { or [, it assumes it's JSON and parses it
+    // Otherwise, it just returns, preventing unintended number conversions
+    const parsed = Object.fromEntries(
+      Object.entries(row || {}).map(([k, v]) => {
+        try {
+          return [k, typeof v === 'string' ? (v.startsWith('{') || v.startsWith('[') ? JSON.parse(v) : v) : v];
+        } catch {
+          return [k, v];
+        }
+      }),
+    );
+
+    return parsed as R;
+  }
+
+  private async doBatchInsert({
+    tableName,
+    records,
+  }: {
+    tableName: TABLE_NAMES;
+    records: Record<string, any>[];
+  }): Promise<void> {
+    if (records.length === 0) return;
+    const batchStatements = records.map(r => prepareStatement({ tableName, record: r }));
+    await this.client.batch(batchStatements, 'write');
+  }
+
+  public batchInsert(args: { tableName: TABLE_NAMES; records: Record<string, any>[] }): Promise<void> {
+    const executeWriteOperationWithRetry = createExecuteWriteOperationWithRetry({
+      logger: this.logger,
+      maxRetries: this.maxRetries,
+      initialBackoffMs: this.initialBackoffMs,
+    });
+
+    return executeWriteOperationWithRetry(
+      () => this.doBatchInsert(args),
+      `batch insert into table ${args.tableName}`,
+    ).catch(error => {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_BATCH_INSERT_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName: args.tableName,
+          },
+        },
+        error,
+      );
+    });
+  }
+
+  /**
+   * 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
+   */
+  async alterTable({
+    tableName,
+    schema,
+    ifNotExists,
+  }: {
+    tableName: TABLE_NAMES;
+    schema: Record<string, StorageColumn>;
+    ifNotExists: string[];
+  }): Promise<void> {
+    const parsedTableName = parseSqlIdentifier(tableName, 'table name');
+
+    try {
+      // 1. Get existing columns using PRAGMA
+      const pragmaQuery = `PRAGMA table_info(${parsedTableName})`;
+      const result = await this.client.execute(pragmaQuery);
+      const existingColumnNames = new Set(result.rows.map((row: any) => row.name.toLowerCase()));
+
+      // 2. Add missing columns
+      for (const columnName of ifNotExists) {
+        if (!existingColumnNames.has(columnName.toLowerCase()) && schema[columnName]) {
+          const columnDef = schema[columnName];
+          const sqlType = this.getSqlType(columnDef.type); // ensure this exists or implement
+          const nullable = columnDef.nullable === false ? 'NOT NULL' : '';
+          // In SQLite, you must provide a DEFAULT if adding a NOT NULL column to a non-empty table
+          const defaultValue = columnDef.nullable === false ? this.getDefaultValue(columnDef.type) : '';
+          const alterSql =
+            `ALTER TABLE ${parsedTableName} ADD COLUMN "${columnName}" ${sqlType} ${nullable} ${defaultValue}`.trim();
+
+          await this.client.execute(alterSql);
+          this.logger?.debug?.(`Added column ${columnName} to table ${parsedTableName}`);
+        }
+      }
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_ALTER_TABLE_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+          },
+        },
+        error,
+      );
+    }
+  }
+
+  async clearTable({ tableName }: { tableName: TABLE_NAMES }): Promise<void> {
+    const parsedTableName = parseSqlIdentifier(tableName, 'table name');
+    try {
+      await this.client.execute(`DELETE FROM ${parsedTableName}`);
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: 'LIBSQL_STORE_CLEAR_TABLE_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+          },
+        },
+        e,
+      );
+      this.logger?.trackException?.(mastraError);
+      this.logger?.error?.(mastraError.toString());
+    }
+  }
+
+  async dropTable({ tableName }: { tableName: TABLE_NAMES }): Promise<void> {
+    const parsedTableName = parseSqlIdentifier(tableName, 'table name');
+    try {
+      await this.client.execute(`DROP TABLE IF EXISTS ${parsedTableName}`);
+    } catch (e) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_DROP_TABLE_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+          },
+        },
+        e,
+      );
+    }
+  }
+}

package/src/storage/domains/scores/index.ts

@@ -0,0 +1,217 @@
+import type { Client, InValue } from '@libsql/client';
+import { ErrorCategory, ErrorDomain, MastraError } from '@mastra/core/error';
+import type { ScoreRowData } from '@mastra/core/scores';
+import { TABLE_SCORERS, ScoresStorage } from '@mastra/core/storage';
+import type { PaginationInfo, StoragePagination } from '@mastra/core/storage';
+import type { StoreOperationsLibSQL } from '../operations';
+
+export class ScoresLibSQL extends ScoresStorage {
+  private operations: StoreOperationsLibSQL;
+  private client: Client;
+  constructor({ client, operations }: { client: Client; operations: StoreOperationsLibSQL }) {
+    super();
+    this.operations = operations;
+    this.client = client;
+  }
+
+  async getScoresByRunId({
+    runId,
+    pagination,
+  }: {
+    runId: string;
+    pagination: StoragePagination;
+  }): Promise<{ pagination: PaginationInfo; scores: ScoreRowData[] }> {
+    try {
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_SCORERS} WHERE runId = ? ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [runId, pagination.perPage + 1, pagination.page * pagination.perPage],
+      });
+      return {
+        scores: result.rows?.slice(0, pagination.perPage).map(row => this.transformScoreRow(row)) ?? [],
+        pagination: {
+          total: result.rows?.length ?? 0,
+          page: pagination.page,
+          perPage: pagination.perPage,
+          hasMore: result.rows?.length > pagination.perPage,
+        },
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_GET_SCORES_BY_RUN_ID_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+
+  async getScoresByScorerId({
+    scorerId,
+    entityId,
+    entityType,
+    pagination,
+  }: {
+    scorerId: string;
+    entityId?: string;
+    entityType?: string;
+    pagination: StoragePagination;
+  }): Promise<{ pagination: PaginationInfo; scores: ScoreRowData[] }> {
+    try {
+      const conditions: string[] = [];
+      const queryParams: InValue[] = [];
+
+      if (scorerId) {
+        conditions.push(`scorerId = ?`);
+        queryParams.push(scorerId);
+      }
+
+      if (entityId) {
+        conditions.push(`entityId = ?`);
+        queryParams.push(entityId);
+      }
+
+      if (entityType) {
+        conditions.push(`entityType = ?`);
+        queryParams.push(entityType);
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_SCORERS} ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [...queryParams, pagination.perPage + 1, pagination.page * pagination.perPage],
+      });
+
+      return {
+        scores: result.rows?.slice(0, pagination.perPage).map(row => this.transformScoreRow(row)) ?? [],
+        pagination: {
+          total: result.rows?.length ?? 0,
+          page: pagination.page,
+          perPage: pagination.perPage,
+          hasMore: result.rows?.length > pagination.perPage,
+        },
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_GET_SCORES_BY_SCORER_ID_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+
+  private transformScoreRow(row: Record<string, any>): ScoreRowData {
+    const scorerValue = JSON.parse(row.scorer ?? '{}');
+    const inputValue = JSON.parse(row.input ?? '{}');
+    const outputValue = JSON.parse(row.output ?? '{}');
+    const additionalLLMContextValue = row.additionalLLMContext ? JSON.parse(row.additionalLLMContext) : null;
+    const runtimeContextValue = row.runtimeContext ? JSON.parse(row.runtimeContext) : null;
+    const metadataValue = row.metadata ? JSON.parse(row.metadata) : null;
+    const entityValue = row.entity ? JSON.parse(row.entity) : null;
+    const extractStepResultValue = row.extractStepResult ? JSON.parse(row.extractStepResult) : null;
+    const analyzeStepResultValue = row.analyzeStepResult ? JSON.parse(row.analyzeStepResult) : null;
+
+    return {
+      id: row.id,
+      traceId: row.traceId,
+      runId: row.runId,
+      scorer: scorerValue,
+      score: row.score,
+      reason: row.reason,
+      extractStepResult: extractStepResultValue,
+      analyzeStepResult: analyzeStepResultValue,
+      analyzePrompt: row.analyzePrompt,
+      extractPrompt: row.extractPrompt,
+      metadata: metadataValue,
+      input: inputValue,
+      output: outputValue,
+      additionalContext: additionalLLMContextValue,
+      runtimeContext: runtimeContextValue,
+      entityType: row.entityType,
+      entity: entityValue,
+      entityId: row.entityId,
+      scorerId: row.scorerId,
+      source: row.source,
+      resourceId: row.resourceId,
+      threadId: row.threadId,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+
+  async getScoreById({ id }: { id: string }): Promise<ScoreRowData | null> {
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${TABLE_SCORERS} WHERE id = ?`,
+      args: [id],
+    });
+    return result.rows?.[0] ? this.transformScoreRow(result.rows[0]) : null;
+  }
+
+  async saveScore(score: Omit<ScoreRowData, 'id' | 'createdAt' | 'updatedAt'>): Promise<{ score: ScoreRowData }> {
+    try {
+      const id = crypto.randomUUID();
+
+      await this.operations.insert({
+        tableName: TABLE_SCORERS,
+        record: {
+          id,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+          ...score,
+        },
+      });
+
+      const scoreFromDb = await this.getScoreById({ id });
+      return { score: scoreFromDb! };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_SAVE_SCORE_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+
+  async getScoresByEntityId({
+    entityId,
+    entityType,
+    pagination,
+  }: {
+    pagination: StoragePagination;
+    entityId: string;
+    entityType: string;
+  }): Promise<{ pagination: PaginationInfo; scores: ScoreRowData[] }> {
+    try {
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_SCORERS} WHERE entityId = ? AND entityType = ? ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [entityId, entityType, pagination.perPage + 1, pagination.page * pagination.perPage],
+      });
+      return {
+        scores: result.rows?.slice(0, pagination.perPage).map(row => this.transformScoreRow(row)) ?? [],
+        pagination: {
+          total: result.rows?.length ?? 0,
+          page: pagination.page,
+          perPage: pagination.perPage,
+          hasMore: result.rows?.length > pagination.perPage,
+        },
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_GET_SCORES_BY_ENTITY_ID_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+}

package/src/storage/domains/traces/index.ts

@@ -0,0 +1,150 @@
+import type { Client, InValue } from '@libsql/client';
+import { ErrorCategory, ErrorDomain, MastraError } from '@mastra/core/error';
+import { TABLE_TRACES, TracesStorage, safelyParseJSON } from '@mastra/core/storage';
+import type { StorageGetTracesArg, StorageGetTracesPaginatedArg, PaginationInfo } from '@mastra/core/storage';
+import type { Trace } from '@mastra/core/telemetry';
+import { parseSqlIdentifier } from '@mastra/core/utils';
+import type { StoreOperationsLibSQL } from '../operations';
+
+export class TracesLibSQL extends TracesStorage {
+  private client: Client;
+  private operations: StoreOperationsLibSQL;
+
+  constructor({ client, operations }: { client: Client; operations: StoreOperationsLibSQL }) {
+    super();
+    this.client = client;
+    this.operations = operations;
+  }
+
+  async getTraces(args: StorageGetTracesArg): Promise<Trace[]> {
+    if (args.fromDate || args.toDate) {
+      (args as any).dateRange = {
+        start: args.fromDate,
+        end: args.toDate,
+      };
+    }
+    try {
+      const result = await this.getTracesPaginated(args);
+      return result.traces;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_GET_TRACES_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+
+  async getTracesPaginated(args: StorageGetTracesPaginatedArg): Promise<PaginationInfo & { traces: Trace[] }> {
+    const { name, scope, page = 0, perPage = 100, attributes, filters, dateRange } = args;
+    const fromDate = dateRange?.start;
+    const toDate = dateRange?.end;
+    const currentOffset = page * perPage;
+
+    const queryArgs: InValue[] = [];
+    const conditions: string[] = [];
+
+    if (name) {
+      conditions.push('name LIKE ?');
+      queryArgs.push(`${name}%`);
+    }
+    if (scope) {
+      conditions.push('scope = ?');
+      queryArgs.push(scope);
+    }
+    if (attributes) {
+      Object.entries(attributes).forEach(([key, value]) => {
+        conditions.push(`json_extract(attributes, '$.${key}') = ?`);
+        queryArgs.push(value);
+      });
+    }
+    if (filters) {
+      Object.entries(filters).forEach(([key, value]) => {
+        conditions.push(`${parseSqlIdentifier(key, 'filter key')} = ?`);
+        queryArgs.push(value);
+      });
+    }
+    if (fromDate) {
+      conditions.push('createdAt >= ?');
+      queryArgs.push(fromDate.toISOString());
+    }
+    if (toDate) {
+      conditions.push('createdAt <= ?');
+      queryArgs.push(toDate.toISOString());
+    }
+
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+    try {
+      const countResult = await this.client.execute({
+        sql: `SELECT COUNT(*) as count FROM ${TABLE_TRACES} ${whereClause}`,
+        args: queryArgs,
+      });
+      const total = Number(countResult.rows?.[0]?.count ?? 0);
+
+      if (total === 0) {
+        return {
+          traces: [],
+          total: 0,
+          page,
+          perPage,
+          hasMore: false,
+        };
+      }
+
+      const dataResult = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_TRACES} ${whereClause} ORDER BY "startTime" DESC LIMIT ? OFFSET ?`,
+        args: [...queryArgs, perPage, currentOffset],
+      });
+
+      const traces =
+        dataResult.rows?.map(
+          row =>
+            ({
+              id: row.id,
+              parentSpanId: row.parentSpanId,
+              traceId: row.traceId,
+              name: row.name,
+              scope: row.scope,
+              kind: row.kind,
+              status: safelyParseJSON(row.status as string),
+              events: safelyParseJSON(row.events as string),
+              links: safelyParseJSON(row.links as string),
+              attributes: safelyParseJSON(row.attributes as string),
+              startTime: row.startTime,
+              endTime: row.endTime,
+              other: safelyParseJSON(row.other as string),
+              createdAt: row.createdAt,
+            }) as Trace,
+        ) ?? [];
+
+      return {
+        traces,
+        total,
+        page,
+        perPage,
+        hasMore: currentOffset + traces.length < total,
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_STORE_GET_TRACES_PAGINATED_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
+  }
+
+  async batchTraceInsert({ records }: { records: Record<string, any>[] }): Promise<void> {
+    this.logger.debug('Batch inserting traces', { count: records.length });
+    await this.operations.batchInsert({
+      tableName: TABLE_TRACES,
+      records,
+    });
+  }
+}