Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
loadExtension
✓ import Database from 'better-sqlite3';
const db = new Database(':memory:');
db.loadExtension('path/to/vss0.so');
✗ const Database = require('sqlite3').Database;
const db = new Database(':memory:');
db.loadExtension('path/to/vss0.so');
Use better-sqlite3 for synchronous API; node-sqlite3 is callback-based.
sqlite3
✓ const sqlite3 = require('sqlite3');
const db = new sqlite3.Database(':memory:').loadExtension('path/to/vss0.so', (err) => { ... });
✗ import { Database } from 'sqlite3';
node-sqlite3 uses CommonJS; ESM import may not work directly.
getVectorTable
✓ db.exec(`CREATE VIRTUAL TABLE vss_docs USING vss0(doc_embedding(384))`);
const rows = db.prepare('SELECT * FROM vss_docs WHERE vss_search(doc_embedding, ?)').all(queryEmbedding);
✗ db.exec(`CREATE VIRTUAL TABLE vss_docs USING vss0(doc_embedding)`);
The dimension must be specified in parentheses after the column name.
Creates an in-memory SQLite database, loads the vss0 extension, creates a virtual table for vector search, inserts a vector, and queries for nearest neighbors.
import Database from 'better-sqlite3';
import { join } from 'path';
const db = new Database(':memory:');
const extPath = join(__dirname, 'node_modules/sqlite-vss-linux-x64/lib/vss0.so');
db.loadExtension(extPath);
db.exec(`CREATE VIRTUAL TABLE vss_items USING vss0(item_embedding(512));`);
const insert = db.prepare('INSERT INTO vss_items(rowid, item_embedding) VALUES (?, ?)');
const embedding = new Float32Array(512); // populate with data
insert.run(1, Buffer.from(embedding.buffer));
const query = db.prepare(`SELECT rowid, distance FROM vss_items WHERE vss_search(item_embedding, ?) ORDER BY distance LIMIT 3`);
const results = query.all(Buffer.from(queryEmbedding.buffer));
console.log(results);
Errors
Common errors & fixes
Error: The specified module could not be found. \\?\C:\...\vss0.so
Attempting to load Linux .so on Windows.
fixInstall the correct platform package (e.g., sqlite-vss-win32-x64-msvc) or use sqlite-vss for automatic platform detection.
Error: dlopen(.../vss0.so): cannot open shared object file: No such file or directory
Pre-compiled extension not found or path incorrect.
fixVerify the path points to node_modules/sqlite-vss-linux-x64/lib/vss0.so.
Error: malformed database schema (vss0) - no such module: vss0
Extension not loaded before virtual table creation.
fixCall db.loadExtension(extPath) before any VIRTUAL TABLE statements.
Audit
Dependencies
better-sqlite3optionalRequired at runtime to load the extension; alternative to node-sqlite3
node-sqlite3optionalAlternative runtime for loading the extension
sqlite-vssrequiredParent package that resolves to this platform-specific package