sqlite-vec-wasm

SQLite 3.50.4 with sqlite-vec v0.1.6 compiled to WebAssembly using the official SQLite WASM build system.

Features

- Full SQLite 3.50.4 running in the browser
- Vector similarity search with sqlite-vec v0.1.6 auto-initialized
- Official SQLite WASM API with OO1 wrapper
- Worker thread support
- OPFS (Origin-Private FileSystem) support
- ESM and bundler-friendly builds
- FTS5, R-Tree, JSON1, and more extensions
- Pure WASM - no server required

Build Output

Pre-built files in dist/ (official SQLite WASM build):
- sqlite3.js (766 KB) - Full JavaScript API with all features
- sqlite3.wasm (1.9 MB) - Compiled binary with SQLite + sqlite-vec
- sqlite3.mjs - ES6 module version
- sqlite3-bundler-friendly.mjs - For bundlers (webpack, vite, etc.)
- sqlite3-worker1*.js - Worker thread support files
- sqlite3-opfs-async-proxy.js - OPFS support

Quick Start

1. Serve the files with a local web server with COOP/COEP headers:
``bash


Using the included Node.js server (recommended)

node server.js

Or use the official SQLite build's server:

cd sqlite-src/ext/wasm
make httpd # Uses althttpd with -enable-sab flag
`

2. Open test.html in your browser to see it working:
`
http://localhost:8000/test.html
`

Notes:
- COOP/COEP headers are required for SharedArrayBuffer support
- OPFS (Origin-Private FileSystem) VFS requires running in a Worker thread
- Standard python3 -m http.server doesn't send the required headers

Building from Source

This project uses the official SQLite WASM build system with sqlite-vec integrated.

$3

- Emscripten SDK
- GNU Make
- Standard build tools (gcc, etc.)

$3

The build process:

1. Setup Emscripten (if not already installed):
`bash
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
`

2. Get SQLite source with WASM build system:
`bash


Download and extract SQLite source


curl -O https://www.sqlite.org/2025/sqlite-src-3504000.zip
unzip sqlite-src-3504000.zip
mv sqlite-src-3504000 sqlite-src
`

3. Clone sqlite-vec into SQLite extensions:
`bash
git clone https://github.com/asg017/sqlite-vec.git sqlite-src/ext/sqlite-vec
cd sqlite-src/ext/sqlite-vec
git checkout v0.1.6
`

4. Generate sqlite-vec.h:
`bash
cd sqlite-src/ext/sqlite-vec
VERSION='0.1.6'
sed -e "s/\${VERSION}/$VERSION/g" \
-e "s/\${VERSION_MAJOR}/0/g" \
-e "s/\${VERSION_MINOR}/1/g" \
-e "s/\${VERSION_PATCH}/6/g" \
-e 's/SQLITE_VEC_LOADABLE_EXTENSION 1/SQLITE_VEC_LOADABLE_EXTENSION 0/' \
sqlite-vec.h.tmpl > sqlite-vec.h
`

5. Configure SQLite build:
`bash
cd sqlite-src
./configure --with-emsdk=/path/to/emsdk
`

6. Integrate sqlite-vec by modifying ext/wasm/GNUmakefile:
- Add sqlite-vec.c to compilation
- Add include path for sqlite-vec
- Create auto-init file

7. Build:
`bash
cd ext/wasm
make
`

Output will be in sqlite-src/ext/wasm/jswasm/

Usage Example

$3

`javascript
sqlite3InitModule().then(function(sqlite3){
// Open database
const db = new sqlite3.oo1.DB();

// sqlite-vec is auto-initialized! No manual init required.

// Create vector table
db.exec('CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[384]);');

// Insert vectors
db.exec("INSERT INTO vec_items(rowid, embedding) VALUES (1, '[0.1, 0.2, 0.3, ...]');");

// Query vectors
const results = db.exec({
sql: 'SELECT rowid, embedding FROM vec_items',
rowMode: 'object',
returnValue: 'resultRows'
});

// Search for similar vectors
const similar = db.exec({
sql: SELECT rowid, distance
FROM vec_items
WHERE embedding MATCH '[0.15, 0.25, 0.35, ...]'
ORDER BY distance LIMIT 5,
returnValue: 'resultRows'
});

// Check sqlite-vec version
const version = db.exec({
sql: 'SELECT vec_version()',
returnValue: 'resultRows'
});

db.close();
});
`

$3

`javascript
importScripts('dist/sqlite3.js');
sqlite3InitModule().then(function(sqlite3){
const db = new sqlite3.oo1.DB();
// ... use the same API as above
});
`

$3

`javascript
import sqlite3InitModule from './dist/sqlite3.mjs';
const sqlite3 = await sqlite3InitModule();
const db = new sqlite3.oo1.DB();
// ... rest of your code
`

Note: sqlite-vec is automatically initialized when you open a database - no need to call sqlite3_vec_init() manually!

What's Compiled In

SQLite Features:
- FTS5 (full-text search)
- R-Tree (spatial indexing)
- JSON1 (JSON functions)
- Session extension
- DBSTAT, DBPAGE virtual tables
- Math functions
- And more - see official SQLite WASM docs

sqlite-vec Features:
- vec0 virtual table for vector storage
- Float32, Float64, Int8 vector types
- Multiple distance metrics
- KNN search
- Auto-initialized on database open

Build Configuration:
- Official SQLite WASM build system
- Full OO1 API wrapper
- Worker thread support
- OPFS (Origin-Private FileSystem)
- Memory growth enabled
- Web + Worker environments

Project Structure

`
.
├── dist/ # Built WASM files from official build
│ ├── sqlite3.js # Main vanilla JS build
│ ├── sqlite3.wasm # WASM binary
│ ├── sqlite3.mjs # ES6 module
│ ├── sqlite3-bundler-friendly.mjs
│ ├── sqlite3-worker1*.js # Worker support
│ └── sqlite3-opfs-async-proxy.js
├── sqlite-src/ # Full SQLite source tree
│ ├── ext/
│ │ ├── wasm/ # Official WASM build system
│ │ │ ├── GNUmakefile # Modified to include sqlite-vec
│ │ │ └── sqlite3_wasm_extra_init.c # Auto-init sqlite-vec
│ │ └── sqlite-vec/ # sqlite-vec extension
│ └── ...
├── test.html # Demo using OO1 API
└── README.md
`

Note: Source directories (emsdk/, sqlite-src/`) are excluded from git.

License

- SQLite: Public Domain
- sqlite-vec: Apache 2.0 / MIT dual license
- This build script: Public Domain

Credits

- SQLite - D. Richard Hipp
- sqlite-vec - Alex Garcia
- Emscripten - LLVM-to-WebAssembly compiler