SQLite WASM

SQLite WASM conveniently wrapped as an ES Module. It includes the sqlite-sync, sqlite-vector, and sqlite-memory extensions that are automatically loaded at runtime. TypeScript types are from the official sqlite-wasm repository.

Features

• 🚀 SQLite WASM wrapped as an ES Module
• 🔄 Includes sqlite-sync, sqlite-vector, and sqlite-memory extensions
• 📝 Full TypeScript support
• 💾 OPFS (Origin Private File System) support for persistent storage
• ⚡ Worker thread support for better performance

Installation

npm install @sqliteai/sqlite-wasm

Vite Configuration

If you are using Vite, you need to add the following configuration options to your vite.config.js:

import{defineConfig}from'vite';exportdefaultdefineConfig({server: {headers: {'Cross-Origin-Opener-Policy': 'same-origin','Cross-Origin-Embedder-Policy': 'require-corp',},},optimizeDeps: {exclude: ['@sqliteai/sqlite-wasm'],},});

💡 Example: Check out the sport-tracker-app example to see SQLite WASM in action with a worker thread implementation.

Usage

There are three ways to use SQLite WASM:

1. Wrapped Worker - Uses a wrapped worker (recommended)
2. Direct Worker - Uses a direct worker implementation
3. Main Thread - Runs in the main thread ⚠️sqlite-sync does not work in the main thread

💡 Note: Only the worker versions support the Origin Private File System (OPFS) storage backend for persistent data storage.

Wrapped Worker (with OPFS Support)

Warning

For this to work, you need to set the following headers on your server:

Cross-Origin-Opener-Policy: same-origin

Cross-Origin-Embedder-Policy: require-corp

import{sqlite3Worker1Promiser}from'@sqliteai/sqlite-wasm';constlog=console.log;consterror=console.error;constinitializeSQLite=async()=>{try{log('Loading and initializing SQLite3 module...');constpromiser=awaitnewPromise((resolve)=>{const_promiser=sqlite3Worker1Promiser({onready: ()=>resolve(_promiser),});});log('Done initializing. Running demo...');constconfigResponse=awaitpromiser('config-get',{});log('Running SQLite3 version',configResponse.result.version.libVersion);constopenResponse=awaitpromiser('open',{filename: 'file:mydb.sqlite3?vfs=opfs',});const{ dbId }=openResponse;log('OPFS is available, created persisted database at',openResponse.result.filename.replace(/^file:(.*?)\?vfs=opfs$/,'$1'),);// Your SQLite code here.}catch(err){if(!(errinstanceofError)){err=newError(err.result.message);}error(err.name,err.message);}};initializeSQLite();

📚 API Reference: The promiser object implements the Worker1 API.

Direct Worker (with OPFS Support)

Warning

For this to work, you need to set the following headers on your server:

Cross-Origin-Opener-Policy: same-origin

Cross-Origin-Embedder-Policy: require-corp

Main thread (main.js):

constworker=newWorker('worker.js',{type: 'module'});

Worker thread (worker.js):

importsqlite3InitModulefrom'@sqliteai/sqlite-wasm';constlog=console.log;consterror=console.error;conststart=(sqlite3)=>{log('Running SQLite3 version',sqlite3.version.libVersion);constdb='opfs'insqlite3
? newsqlite3.oo1.OpfsDb('/mydb.sqlite3')
: newsqlite3.oo1.DB('/mydb.sqlite3','ct');log('opfs'insqlite3
? `OPFS is available, created persisted database at ${db.filename}`
: `OPFS is not available, created transient database ${db.filename}`,);// Your SQLite code here.};constinitializeSQLite=async()=>{try{log('Loading and initializing SQLite3 module...');constsqlite3=awaitsqlite3InitModule({print: log,printErr: error});log('Done initializing. Running demo...');start(sqlite3);}catch(err){error('Initialization error:',err.name,err.message);}};initializeSQLite();

📚 API Reference: The db object implements the Object Oriented API #1.

Main Thread (without OPFS)

importsqlite3InitModulefrom'@sqliteai/sqlite-wasm';constlog=console.log;consterror=console.error;conststart=(sqlite3)=>{log('Running SQLite3 version',sqlite3.version.libVersion);constdb=newsqlite3.oo1.DB('/mydb.sqlite3','ct');// Your SQLite code here.};constinitializeSQLite=async()=>{try{log('Loading and initializing SQLite3 module...');constsqlite3=awaitsqlite3InitModule({print: log,printErr: error,});log('Done initializing. Running demo...');start(sqlite3);}catch(err){error('Initialization error:',err.name,err.message);}};initializeSQLite();

📚 API Reference: The db object implements the Object Oriented API #1.

Resources

• 📖 SQLite WASM Documentation
• 🔧 Worker1 API Reference
• 🛠️ Object Oriented API #1
• 📦 Package on NPM

License

This project is licensed under the Elastic License 2.0. You can use, copy, modify, and distribute it under the terms of the license for non-production use. For production or managed service use, please contact SQLite Cloud, Inc for a commercial license.