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:

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

Prerequisites

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

Build Steps

The build process:

1. Setup Emscripten (if not already installed):

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:

# 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:

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:

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:

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:

cd ext/wasm
make

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

Usage Example

Using the Official OO1 API (Recommended)

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

Using in a Worker

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

Using as ES6 Module

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