@mastra/libsql 1.22.3-alpha.1 → 1.22.3-alpha.3

package/README.md

@@ -16,27 +16,30 @@ npm install @mastra/libsql
 import { LibSQLVector } from '@mastra/libsql';
 
 const vectorStore = new LibSQLVector({
-  url: 'file:./my-db.db'
+  url: 'file:./my-db.db',
 });
 
 // Create a new table with vector support
 await vectorStore.createIndex({
   indexName: 'my_vectors',
-  dimension: 1536,
+  dimension: 3,
   metric: 'cosine',
 });
 
 // Add vectors
 const ids = await vectorStore.upsert({
   indexName: 'my_vectors',
-  vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
+  vectors: [
+    [0.1, 0.2, 0.3],
+    [0.3, 0.4, 0.5],
+  ],
   metadata: [{ text: 'doc1' }, { text: 'doc2' }],
 });
 
 // Query vectors
 const results = await vectorStore.query({
   indexName: 'my_vectors',
-  queryVector: [0.1, 0.2, ...],
+  queryVector: [0.1, 0.2, 0.3],
   topK: 10, // topK
   filter: { text: 'doc1' }, // filter
   includeVector: false, // includeVector
@@ -44,111 +47,14 @@ const results = await vectorStore.query({
 });
 ```
 
-### Storage
-
-```typescript
-import { LibSQLStore } from '@mastra/libsql';
-
-const store = new LibSQLStore({
-  id: 'libsql-storage',
-  url: 'file:./my-db.db',
-});
-
-// Create a thread
-await store.saveThread({
-  thread: {
-    id: 'thread-123',
-    resourceId: 'resource-456',
-    title: 'My Thread',
-    metadata: { key: 'value' },
-    createdAt: new Date(),
-  },
-});
-
-// Add messages to thread
-await store.saveMessages({
-  messages: [
-    {
-      id: 'msg-789',
-      threadId: 'thread-123',
-      role: 'user',
-      content: { content: 'Hello' },
-      resourceId: 'resource-456',
-      createdAt: new Date(),
-    },
-  ],
-});
-
-// Query threads and messages
-const savedThread = await store.getThreadById({ threadId: 'thread-123' });
-const messages = await store.listMessages({ threadId: 'thread-123' });
-```
-
-## Configuration
-
-The LibSQLStore store can be initialized with:
-
-- Configuration object with url and auth. Auth is only necessary when using a provider like [Turso](https://turso.tech/)
-
-## Features
-
-### Vector Store Features
-
-- Vector similarity search with cosine, euclidean, and dot product metrics
-- Advanced metadata filtering with MongoDB-like query syntax
-- Minimum score threshold for queries
-- Automatic UUID generation for vectors
-- Table management (create, list, describe, delete, truncate)
-
-### Storage Features
-
-- Thread and message storage with JSON support
-- Atomic transactions for data consistency
-- Efficient batch operations
-- Rich metadata support
-- Timestamp tracking
-- Cascading deletes
-
-## Supported Filter Operators
-
-The following filter operators are supported for metadata queries:
-
-- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
-- Logical: `$and`, `$or`
-- Array: `$in`, `$nin`
-- Text: `$regex`, `$like`
-
-Example filter:
-
-```typescript
-{
-  $and: [{ age: { $gt: 25 } }, { tags: { $in: ['tag1', 'tag2'] } }];
-}
-```
-
-## Vector Store Methods
+## Documentation
 
-- `createIndex({indexName, dimension, metric?, indexConfig?, defineIndex?})`: Create a new table with vector support
-- `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
-- `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
-- `updateVector({ indexName, id?, filter?, update })`: Update a single vector by ID or metadata filter
-- `deleteVector({ indexName, id })`: Delete a single vector by ID
-- `deleteVectors({ indexName, ids?, filter? })`: Delete multiple vectors by IDs or metadata filter
-- `defineIndex({indexName, metric?, indexConfig?})`: Define an index
-- `listIndexes()`: List all vector-enabled tables
-- `describeIndex(indexName)`: Get table statistics
-- `deleteIndex(indexName)`: Delete a table
-- `truncateIndex(indexName)`: Remove all data from a table
+- [@mastra/libsql documentation](https://mastra.ai/reference/vectors/libsql)
 
-## Storage Methods
+## Changelog
 
-- `saveThread({ thread })`: Create or update a thread
-- `getThreadById({ threadId })`: Get a thread by ID
-- `deleteThread({ threadId })`: Delete a thread and its messages
-- `saveMessages({ messages })`: Save multiple messages in a transaction
-- `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
-- `deleteMessages(messageIds)`: Delete specific messages
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/stores/libsql/CHANGELOG.md) for version history and release notes.
 
-## Related Links
+## Support
 
-- [LibSQL Documentation](https://docs.turso.tech/sdk/introductionh)
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.22.3-alpha.1"
+  version: "1.22.3-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.3-alpha.1",
+  "version": "1.22.3-alpha.3",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-studio-editor.md

@@ -316,7 +316,7 @@ See the [Editor versioning reference](https://mastra.ai/reference/editor/version
 
 ## Programmatic access
 
-Everything available in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor), the REST API, or the Client SDK. Use it to script bulk updates or seed stored configurations from code. It can also power automation that tunes agents based on [evaluation results](https://mastra.ai/docs/datasets/running-experiments).
+Everything available in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor), the REST API, or the Client SDK. Use it to script bulk updates or seed stored configurations from code. It can also power automation that tunes agents based on [evaluation results](https://mastra.ai/docs/evals/experiments).
 
 Call `mastra.getEditor()` when application code has access to the Mastra instance:
 

package/dist/index.cjs

@@ -5,6 +5,8 @@ let _mastra_core_storage = require("@mastra/core/storage");
 let _mastra_core_utils = require("@mastra/core/utils");
 let _mastra_core_vector = require("@mastra/core/vector");
 let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
+let fs_promises = require("fs/promises");
+let path = require("path");
 let _mastra_core_base = require("@mastra/core/base");
 let crypto$1 = require("crypto");
 let _mastra_core_agent = require("@mastra/core/agent");
@@ -237,13 +239,13 @@ const FILTER_OPERATORS = {
 		sql: `NOT (${key})`,
 		needsValue: false
 	}),
-	$size: (key, paramIndex) => {
+	$size: (key, value) => {
 		const jsonPath = getJsonPath(key);
 		return {
 			sql: `(
     CASE
-      WHEN json_type(json_extract(metadata, ${jsonPath})) = 'array' THEN 
-        json_array_length(json_extract(metadata, ${jsonPath})) = $${paramIndex}
+      WHEN json_type(json_extract(metadata, ${jsonPath})) = 'array' THEN
+        json_array_length(json_extract(metadata, ${jsonPath})) = ?
       ELSE FALSE
     END
   )`,
@@ -385,6 +387,31 @@ const processOperator = (key, operator, operatorValue) => {
 	};
 };
 //#endregion
+//#region src/vector/write-lock.ts
+const databaseWriteChains = /* @__PURE__ */ new Map();
+async function getLocalFileDatabaseKey({ url, syncUrl, cwd }) {
+	if (!url.startsWith("file:") || url.includes(":memory:") || syncUrl) return;
+	const uriPath = url.slice(5).split(/[?#]/, 1)[0];
+	const decodedPath = decodeURIComponent(uriPath);
+	const absolutePath = (0, path.isAbsolute)(decodedPath) ? decodedPath : (0, path.resolve)(cwd, decodedPath);
+	try {
+		return await (0, fs_promises.realpath)(absolutePath);
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+	}
+	return (0, path.join)(await (0, fs_promises.realpath)((0, path.dirname)(absolutePath)), (0, path.basename)(absolutePath));
+}
+function withLocalFileDatabaseWriteLock(key, fn) {
+	if (!key) return fn();
+	const result = (databaseWriteChains.get(key) ?? Promise.resolve()).then(fn, fn);
+	const tail = result.then(() => void 0, () => void 0);
+	databaseWriteChains.set(key, tail);
+	tail.then(() => {
+		if (databaseWriteChains.get(key) === tail) databaseWriteChains.delete(key);
+	});
+	return result;
+}
+//#endregion
 //#region src/vector/index.ts
 var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	turso;
@@ -392,25 +419,57 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	initialBackoffMs;
 	overFetchMultiplier;
 	isMemoryDb;
-	vectorIndexes;
+	initialization;
+	databaseKey;
+	vectorIndexes = /* @__PURE__ */ new Set();
 	constructor({ url, authToken, syncUrl, syncInterval, maxRetries = 5, initialBackoffMs = 100, vectorTopKOverFetchMultiplier = 10, id }) {
 		super({ id });
+		this.isMemoryDb = url.includes(":memory:");
+		const isLocalDb = (url.startsWith("file:") || this.isMemoryDb) && !syncUrl;
+		const cwd = process.cwd();
 		this.turso = (0, _libsql_client.createClient)({
 			url,
 			syncUrl,
 			authToken,
-			syncInterval
+			syncInterval,
+			...isLocalDb ? { timeout: 5e3 } : {}
 		});
 		this.maxRetries = maxRetries;
 		this.initialBackoffMs = initialBackoffMs;
 		if (!Number.isInteger(vectorTopKOverFetchMultiplier) || vectorTopKOverFetchMultiplier < 1) throw new Error("vectorTopKOverFetchMultiplier must be a positive integer");
 		this.overFetchMultiplier = vectorTopKOverFetchMultiplier;
-		this.isMemoryDb = url.includes(":memory:");
-		if (url.includes(`file:`) || this.isMemoryDb) {
-			this.turso.execute("PRAGMA journal_mode=WAL;").then(() => this.logger.debug("LibSQLStore: PRAGMA journal_mode=WAL set.")).catch((err) => this.logger.warn("LibSQLStore: Failed to set PRAGMA journal_mode=WAL.", err));
-			this.turso.execute("PRAGMA busy_timeout = 5000;").then(() => this.logger.debug("LibSQLStore: PRAGMA busy_timeout=5000 set.")).catch((err) => this.logger.warn("LibSQLStore: Failed to set PRAGMA busy_timeout=5000.", err));
+		this.initialization = this.initialize({
+			url,
+			syncUrl,
+			cwd,
+			isLocalDb
+		});
+	}
+	async initialize({ url, syncUrl, cwd, isLocalDb }) {
+		if (isLocalDb) {
+			await this.applyLocalPragmas();
+			this.databaseKey = await getLocalFileDatabaseKey({
+				url,
+				syncUrl,
+				cwd
+			});
 		}
-		this.vectorIndexes = this.isMemoryDb ? Promise.resolve(/* @__PURE__ */ new Set()) : this.discoverVectorIndexes();
+		if (!this.isMemoryDb) this.vectorIndexes = await this.discoverVectorIndexes();
+	}
+	async applyLocalPragmas() {
+		for (const [label, sql] of [["journal_mode=WAL", "PRAGMA journal_mode=WAL;"], ["busy_timeout=5000", "PRAGMA busy_timeout = 5000;"]]) try {
+			await this.turso.execute(sql);
+			this.logger.debug(`LibSQLStore: PRAGMA ${label} set.`);
+		} catch (err) {
+			this.logger.warn(`LibSQLStore: Failed to set PRAGMA ${label}.`, err);
+		}
+	}
+	async ensureInitialized() {
+		await this.initialization;
+	}
+	async executeMutation(operation, isTransaction = false) {
+		await this.ensureInitialized();
+		return withLocalFileDatabaseWriteLock(this.databaseKey, () => this.executeWriteOperationWithRetry(operation, isTransaction));
 	}
 	/**
 	* Closes the underlying libsql client, releasing this vector store's OS file handles.
@@ -418,6 +477,7 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	* Safe to call more than once; subsequent calls are no-ops.
 	*/
 	async close() {
+		await this.ensureInitialized();
 		if (!this.turso.closed) this.turso.close();
 	}
 	async discoverVectorIndexes() {
@@ -453,8 +513,8 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	transformFilter(filter) {
 		return new LibSQLFilterTranslator().translate(filter);
 	}
-	async hasVectorIndex(parsedIndexName) {
-		return (await this.vectorIndexes).has(`${parsedIndexName}_vector_idx`);
+	hasVectorIndex(parsedIndexName) {
+		return this.vectorIndexes.has(`${parsedIndexName}_vector_idx`);
 	}
 	async queryWithIndex(parsedIndexName, vectorStr, topK, filter, includeVector, minScore) {
 		const { sql: filterQuery, values: filterValues } = buildFilterQuery(this.transformFilter(filter));
@@ -509,9 +569,10 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 			details: { message: "queryVector must be an array of finite numbers" }
 		});
 		try {
+			await this.ensureInitialized();
 			const parsedIndexName = (0, _mastra_core_utils.parseSqlIdentifier)(indexName, "index name");
 			const vectorStr = `[${queryVector.join(",")}]`;
-			if (!this.isMemoryDb && await this.hasVectorIndex(parsedIndexName)) try {
+			if (!this.isMemoryDb && this.hasVectorIndex(parsedIndexName)) try {
 				const indexedResults = await this.queryWithIndex(parsedIndexName, vectorStr, topK, filter, includeVector, minScore);
 				if (!filter || indexedResults.length >= topK) return indexedResults;
 			} catch (err) {
@@ -552,9 +613,9 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 			}, error);
 		}
 	}
-	upsert(args) {
+	async upsert(args) {
 		try {
-			return this.executeWriteOperationWithRetry(() => this.doUpsert(args), true);
+			return await this.executeMutation(() => this.doUpsert(args), true);
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("LIBSQL", "UPSERT", "FAILED"),
@@ -602,9 +663,9 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 			throw error;
 		}
 	}
-	createIndex(args) {
+	async createIndex(args) {
 		try {
-			return this.executeWriteOperationWithRetry(() => this.doCreateIndex(args));
+			return await this.executeMutation(() => this.doCreateIndex(args));
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("LIBSQL", "CREATE_INDEX", "FAILED"),
@@ -638,11 +699,11 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
         `,
 			args: []
 		});
-		this.vectorIndexes.then((indexes) => indexes.add(`${parsedIndexName}_vector_idx`));
+		this.vectorIndexes.add(`${parsedIndexName}_vector_idx`);
 	}
-	deleteIndex(args) {
+	async deleteIndex(args) {
 		try {
-			return this.executeWriteOperationWithRetry(() => this.doDeleteIndex(args));
+			return await this.executeMutation(() => this.doDeleteIndex(args));
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("LIBSQL", "DELETE_INDEX", "FAILED"),
@@ -658,10 +719,11 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 			sql: `DROP TABLE IF EXISTS ${parsedIndexName}`,
 			args: []
 		});
-		this.vectorIndexes.then((indexes) => indexes.delete(`${parsedIndexName}_vector_idx`));
+		this.vectorIndexes.delete(`${parsedIndexName}_vector_idx`);
 	}
 	async listIndexes() {
 		try {
+			await this.ensureInitialized();
 			return (await this.turso.execute({
 				sql: `
         SELECT name FROM sqlite_master 
@@ -686,6 +748,7 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	*/
 	async describeIndex({ indexName }) {
 		try {
+			await this.ensureInitialized();
 			const parsedIndexName = (0, _mastra_core_utils.parseSqlIdentifier)(indexName, "index name");
 			const tableInfo = await this.turso.execute({
 				sql: `
@@ -731,7 +794,7 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	* @throws Will throw an error if no updates are provided or if the update operation fails.
 	*/
 	updateVector(args) {
-		return this.executeWriteOperationWithRetry(() => this.doUpdateVector(args));
+		return this.executeMutation(() => this.doUpdateVector(args));
 	}
 	async doUpdateVector(params) {
 		const { indexName, update } = params;
@@ -836,9 +899,9 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 	* @returns A promise that resolves when the deletion is complete.
 	* @throws Will throw an error if the deletion operation fails.
 	*/
-	deleteVector(args) {
+	async deleteVector(args) {
 		try {
-			return this.executeWriteOperationWithRetry(() => this.doDeleteVector(args));
+			return await this.executeMutation(() => this.doDeleteVector(args));
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("LIBSQL", "DELETE_VECTOR", "FAILED"),
@@ -859,7 +922,7 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 		});
 	}
 	deleteVectors(args) {
-		return this.executeWriteOperationWithRetry(() => this.doDeleteVectors(args));
+		return this.executeMutation(() => this.doDeleteVectors(args));
 	}
 	async doDeleteVectors({ indexName, filter, ids }) {
 		const parsedIndexName = (0, _mastra_core_utils.parseSqlIdentifier)(indexName, "index name");
@@ -941,9 +1004,9 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 			}, error);
 		}
 	}
-	truncateIndex(args) {
+	async truncateIndex(args) {
 		try {
-			return this.executeWriteOperationWithRetry(() => this._doTruncateIndex(args));
+			return await this.executeMutation(() => this._doTruncateIndex(args));
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("LIBSQL", "TRUNCATE_INDEX", "FAILED"),
@@ -2499,6 +2562,26 @@ var AgentsLibSQL = class extends _mastra_core_storage.AgentsStorage {
 			}, error);
 		}
 	}
+	async getVersions(ids) {
+		if (ids.length === 0) return [];
+		try {
+			return (await this.#db.selectMany({
+				tableName: _mastra_core_storage.TABLE_AGENT_VERSIONS,
+				whereClause: {
+					sql: `WHERE id IN (${ids.map(() => "?").join(", ")})`,
+					args: ids
+				}
+			}) ?? []).map((row) => this.parseVersionRow(row));
+		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "GET_VERSIONS", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { count: ids.length }
+			}, error);
+		}
+	}
 	async getVersionByNumber(agentId, versionNumber) {
 		try {
 			const rows = await this.#db.selectMany({
@@ -12242,6 +12325,24 @@ var SkillsLibSQL = class extends _mastra_core_storage.SkillsStorage {
 			}, error);
 		}
 	}
+	async getVersions(ids) {
+		if (ids.length === 0) return [];
+		try {
+			const placeholders = ids.map(() => "?").join(", ");
+			return ((await this.#client.execute({
+				sql: `SELECT ${buildSelectColumns(_mastra_core_storage.TABLE_SKILL_VERSIONS)} FROM "${_mastra_core_storage.TABLE_SKILL_VERSIONS}" WHERE id IN (${placeholders})`,
+				args: ids
+			})).rows ?? []).map((row) => this.#parseVersionRow(row));
+		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "GET_SKILL_VERSIONS", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { count: ids.length }
+			}, error);
+		}
+	}
 	async getVersionByNumber(skillId, versionNumber) {
 		try {
 			const row = (await this.#client.execute({