GlueSQL.js

GlueSQL.js is a SQL database for web browsers and Node.js. It works as an embedded database and entirely runs in the browser. GlueSQL.js supports in-memory, localStorage, and sessionStorage backends in browsers.

Learn more at the https://gluesql.org/docs

• Getting Started - JavaScript
• Getting Started - Node.js
• SQL Syntax

Installation

Yarn

yarn add gluesql

npm

npm install gluesql

JavaScript modules

import { gluesql } from 'https://cdn.jsdelivr.net/npm/gluesql/gluesql.js';

Usage

import { gluesql } from 'gluesql';

const db = await gluesql();

await db.query(`
  CREATE TABLE User (id INTEGER, name TEXT);
  INSERT INTO User VALUES (1, "Hello"), (2, "World");
`);

const [{ rows }] = await db.query('SELECT * FROM User;');

console.log(rows);

Browser Storage Engines

GlueSQL.js includes three browser storage engines:

Engine	Persistence	Notes
memory	In-memory only	Default engine. Data is cleared when the page is reloaded.
localStorage	Persistent per origin	Uses the browser localStorage API.
sessionStorage	Persistent for the browser tab session	Uses the browser sessionStorage API.

Specify the storage engine with the ENGINE clause when creating a table:

import { gluesql } from 'gluesql';

const db = await gluesql();

await db.query(`
  CREATE TABLE Mem (id INTEGER) ENGINE = memory;
  CREATE TABLE Loc (id INTEGER) ENGINE = localStorage;
  CREATE TABLE Ses (id INTEGER) ENGINE = sessionStorage;
`);

The browser package can query tables backed by different engines through the same SQL interface:

const db = await gluesql();

await db.query(`
  CREATE TABLE Mem (id INTEGER) ENGINE = memory;
  CREATE TABLE Loc (id INTEGER) ENGINE = localStorage;
  CREATE TABLE Ses (id INTEGER) ENGINE = sessionStorage;

  SELECT *
  FROM Mem
  JOIN Loc
  JOIN Ses;
`);

Memory

memory is the default storage engine. It is available in browsers and Node.js.

const db = await gluesql();

await db.query(`
  CREATE TABLE User (id INTEGER, name TEXT) ENGINE = memory;
`);

When the ENGINE clause is omitted, GlueSQL.js uses the current default engine. The initial default engine is memory.

Web Storage

localStorage and sessionStorage are available in browsers and use the browser Web Storage APIs.

const db = await gluesql();

await db.query(`
  CREATE TABLE LocalCache (id INTEGER, value TEXT) ENGINE = localStorage;
  CREATE TABLE SessionCache (id INTEGER, value TEXT) ENGINE = sessionStorage;
`);

• localStorage keeps data for the browser origin until it is explicitly cleared.
• sessionStorage keeps data for the current browser tab session.

Web Storage is useful for lightweight structured data. Browsers apply storage quotas, commonly around several MB per origin, so avoid using localStorage or sessionStorage for large datasets.

Changing The Default Engine

The default engine is memory. In browsers, you can change it after creating the database:

const db = await gluesql();

db.setDefaultEngine('localStorage');

await db.query(`
  CREATE TABLE User (id INTEGER, name TEXT);
`);

Node.js currently supports only non-persistent memory storage.

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.