{"id":43976,"library":"sql.js","title":"sql.js","description":"SQLite compiled to JavaScript via Emscripten, enabling full SQLite functionality in browsers and Node.js without native bindings. Current stable version is 1.14.1, released periodically. Key differentiator: runs entirely in memory using WebAssembly (or legacy JS), allows importing/exporting SQLite database files as Uint8Array, and works cross-platform without native dependencies. Includes contributed math/string extension functions. Note: unlike native SQLite bindings (e.g., sqlite3), sql.js requires loading the entire database into memory, which can cause out-of-memory issues for large databases. Pure JavaScript implementation with WebAssembly fallback.","status":"active","version":"1.14.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/sql-js/sql.js","tags":["javascript","sql","sqlite","stand-alone","relational","database","RDBMS","data","query"],"install":[{"cmd":"npm install sql.js","lang":"bash","label":"npm"},{"cmd":"yarn add sql.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add sql.js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used to compile SQLite to WebAssembly/JavaScript; required at build time, but not at runtime.","package":"emscripten","optional":true}],"imports":[{"note":"Default export is a factory function that returns a promise of the SQL module. The require() pattern works in CommonJS but is not recommended for ESM projects. Always await the result before using SQL.","wrong":"const initSqlJs = require('sql.js')","symbol":"initSqlJs","correct":"import initSqlJs from 'sql.js'"},{"note":"initSqlJs returns a Promise that resolves to the SQL module. Forgetting to await leads to undefined. The locateFile configuration is required in browsers to find the .wasm file; can be omitted in Node.js if the wasm binary is in the expected location.","wrong":"const SQL = initSqlJs()","symbol":"SQL (module object)","correct":"const SQL = await initSqlJs({ locateFile: file => `/path/${file}` })"},{"note":"Database class is accessed via the SQL module object (e.g., SQL.Database). Cannot be imported as a named export directly. Always use SQL.Database after initializing the module.","wrong":"const db = new Database(); // ReferenceError","symbol":"Database","correct":"const db = new SQL.Database();"},{"note":"Statements are created via db.prepare(), not by constructing a Statement class directly. The Statement class is internal and not exported.","wrong":"const stmt = new SQL.Statement('SELECT * FROM test');","symbol":"Statement (prepared)","correct":"const stmt = db.prepare('SELECT * FROM test');"}],"quickstart":{"code":"import initSqlJs from 'sql.js';\n\nasync function main() {\n  const SQL = await initSqlJs({\n    locateFile: file => `https://sql.js.org/dist/${file}`\n  });\n\n  const db = new SQL.Database();\n\n  db.run(\"CREATE TABLE test (id INT, name TEXT);\");\n  db.run(\"INSERT INTO test VALUES (1, 'Alice');\");\n  db.run(\"INSERT INTO test VALUES (2, 'Bob');\");\n\n  const stmt = db.prepare(\"SELECT * FROM test WHERE id > :id\");\n  stmt.bind({ ':id': 0 });\n  while (stmt.step()) {\n    const row = stmt.getAsObject();\n    console.log(row.id, row.name);\n  }\n  stmt.free();\n\n  const data = db.export();\n  const buffer = Buffer.from(data);\n  console.log('Exported db size:', buffer.length);\n\n  db.close();\n}\n\nmain().catch(console.error);","lang":"javascript","description":"Demonstrates creating an in-memory SQLite database, running statements, using prepared statements with parameter binding, and exporting the database as a Uint8Array."},"warnings":[{"fix":"Call db.export() to get a Uint8Array and persist it (e.g., write to file or localStorage). To import, pass the Uint8Array to new SQL.Database(data).","message":"The database is stored in memory only; changes are not persisted unless manually exported via db.export() and saved to disk/indexedDB.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use await initSqlJs() or .then() instead of passing a callback.","message":"In version 1.0, the API changed from callback-based to Promise-based: initSqlJs() now returns a Promise.","severity":"breaking","affected_versions":"<1.0 -> >=1.0"},{"fix":"Set locateFile property in initSqlJs config to point to the correct URL or local path of the .wasm file.","message":"In browsers, the WebAssembly binary (sql-wasm.wasm) must be served as a static asset or loaded via CDN. Failing to provide locateFile will cause initSqlJs() to fail with a network error.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use the default WebAssembly build (sql-wasm.js) by importing 'sql.js' which now uses WASM. For legacy browsers, use the 'sql-asm.js' variant explicitly.","message":"The old non-WASM JavaScript fallback (sql.js) is deprecated; always use the WebAssembly version for better performance.","severity":"deprecated","affected_versions":"<1.5"},{"fix":"Always call stmt.free() after processing all rows, or use try/finally to ensure cleanup.","message":"Prepared statements must be freed manually (stmt.free()) to avoid memory leaks. Failure to do so accumulates resource usage.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Explicitly set locateFile in initSqlJs options, or ensure the wasm file is in the expected path relative to the script.","message":"In Node.js, the wasm binary may not be found automatically if installed globally or via a package manager that flattens node_modules. This can cause 'Error: Could not locate the wasm binary'.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"search_vec":"'1.14.1':23 'allow':37 'alon':94 'bind':18,61 'browser':13 'caus':74 'compil':3 'contribut':53 'cross':47 'cross-platform':46 'current':19 'data':98 'databas':40,69,82,96 'depend':51 'differenti':27 'e.g':62 'emscripten':7 'enabl':8 'entir':29,68 'extens':55 'fallback':88 'file':41 'full':9 'function':11,56 'implement':85 'importing/exporting':38 'includ':52 'issu':79 'javascript':5,84,89 'js':36 'key':26 'larg':81 'legaci':35 'load':66 'math/string':54 'memori':31,71,78 'nativ':17,50,59 'node.js':15 'note':57 'out-of-memori':75 'period':25 'platform':48 'pure':83 'queri':99 'rdbms':97 'relat':95 'releas':24 'requir':65 'run':28 'sql':90 'sql.js':1,64 'sqlite':2,10,39,60,91 'sqlite3':63 'stabl':20 'stand':93 'stand-alon':92 'uint8array':43 'unlik':58 'use':32 'version':21 'via':6 'webassembl':33,87 'without':16,49 'work':45","created_at":"2026-06-05T17:02:22.817452+00:00","updated_at":"2026-06-05T17:02:22.817452+00:00","problems":[{"fix":"const SQL = await initSqlJs({ locateFile: ... });","cause":"Forgot to await initSqlJs() or assigned the result incorrectly.","error":"TypeError: SQL is not a constructor"},{"fix":"Ensure the .wasm file matches the sql.js version. Use the same source for both (e.g., from npm).","cause":"Corrupted or incompatible wasm binary, or using a version mismatch between js and wasm files.","error":"RuntimeError: memory access out of bounds"},{"fix":"Provide a valid locateFile function that returns the correct URL or local path to sql-wasm.wasm.","cause":"The locateFile callback returned an incorrect path, or the binary is missing.","error":"Error: Could not locate the wasm binary"},{"fix":"Use the legacy JavaScript build (sql-asm.js) instead of the WASM build, or ensure the environment supports SharedArrayBuffer (requires cross-origin isolation headers).","cause":"Using sql.js in an environment where SharedArrayBuffer is not available (e.g., older browsers, or non-secure contexts).","error":"Uncaught (in promise) ReferenceError: SharedArrayBuffer is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"http://github.com/sql-js/sql.js","github":"ssh://git@github.com/sql-js/sql.js","docs":null,"changelog":null,"pypi":null,"npm":"sql.js","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}