sqljs-manager

Database Manager with Encryption

This package provides a simple and efficient solution for managing SQLite databases in the browser, with optional encryption for secure storage and support for exporting, importing, and uploading databases to a server.

Installation

Install the package using npm or yarn:

npm install your-database-package-name

or

yarn add your-database-package-name

Features

• Database Management:

  • Initialize, export, and import SQLite databases.
  • Execute SQL queries with ease.

• Encryption (Optional):

  • Securely encrypt and decrypt database dumps using AES-GCM.
  • Generate, import, and export encryption keys.

• Export and Import:

  • Export database dumps as plain binary or encrypted data.
  • Import plain or encrypted dumps.

• Server Interaction:

  • Upload database dumps to a server.
  • Easily handle serialized data for server communication.

• Local Storage Support:

  • Save encrypted database dumps to IndexedDB for persistence.
  • Load database dumps from IndexedDB for seamless offline operation.

Usage

1. Initialize a Database

import { DatabaseManager } from "your-database-package-name";

const dbManager = new DatabaseManager({
  locateFile: (file) => `/path-to-your-wasm/${file}` // Specify the path to sql-wasm.wasm
});

// Execute SQL commands
await dbManager.initialize([
  "CREATE TABLE expenses (id INTEGER PRIMARY KEY, date TEXT, amount REAL)"
]);
dbManager.execute("INSERT INTO expenses (date, amount) VALUES (?, ?)", ["2023-12-03", 100]);

console.log(dbManager.execute("SELECT * FROM expenses"));

2. Enable Encryption

To enable encryption, initialize an EncryptionManager:

import { EncryptionManager } from "your-database-package-name";

const encryptionManager = new EncryptionManager();
await encryptionManager.generateKey(); // Generate a new encryption key

// Optionally, export and import keys
const exportedKey = await encryptionManager.exportKey();
await encryptionManager.importKey(exportedKey);

3. Export and Import Database Dumps

Exporting a Database

You can export the database as plain or encrypted data:

const dump = await dbManager.exportDatabase();

Importing a Database

Import previously exported dumps (plain or encrypted):

await dbManager.importDatabase(dump);

4. Save and Load Database to/from IndexedDB

Save Encrypted Database to IndexedDB

await dbManager.saveToLocalStorage();

Load Encrypted Database from IndexedDB

await dbManager.loadFromLocalStorage("secure-password");

5. Upload Database to Server

Upload a database dump to a server endpoint:

import { uploadDatabaseToServer } from "your-database-package-name";

await uploadDatabaseToServer(dbManager, "https://your-server.com");

Important: WASM Usage

This package relies on the sql-wasm.wasm file for SQLite operations in the browser. You need to ensure this file is accessible from your project.

Steps to Include sql-wasm.wasm:

• Place the File: Copy sql-wasm.wasm from the sql.js package into your public directory (or equivalent for your build tool).

• Configure Path: Pass the correct path to the DatabaseManager using the locateFile option:

  const dbManager = new DatabaseManager({
    locateFile: (file) => `/path-to-wasm/${file}` // Adjust the path as needed
  });
  

• Default Path: If no locateFile is provided, the package will attempt to locate the file at /path-to-public/sql-wasm.wasm. Ensure this path is valid in your project structure.

API Reference

Classes

DatabaseManager

• execute(query: string, params?: any[]): any[]
  • Executes an SQL query with optional parameters.
• exportDatabase(): Promise<Uint8Array | { iv: Uint8Array; encrypted: Uint8Array }>
  • Exports the database dump (plain or encrypted).
• importDatabase(dump: Uint8Array | { iv: Uint8Array; encrypted: Uint8Array }): Promise<void>
  • Imports a database dump.
• saveToLocalStorage(): Promise<void>
  • Saves an encrypted database dump to IndexedDB.
• loadFromLocalStorage(password: string): Promise<void>
  • Loads an encrypted database dump from IndexedDB.

EncryptionManager

• generateKey(): Promise<void>
  • Generates a new encryption key.
• exportKey(): Promise<Uint8Array>
  • Exports the current encryption key.
• importKey(key: Uint8Array): Promise<void>
  • Imports an encryption key.
• encrypt(data: Uint8Array): Promise<{ iv: Uint8Array; encrypted: Uint8Array }>
  • Encrypts a given Uint8Array.
• decrypt(data: { iv: Uint8Array; encrypted: Uint8Array }): Promise<Uint8Array>
  • Decrypts encrypted data.

License

This package is licensed under the MIT License.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.