{"id":16627,"library":"git-sqlite-vfs","title":"Git Versioned SQLite VFS","description":"git-sqlite-vfs (version 0.0.20) provides a unique solution for versioning SQLite databases using Git. It achieves this by implementing a custom Virtual File System (VFS) extension for SQLite, sharding database files into deterministic 4KB binary pages stored in a specified directory (e.g., `.my-db`). This approach resolves the common issue of binary merge conflicts in Git when trying to version a monolithic SQLite database file, enabling effective diffing and merging of database changes. The library integrates seamlessly with popular tools like Drizzle ORM and libSQL clients, and is compatible with both Node.js (v22.5+) and Deno environments. While still in early development, it offers CLI tools to replace standard `drizzle-kit` commands for schema management and migrations within the VFS context, ensuring database changes are correctly applied to the sharded structure. Its primary differentiator is making SQLite a first-class citizen in Git-based version control workflows, enabling collaborative database schema and data evolution.","status":"active","version":"0.0.20","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install git-sqlite-vfs","lang":"bash","label":"npm"},{"cmd":"yarn add git-sqlite-vfs","lang":"bash","label":"yarn"},{"cmd":"pnpm add git-sqlite-vfs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to libSQL/SQLite databases, used by the VFS client.","package":"@libsql/client","optional":false},{"reason":"Peer dependency, potentially for native bindings or alternative client usage alongside @libsql/client.","package":"libsql","optional":true},{"reason":"Peer dependency for schema generation and migration tooling, integrated via git-sqlite-vfs CLI.","package":"drizzle-kit","optional":false},{"reason":"Commonly used for ORM integration with the VFS-enabled database.","package":"drizzle-orm","optional":true}],"imports":[{"note":"The package primarily targets ESM environments. CommonJS require() may lack type safety or lead to issues in some bundlers.","wrong":"const { createVFSClient } = require('git-sqlite-vfs');","symbol":"createVFSClient","correct":"import { createVFSClient } from 'git-sqlite-vfs';"},{"note":"Used for integrating the VFS-enabled client with Drizzle ORM. This is a standard Drizzle import.","symbol":"drizzle","correct":"import { drizzle } from 'drizzle-orm/libsql';"},{"note":"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.","wrong":"import { createClient } from 'npm:@libsql/client';","symbol":"createClient","correct":"import { createClient } from 'npm:@libsql/client@0.14.0/node';"}],"quickstart":{"code":"import { createVFSClient } from 'git-sqlite-vfs';\nimport { drizzle } from 'drizzle-orm/libsql';\nimport { sql } from 'drizzle-orm';\n\nconst run = async () => {\n  // Initialize the VFS-enabled client, automatically loading the VFS extension\n  // and configuring PRAGMAs for compaction.\n  const client = await createVFSClient({\n      url: 'file:.db/main.db' // Database path within the VFS sharded directory\n  });\n\n  // Integrate the VFS client with Drizzle ORM\n  const db = drizzle(client);\n\n  // Example: Create a table and insert data using Drizzle\n  await db.execute(sql`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);`);\n  await db.execute(sql`INSERT INTO users (name) VALUES ('Alice'), ('Bob');`);\n  const result = await db.execute(sql`SELECT * FROM users;`);\n  console.log('Users:', result);\n\n  // To ensure VFS shards are compacted, trigger a VACUUM periodically\n  // or rely on auto_vacuum=FULL; and journal_mode=DELETE; which createVFSClient sets.\n  // await db.execute(sql`VACUUM;`);\n\n  await client.close();\n};\n\nrun().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Always use `npx git-sqlite-vfs <command>` for schema management and migrations when working with a VFS-enabled database.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<22.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`","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`.","error":"Error: VFS extension not loaded"},{"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.","cause":"The SQLite database is not configured for full auto-vacuuming or delete journaling, preventing the VFS from actively removing unused data shards.","error":"Database file size not shrinking; unused '.bin' files accumulating in VFS directory."},{"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`.","cause":"Using `drizzle-kit` commands directly instead of the `git-sqlite-vfs` CLI wrappers, which bypasses the VFS integration.","error":"Drizzle migrations/schema push not reflecting changes in VFS-enabled database."}],"ecosystem":"npm"}