sqlite-vss

library0.1.2jsnpmunverified

SQLite vector similarity search extension via npm for Node.js. Current version 0.1.2, release cadence infrequent. Provides vector search capabilities (e.g., cosine similarity, inner product) as a loadable SQLite extension. Key differentiator: pre-compiled binaries for MacOS and Linux x64, integrates with better-sqlite3 and node-sqlite3. Includes TypeScript types.

database ai-ml

npm install sqlite-vss

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-VSS

sqlite-vss

databasejavascriptv0.1.2

harness data pending

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.

getLoadablePath

✓ import * as sqlite_vss from 'sqlite-vss'; const path = sqlite_vss.getLoadablePath()

✗ import { getLoadablePath } from 'sqlite-vss'

Exported as named export from module, but correct usage is via namespace import

load

✓ import * as sqlite_vss from 'sqlite-vss'; sqlite_vss.load(db)

✗ const sqlite_vss = require('sqlite-vss'); sqlite_vss.load(db)

For better-sqlite3; load() attaches extension automatically

default

✓ import * as sqlite_vss from 'sqlite-vss'

✗ import sqlite_vss from 'sqlite-vss'

No default export; use namespace import

Shows how to load the extension, create a virtual table with vector index, insert vectors, and perform a similarity search.

import Database from 'better-sqlite3'; import * as sqlite_vss from 'sqlite-vss'; const db = new Database(':memory:'); sqlite_vss.load(db); // Create a virtual table for vector search db.exec(`CREATE VIRTUAL TABLE vss_docs USING vss0( headline_embedding(512) distance_measure=cosine )`); // Insert sample data const vector = new Float32Array(512); vector.fill(0.1); const vectorBuffer = Buffer.from(vector.buffer); db.prepare(`INSERT INTO vss_docs (rowid, headline_embedding) VALUES (?, ?)`).run(1, vectorBuffer); // Query const queryVector = new Float32Array(512); queryVector.fill(0.1); const queryBuffer = Buffer.from(queryVector.buffer); const results = db.prepare(`SELECT rowid, distance FROM vss_docs WHERE vss_search(headline_embedding, ?) LIMIT 5`).all(queryBuffer); console.log(results);

Debug

Known issues

deprecatedThe `vss_version()` function may be removed in future versions.

fix

Check release notes for alternative API.

affects: >=0.1.0

breakingPlatform-specific optional dependencies are required; installing with --no-optional will break.

fix

Always install without --no-optional flag.

affects: >=0.1.0

gotchaVector embeddings must be provided as Buffer (not Array or Float32Array directly) when using better-sqlite3.

fix

Convert Float32Array to Buffer via Buffer.from(array.buffer).

affects: >=0.1.0

gotchaOnly supports darwin-x64 and linux-x64 platforms; other platforms will throw an Error.

fix

Check process.platform and process.arch before installing.

affects: >=0.1.0

breakingIncompatible with some SQLite builds due to extension loading restrictions.

fix

Ensure SQLite library supports loadable extensions (enable with SQLITE_ENABLE_LOAD_EXTENSION).

affects: >=0.1.0

deprecatedUsage with node-sqlite3 requires manual loadExtension call; load() is only for better-sqlite3.

fix

For node-sqlite3, use sqlite_vss.getLoadablePath() and pass to db.loadExtension().

affects: >=0.1.0

Errors

Common errors & fixes

Error: The specified module could not be found. \\?\\...\\sqlite-vss.node

Missing platform-specific optional dependency or incorrect architecture.

fix

Ensure you are on a supported platform and did not use --no-optional. Verify with `node -e 'console.log(process.platform, process.arch)'`.

Error: Cannot find module 'sqlite-vss'

Package not installed or incorrect import path.

fix

Run `npm install sqlite-vss` in your project directory.

Error: loadExtension is not a function

Using db.loadExtension() on a database instance that doesn't support it (e.g., better-sqlite3 uses .load() instead).

fix

Use db.loadExtension() for node-sqlite3, or sqlite_vss.load(db) for better-sqlite3.

TypeError: Invalid buffer size or invalid vector dimension

Vector buffer size doesn't match the declared dimension (e.g., 512 floats = 2048 bytes).

fix

Ensure the Buffer length equals dimension * 4 bytes (Float32).

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

better-sqlite3optionalPrimary SQLite client used for loading the extension

sqlite3optionalAlternative SQLite client for loading the extension

Agent activity

20 hits · last 30 days

node