Git Versioned SQLite VFS

Common errors

• Error: VFS extension not loaded

  cause Attempting to use `git-sqlite-vfs` functionality in Deno without correctly loading the native VFS extension, often due to importing the browser-compatible `@libsql/client`.
  fix Use `createVFSClient` from `git-sqlite-vfs` or explicitly import the Node-specific `@libsql/client/node` binding in Deno: `import { createClient } from 'npm:@libsql/client@<version>/node';`

• Database file size not shrinking; unused '.bin' files accumulating in VFS directory.

  cause The SQLite database is not configured for full auto-vacuuming or delete journaling, preventing the VFS from actively removing unused data shards.
  fix Ensure `PRAGMA auto_vacuum = FULL;` and `PRAGMA journal_mode = DELETE;` are executed upon database connection. Alternatively, run `VACUUM;` periodically to compact the database and allow the VFS to remove out-of-bounds shards.

• Drizzle migrations/schema push not reflecting changes in VFS-enabled database.

  cause Using `drizzle-kit` commands directly instead of the `git-sqlite-vfs` CLI wrappers, which bypasses the VFS integration.
  fix Always use the `git-sqlite-vfs` CLI for schema management: `npx git-sqlite-vfs generate`, `npx git-sqlite-vfs push`, and `npx git-sqlite-vfs migrate`.

Warnings

• breaking The `git-sqlite-vfs` CLI commands (`setup`, `generate`, `push`, `migrate`) are designed to replace their `drizzle-kit` counterparts when working with a VFS-enabled database. Using raw `drizzle-kit` commands directly will not correctly interact with the sharded VFS database and can lead to inconsistencies or lost changes.
  Fix: Always use `npx git-sqlite-vfs <command>` for schema management and migrations when working with a VFS-enabled database.
• gotcha When using `git-sqlite-vfs` in Deno, importing `@libsql/client` directly (e.g., `import { createClient } from 'npm:@libsql/client';`) will resolve to the browser-compatible implementation, which bypasses the native C extension required for the VFS. This will prevent the VFS from functioning.
  Fix: Use the `createVFSClient` helper function provided by `git-sqlite-vfs`, which automatically handles the correct Node environment binding. If bypassing `createVFSClient`, import directly from the Node environment: `import { createClient } from 'npm:@libsql/client@<version>/node';`.
• gotcha For efficient database compaction and removal of unused VFS `.bin` shards (e.g., after deletes), SQLite requires `PRAGMA auto_vacuum = FULL;` and `PRAGMA journal_mode = DELETE;`. While `createVFSClient()` automatically sets these upon connection, manual client initialization requires you to run these PRAGMAs explicitly.
  Fix: Ensure `PRAGMA auto_vacuum = FULL;` and `PRAGMA journal_mode = DELETE;` are executed on your database connection, or periodically run `VACUUM;` to trigger compaction and shard removal.
• gotcha Node.js compatibility notes: The package leverages Node.js v22.5+ for the internal `node:sqlite` API. For older Node.js versions, it will fall back to using `better-sqlite3`. While generally transparent, this might have implications for performance or specific platform environments.
  Fix: For optimal and consistent behavior, consider using Node.js v22.5 or newer. If using older versions, ensure `better-sqlite3` is compatible with your environment.

Install

• npm install git-sqlite-vfs npm
• yarn add git-sqlite-vfs yarn
• pnpm add git-sqlite-vfs pnpm

Imports

• createVFSClient
  wrong:

  const { createVFSClient } = require('git-sqlite-vfs');

  correct:

  import { createVFSClient } from 'git-sqlite-vfs';

  The package primarily targets ESM environments. CommonJS require() may lack type safety or lead to issues in some bundlers.
• drizzle

  import { drizzle } from 'drizzle-orm/libsql';

  Used for integrating the VFS-enabled client with Drizzle ORM. This is a standard Drizzle import.
• createClient
  wrong:

  import { createClient } from 'npm:@libsql/client';

  correct:

  import { createClient } from 'npm:@libsql/client@0.14.0/node';

  When using Deno, directly importing from `npm:@libsql/client` defaults to a browser-compatible implementation that bypasses native VFS extensions. The `/node` subpath is required for VFS functionality in Deno.

Quickstart

Demonstrates initializing a VFS-enabled libSQL client, integrating it with Drizzle ORM, and performing basic database operations. It also highlights the automatic configuration for database compaction.

import { createVFSClient } from 'git-sqlite-vfs';
import { drizzle } from 'drizzle-orm/libsql';
import { sql } from 'drizzle-orm';

const run = async () => {
  // Initialize the VFS-enabled client, automatically loading the VFS extension
  // and configuring PRAGMAs for compaction.
  const client = await createVFSClient({
      url: 'file:.db/main.db' // Database path within the VFS sharded directory
  });

  // Integrate the VFS client with Drizzle ORM
  const db = drizzle(client);

  // Example: Create a table and insert data using Drizzle
  await db.execute(sql`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);`);
  await db.execute(sql`INSERT INTO users (name) VALUES ('Alice'), ('Bob');`);
  const result = await db.execute(sql`SELECT * FROM users;`);
  console.log('Users:', result);

  // To ensure VFS shards are compacted, trigger a VACUUM periodically
  // or rely on auto_vacuum=FULL; and journal_mode=DELETE; which createVFSClient sets.
  // await db.execute(sql`VACUUM;`);

  await client.close();
};

run().catch(console.error);