SQLite Wasm conveniently wrapped as an ES Module.
npm install @sqlite.org/sqlite-wasmSQLite Wasm conveniently wrapped as an ES Module.
> [!Warning]
>
> This project wraps the code of
> SQLite Wasm with _no_ changes,
> apart from added TypeScript types. Please do _not_ file issues or feature
> requests regarding the underlying SQLite Wasm code here. Instead, please
> follow the
> SQLite bug filing instructions.
> Filing TypeScript type related issues and feature requests is fine.
> [!Warning]
>
> Node.js is currently only supported for in-memory databases without
> persistence.
``bash`
npm install @sqlite.org/sqlite-wasm
There are three ways to use SQLite Wasm:
- in the main thread with a wrapped worker
(🏆 preferred option)
- in a worker
- in the main thread
Only the worker versions allow you to use the origin private file system (OPFS)
storage back-end.
> [!Warning]
>
> For this to work, you need to set the following headers on your server:
>
> Cross-Origin-Opener-Policy: same-origin
>
>
`js
import { sqlite3Worker1Promiser } from '@sqlite.org/sqlite-wasm';
const log = console.log;
const error = console.error;
const initializeSQLite = async () => {
try {
log('Loading and initializing SQLite3 module...');
const promiser = await new Promise((resolve) => {
const _promiser = sqlite3Worker1Promiser({
onready: () => resolve(_promiser),
});
});
log('Done initializing. Running demo...');
const configResponse = await promiser('config-get', {});
log('Running SQLite3 version', configResponse.result.version.libVersion);
const openResponse = await promiser('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 (!(err instanceof Error)) {
err = new Error(err.result.message);
}
error(err.name, err.message);
}
};
initializeSQLite();
`
The promiser object above implements the
Worker1 API.
> [!Warning]
>
> For this to work, you need to set the following headers on your server:
>
> Cross-Origin-Opener-Policy: same-origin
>
>
`jsmain.js
// In .`
const worker = new Worker('worker.js', { type: 'module' });
`jsworker.js
// In .
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
const log = console.log;
const error = console.error;
const start = (sqlite3) => {
log('Running SQLite3 version', sqlite3.version.libVersion);
const db =
'opfs' in sqlite3
? new sqlite3.oo1.OpfsDb('/mydb.sqlite3')
: new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
log(
'opfs' in sqlite3
? OPFS is available, created persisted database at ${db.filename}
: ,
);
// Your SQLite code here.
};
const initializeSQLite = async () => {
try {
log('Loading and initializing SQLite3 module...');
const sqlite3 = await sqlite3InitModule();
log('Done initializing. Running demo...');
start(sqlite3);
} catch (err) {
error('Initialization error:', err.name, err.message);
}
};
initializeSQLite();
`
The db object above implements the
Object Oriented API #1.
`js
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
const log = console.log;
const error = console.error;
const start = (sqlite3) => {
log('Running SQLite3 version', sqlite3.version.libVersion);
const db = new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
// Your SQLite code here.
};
const initializeSQLite = async () => {
try {
log('Loading and initializing SQLite3 module...');
const sqlite3 = await sqlite3InitModule();
log('Done initializing. Running demo...');
start(sqlite3);
} catch (err) {
error('Initialization error:', err.name, err.message);
}
};
initializeSQLite();
`
The db object above implements the
Object Oriented API #1.
If you are using vite, you need to add the following
config option in vite.config.js:
`js
import { defineConfig } from 'vite';
export default defineConfig({
server: {
headers: {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
},
},
optimizeDeps: {
exclude: ['@sqlite.org/sqlite-wasm'],
},
});
`
Check out a
sample project
that shows this in action.
See the demo folder for
examples of how to use this in the main thread and in a worker. (Note that the
worker variant requires special HTTP headers, so it can't be hosted on GitHub
Pages.) An example that shows how to use this with vite is available on
StackBlitz.
See the list of
npm dependents
for this package.
(These steps can only be executed by maintainers.)
1. Manually trigger the
GitHub Actions workflow. By
default, it uses the latest SQLite tag. This pull request will contain the
latest sqlite3.wasm and related bindings.
2. Once the above pull request is validated and merged, update the version
number in package.json, reflecting the current-build1
SQLite version number and add a build
identifier suffix like . The complete version number should read3.41.2-build1
something like .
1. Build the Docker image:
`bash`
docker build -t sqlite-wasm-builder:env .
2. Run the build:
Unix (Linux/macOS):
`bash`
docker run --rm \
-e SQLITE_REF="master" \
-v "$(pwd)/out":/out \
-v "$(pwd)/src/bin":/src/bin \
sqlite-wasm-builder:env build
Windows (PowerShell):
`powershell
docker run --rm
-e SQLITE_REF="master"
-v "${PWD}/out:/out"
-v "${PWD}/src/bin:/src/bin"
sqlite-wasm-builder:env build
Windows (Command Prompt):
`cmd`
docker run --rm ^
-e SQLITE_REF="master" ^
-v "%cd%/out:/out" ^
-v "%cd%/src/bin:/src/bin" ^
sqlite-wasm-builder:env build
The test suite consists of Node.js tests and browser-based tests (using Vitest
Browser Mode). Tests aim to sanity-check the exported scripts. We test for
correct exports and very basic functionality.
1. Install dependencies:
`bash`
npm install
2. Install Playwright browsers (required for browser tests):
`bash`
npx playwright install chromium --with-deps --no-shell
3. Run all tests:
`bash`
npm test
Apache 2.0.
This project is based on SQLite Wasm, which it
conveniently wraps as an ES Module and publishes to npm as
@sqlite.org/sqlite-wasm`.