fix(libsql): add public close() to LibSQLStore and wire into Mastra.shutdown() (#17306)

Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: 3 people

.changeset/libsql-store-close-windows-ebusy.md

@@ -0,0 +1,15 @@
+---
+"@mastra/libsql": patch
+---
+
+Added a public `close()` method to `LibSQLStore` that releases SQLite file handles and cleans up the WAL/shm sidecar files. Previously these handles stayed open until the process exited, which on Windows caused `EBUSY` errors when removing the storage directory after shutdown. `Mastra.shutdown()` now calls `close()` automatically, so you no longer need to reach into private fields.
+
+```typescript
+const storage = new LibSQLStore({ id: 'my-store', url: 'file:./dev.db' });
+
+// Release all file handles, including WAL/shm sidecar files
+await storage.close();
+
+// Now safe to remove the storage directory on all platforms, including Windows
+await fs.rm('./dev.db', { recursive: true, force: true });
+```

.changeset/mastra-shutdown-closes-storage.md

@@ -0,0 +1,12 @@
+---
+"@mastra/core": patch
+---
+
+`Mastra.shutdown()` now releases storage resources automatically. Stores that expose a `close()` lifecycle hook (such as `LibSQLStore`) are closed during shutdown, so file handles are freed and the storage directory can be removed cleanly afterward, including on Windows.
+
+```typescript
+const mastra = new Mastra({ storage });
+
+// Storage is closed for you — no manual cleanup needed
+await mastra.shutdown();
+```

packages/core/src/mastra/index.ts

@@ -4294,6 +4294,11 @@ export class Mastra<
   async shutdown(): Promise<void> {
     // SchedulerWorker is stopped as part of stopWorkers().
     await this.stopWorkers();
+    // Close storage to release OS file handles (critical on Windows: open WAL/shm
+    // handles cause EBUSY when callers try to fs.rm the storage dir after shutdown).
+    if (this.#storage?.close) {
+      await this.#storage.close();
+    }
     // Shutdown observability registry, exporters, etc...
     await this.#observability.shutdown();
 

packages/core/src/storage/base.ts

@@ -460,6 +460,13 @@ export class MastraCompositeStore extends MastraBase {
     await Promise.all(initTasks);
     return true;
   }
+  /**
+   * Optional lifecycle hook: release underlying client/connection handles.
+   * Implementations (e.g. LibSQLStore) override this to checkpoint WAL files
+   * and close the database client so OS handles are freed synchronously.
+   * Called automatically by Mastra.shutdown().
+   */
+  close?(): Promise<void>;
 }
 
 /**

stores/libsql/src/storage/close.test.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createClient } from '@libsql/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LibSQLStore } from './index';
+
+type TestClient = ReturnType<typeof createClient>;
+
+const getClient = (store: LibSQLStore): TestClient => (store as unknown as { client: TestClient }).client;
+
+const executedSqlFrom = (spy: ReturnType<typeof vi.spyOn>): string[] =>
+  (spy.mock.calls as unknown as unknown[][]).map(call => {
+    const arg = call[0];
+    return typeof arg === 'string' ? arg : (arg as { sql: string }).sql;
+  });
+
+describe('LibSQLStore.close()', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'libsql-close-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('checkpoints/truncates the WAL and closes the client for local file DBs', async () => {
+    const dbPath = path.join(tmpDir, 'mastra.db');
+    const store = new LibSQLStore({ id: 'close-local', url: `file:${dbPath}` });
+    await store.init();
+
+    const client = getClient(store);
+    const executeSpy = vi.spyOn(client, 'execute');
+    const closeSpy = vi.spyOn(client, 'close');
+
+    await store.close();
+
+    const executedSql = executedSqlFrom(executeSpy);
+    expect(executedSql).toContain('PRAGMA wal_checkpoint(TRUNCATE);');
+    expect(executedSql).toContain('PRAGMA journal_mode=DELETE;');
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+    expect(client.closed).toBe(true);
+  });
+
+  it('is idempotent — a second close() is a no-op', async () => {
+    const dbPath = path.join(tmpDir, 'mastra.db');
+    const store = new LibSQLStore({ id: 'close-idempotent', url: `file:${dbPath}` });
+    await store.init();
+
+    const client = getClient(store);
+
+    await store.close();
+
+    const executeSpy = vi.spyOn(client, 'execute');
+    const closeSpy = vi.spyOn(client, 'close');
+
+    await expect(store.close()).resolves.toBeUndefined();
+
+    expect(executeSpy).not.toHaveBeenCalled();
+    expect(closeSpy).not.toHaveBeenCalled();
+  });
+
+  it('runs WAL cleanup for an injected client that points at a local file', async () => {
+    const dbPath = path.join(tmpDir, 'injected.db');
+    const client = createClient({ url: `file:${dbPath}` });
+    const store = new LibSQLStore({ id: 'close-injected-local', client });
+    await store.init();
+
+    expect(client.protocol).toBe('file');
+
+    const executeSpy = vi.spyOn(client, 'execute');
+    const closeSpy = vi.spyOn(client, 'close');
+
+    await store.close();
+
+    expect(executedSqlFrom(executeSpy)).toContain('PRAGMA wal_checkpoint(TRUNCATE);');
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips WAL pragmas for non-file (remote) clients', async () => {
+    const client = createClient({ url: `file:${path.join(tmpDir, 'remote.db')}` });
+    // Pretend this is a remote connection without touching the underlying file logic.
+    Object.defineProperty(client, 'protocol', { value: 'https', configurable: true });
+
+    const store = new LibSQLStore({ id: 'close-remote', client });
+    await store.init();
+
+    const executeSpy = vi.spyOn(client, 'execute');
+    const closeSpy = vi.spyOn(client, 'close');
+
+    await store.close();
+
+    const executedSql = executedSqlFrom(executeSpy);
+    expect(executedSql).not.toContain('PRAGMA wal_checkpoint(TRUNCATE);');
+    expect(executedSql).not.toContain('PRAGMA journal_mode=DELETE;');
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('still closes the client and warns when WAL checkpoint fails', async () => {
+    const dbPath = path.join(tmpDir, 'wal-fail.db');
+    const store = new LibSQLStore({ id: 'close-wal-fail', url: `file:${dbPath}` });
+    await store.init();
+
+    const client = getClient(store);
+    vi.spyOn(client, 'execute').mockRejectedValue(new Error('boom'));
+    const closeSpy = vi.spyOn(client, 'close');
+    const warnSpy = vi.spyOn((store as unknown as { logger: { warn: (...args: unknown[]) => void } }).logger, 'warn');
+
+    await expect(store.close()).resolves.toBeUndefined();
+
+    expect(warnSpy).toHaveBeenCalled();
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes WAL sidecar files so the storage dir can be deleted', async () => {
+    const dbPath = path.join(tmpDir, 'sidecars.db');
+    const store = new LibSQLStore({ id: 'close-sidecars', url: `file:${dbPath}` });
+    await store.init();
+
+    // Force some writes so the WAL sidecar files exist.
+    const client = getClient(store);
+    await client.execute('CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY);');
+    await client.execute('INSERT INTO t (id) VALUES (1);');
+
+    await store.close();
+
+    expect(fs.existsSync(`${dbPath}-wal`)).toBe(false);
+    expect(fs.existsSync(`${dbPath}-shm`)).toBe(false);
+  });
+});

stores/libsql/src/storage/index.ts

@@ -296,6 +296,41 @@ export class LibSQLStore extends MastraCompositeStore {
 
     await this.initDomainsSequentially();
   }
+
+  /**
+   * Closes the underlying libsql client, releasing all OS file handles.
+   *
+   * For local file databases, first runs PRAGMA wal_checkpoint(TRUNCATE) and
+   * switches back to journal_mode=DELETE so that Windows releases the -wal
+   * and -shm sidecar files promptly. Without this, the handles stay open
+   * until process exit, causing EBUSY errors when callers try to fs.rm the
+   * storage directory after Mastra.shutdown().
+   *
+   * Remote (Turso) databases skip the WAL pragmas and just close the client.
+   *
+   * Safe to call more than once; subsequent calls are no-ops.
+   */
+  async close(): Promise<void> {
+    if (this.client.closed) {
+      return;
+    }
+
+    // A store built from an injected client may still point at a local file even
+    // though `isLocalDb` (derived from the url config) is false, so also trust the
+    // client's own protocol to decide whether WAL cleanup is needed.
+    const isLocalFileDb = this.isLocalDb || this.client.protocol === 'file';
+
+    if (isLocalFileDb) {
+      try {
+        await this.client.execute('PRAGMA wal_checkpoint(TRUNCATE);');
+        await this.client.execute('PRAGMA journal_mode=DELETE;');
+      } catch (err) {
+        this.logger.warn('LibSQLStore: Failed to checkpoint WAL before close.', err);
+      }
+    }
+
+    this.client.close();
+  }
 }
 
 export { LibSQLStore as DefaultStorage };