git-sqlite-vfs

library0.0.20jsnpmunverified

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.

database devops

npm install git-sqlite-vfs

package ↗

INSTALL

IMPORT

SIG · GIT-SQLITE-VFS

git-sqlite-vfs

databasejavascriptv0.0.20

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createVFSClient

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

✗ const { createVFSClient } = require('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

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

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

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.

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);

git-sqlite-vfs --version

Debug

Known issues

breakingThe `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.

affects: >=0.0.1

gotchaWhen 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';`.

affects: >=0.0.1

gotchaFor 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.

affects: >=0.0.1

gotchaNode.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.

affects: <22.5

Errors

Common errors & fixes

Error: VFS extension not loaded

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.

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.

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`.

Upgrade

Version history

0.0.20latest on npm

Audit

Dependencies

@libsql/clientrequiredRequired for connecting to libSQL/SQLite databases, used by the VFS client.

libsqloptionalPeer dependency, potentially for native bindings or alternative client usage alongside @libsql/client.

drizzle-kitrequiredPeer dependency for schema generation and migration tooling, integrated via git-sqlite-vfs CLI.

drizzle-ormoptionalCommonly used for ORM integration with the VFS-enabled database.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/git-sqlite-vfs ↗