git-sqlite-vfs 0.0.9 → 0.0.11

package/README.md

@@ -1,42 +1,40 @@
 # git-sqlite-vfs
 
-A Git-Versioned SQLite Database powered by a custom native Virtual File System (VFS).
+A Git-versioned SQLite database utilizing a custom Virtual File System (VFS).
 
-By combining the robustness of native SQLite, Drizzle ORM, and libSQL with the distributed tracking power of Git, `git-sqlite-vfs` enables you to version, diff, and merge your application's database exactly like your source code. It works out-of-the-box in both **Node.js** and **Deno**.
+By integrating SQLite, Drizzle ORM, and libSQL with Git, `git-sqlite-vfs` enables versioning, diffing, and merging of SQLite databases. It is compatible with Node.js and Deno.
 
 ## Architecture
 
-Traditional SQLite databases are stored as a single flat file, making them difficult to version control because a 1-byte insertion can trigger a cascading byte shift across the entire file, rendering delta-compression useless.
+Standard SQLite databases are stored as a single file. This limits version control compatibility, as minor insertions cause cascading byte shifts, negating delta-compression and creating unresolvable binary merge conflicts.
 
-This package dynamically loads a specialized SQLite C Extension that overrides the default VFS. It shards your database into 4KB deterministic binary pages inside a targeted directory (e.g. `.my-db`).
+This package provides a loadable SQLite C extension that overrides the default VFS behavior. It shards the database into deterministic 4KB binary pages within a specified directory (e.g. `.my-db`).
 
-When you merge branches, our custom `git-merge-sqlitevfs` driver is natively hooked into Git's conflict resolution pipeline to properly reconcile binary B-Tree page conflicts, ensuring absolute data integrity!
+During a Git merge, a custom `git-merge-sqlitevfs` driver integrates with Git's conflict resolution pipeline to reconcile B-Tree page conflicts.
 
 ## Installation
 
-Install the VFS package alongside your libSQL and Drizzle tools:
-
 ```bash
 npm install git-sqlite-vfs @libsql/client drizzle-orm
 ```
 
-## Git Setup
+## Git Configuration
 
-To enable Git versioning and binary merging, you must configure your repository to use the custom merge driver. We provide a convenient CLI to wire everything up:
+The repository must be configured to use the custom merge driver. This configuration occurs automatically when `bootstrapGitVFS()` is called:
 
-```bash
-npx git-sqlite-setup --vfs-dir .my-db
-```
+1. Registers `git-merge-sqlitevfs` as a custom Git merge driver in the local `.git/config`.
+2. Updates `.gitattributes` in the repository root to route files matching the configured directory (e.g., `.my-db/*`) through the custom merge driver.
+3. Updates `.gitignore` to ignore SQLite transient files (`*-journal`, `*-wal`, `*-shm`).
+
+### Source Code Compatibility
 
-This will:
-1. Register `git-merge-sqlitevfs` as a custom Git merge driver in your local `.git/config`.
-2. Create or append to a `.gitattributes` file in your repo root to route all files in `.my-db/*` through the custom merge driver.
+The custom SQLite merge driver scopes to the designated database directory via `.gitattributes`. Other repository files continue using Git's default text-based merge algorithms.
 
-## Usage (Isomorphic)
+## Usage
 
-The VFS works transparently in both Node.js and Deno. By using the `bootstrapGitVFS()` method before you initialize `@libsql/client`, the native memory spaces are perfectly synchronized.
+The VFS operates in Node.js and Deno environments. Calling `bootstrapGitVFS()` prior to initializing `@libsql/client` loads the extension process-wide.
 
-### Using `@libsql/client` with Drizzle ORM
+### Example with `@libsql/client` and Drizzle ORM
 
 ```typescript
 import { createClient } from '@libsql/client'; // In Deno: 'npm:@libsql/client/node'
@@ -44,47 +42,47 @@ import { drizzle } from 'drizzle-orm/libsql';
 import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
 import { bootstrapGitVFS } from 'git-sqlite-vfs';
 
-// 1. Load the native extension process-wide and set the VFS directory
+// Load the native extension process-wide and set the VFS directory
 await bootstrapGitVFS({ dir: '.my-db' });
 
-// 2. Initialize your database connection using a standard file: URL
+// Initialize the database connection using a file URL
 const client = createClient({
     url: 'file:.my-db/local.db'
 });
 
-// 3. Wrap with Drizzle ORM
+// Wrap with Drizzle ORM
 const db = drizzle(client);
 
-// 4. Define your schema
+// Define the schema
 const users = sqliteTable('users', {
     id: integer('id').primaryKey(),
     name: text('name')
 });
 
-// 5. Query natively! All I/O is safely intercepted by the Git VFS.
+// Execute queries
 await db.insert(users).values({ id: 1, name: 'Alice' });
 const allUsers = await db.select().from(users);
 
 console.log(allUsers);
 ```
 
-## Preventing Git Bloat
+## Database Compaction
 
-Because SQLite usually zeroes out deleted data pages rather than shrinking the file, you might accumulate "zombie" `.bin` pages in your repository over time. To ensure the Git VFS automatically garbage-collects these abandoned chunks, you must configure SQLite to run `FULL` auto-vacuuming and use `DELETE` journaling.
+SQLite often zeroes out deleted data pages rather than shrinking the file size, causing unneeded `.bin` pages to remain. To allow the Git VFS to remove these unused shards, configure SQLite to use `FULL` auto-vacuuming and `DELETE` journaling.
 
-Run these PRAGMAs once when initializing your database connection:
+Execute these PRAGMA statements during connection initialization:
 
 ```sql
 PRAGMA auto_vacuum = FULL;
 PRAGMA journal_mode = DELETE;
 ```
 
-Or run `VACUUM;` periodically. When SQLite explicitly shrinks the database file, the underlying VFS `xTruncate` routine will physically `unlink()` the out-of-bounds `.bin` shards, keeping your Git tracking history perfectly compressed!
+Alternatively, executing `VACUUM;` periodically reduces the database file size, and the VFS `xTruncate` implementation will remove out-of-bounds `.bin` shards.
 
 ## Compatibility
 
-- **Node.js**: v22.5+ (using the new `node:sqlite` API internally) or fallback to `better-sqlite3`.
-- **Deno**: Supported automatically (loads the extension dynamically via `jsr:@db/sqlite`).
+- **Node.js**: v22.5+ (using the internal `node:sqlite` API) or fallback to `better-sqlite3`.
+- **Deno**: Supported natively (loads the extension dynamically via `jsr:@db/sqlite`).
 
 ## License
 

package/index.js

@@ -53,6 +53,14 @@ export async function bootstrapGitVFS(options = {}) {
     const db = new Database(':memory:');
     db.loadExtension(currentExtPath);
     db.close();
+
+    try {
+        const repoDir = typeof Deno !== 'undefined' ? Deno.cwd() : process.cwd();
+        const vfsDir = options.dir || '.db';
+        await configureGitIntegration({ repoDir, vfsDir });
+    } catch (e) {
+        // Ignore errors if git is not available or not in a git repository
+    }
 }
 
 export async function configureGitIntegration({ repoDir, vfsDir }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-sqlite-vfs",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "A Git-Versioned SQLite Database via a Custom Virtual File System (VFS)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -24,9 +24,9 @@
   "scripts": {
     "build": "cd c && make",
     "postinstall": "node install.js",
-    "pretest": "npm run build && rm -rf .db test.db .test-db .compaction-db .git && git init --initial-branch=master",
+    "pretest": "npm run build && rm -rf .db test.db .test-db .compaction-db .git .gitattributes .gitignore && git init --initial-branch=master",
     "test": "node --test test/*.node.test.js",
-    "test:deno": "npm run build && rm -rf .db test.db .test-db .git && git init --initial-branch=master && deno test -A test/*.deno.test.ts"
+    "test:deno": "npm run build && rm -rf .db test.db .test-db .git .gitattributes .gitignore && git init --initial-branch=master && deno test -A test/*.deno.test.ts"
   },
   "dependencies": {
     "@libsql/client": "^0.14.0",