Database-js SQLite Driver

Common errors

• Error: Cannot find module 'database-js2'

  cause The core `database-js` library was incorrectly referred to as `database-js2` in older documentation or examples.
  fix Change your import statement from `require('database-js2')` to `require('database-js')` or `import { Connection } from 'database-js';`.

• Error: NAPI_VERSION_MISMATCH (node-sqlite3)

  cause The native `node-sqlite3` module was compiled against a different Node.js N-API version than the one currently running, often due to Node.js version changes or corrupted `node_modules`.
  fix Delete `node_modules` and `package-lock.json`, then reinstall: `rm -rf node_modules package-lock.json && npm install`. If issues persist, ensure `node-gyp` is configured correctly or try rebuilding `node-sqlite3` specifically using `npm rebuild node-sqlite3`.

• Error: A database-js driver for 'sqlite' could not be found.

  cause The `database-js-sqlite` package, which registers the 'sqlite' driver for `database-js`, is not installed or accessible in your project.
  fix Ensure `database-js-sqlite` is listed in your dependencies and properly installed: `npm install database-js-sqlite`.

Warnings

• gotcha The README and examples historically referenced `database-js2`. The correct package name for the core library is `database-js`. Using `database-js2` will result in a 'Cannot find module' error.
  Fix: Always use `require('database-js')` or `import { Connection } from 'database-js'` for the core library.
• breaking This package, and its core dependency `database-js`, have not seen significant updates since 2018-2019. This means it may not be compatible with newer Node.js versions (e.g., > v16) or may lack support for modern JavaScript features or API changes.
  Fix: Thoroughly test compatibility with your target Node.js version. Consider alternative, more actively maintained SQLite drivers if encountering issues with newer environments.
• gotcha The underlying `node-sqlite3` package is a native module, which can cause installation issues (e.g., `node-gyp` errors) if build tools are not properly configured on your system or if prebuilt binaries are unavailable for your specific OS/Node.js architecture.
  Fix: Ensure you have Python 2.x/3.x, `make` (Linux/macOS) or Visual Studio Build Tools (Windows) installed. Refer to `node-sqlite3` documentation for troubleshooting native module compilation errors. Consider using the `sql.js` driver option for purely JavaScript environments.
• gotcha When specifying the `sql.js` driver, ensure `sql.js` is installed as a dependency. Without it, the connection attempt will fail when `driver=sql.js` is used.
  Fix: Install `sql.js` (e.g., `npm install sql.js`) if you intend to use it as the SQLite driver: `connection = new Connection('sqlite:///test.sqlite?driver=sql.js');`

Install

• npm install database-js-sqlite npm
• yarn add database-js-sqlite yarn
• pnpm add database-js-sqlite pnpm

Imports

• Connection
  wrong:

  var Database = require('database-js2').Connection;

  correct:

  import { Connection } from 'database-js';

  While the README historically showed `database-js2`, the correct package name for the core framework is `database-js`. This is the main class used to establish database connections after `database-js-sqlite` is installed and registers its driver.
• SQLiteConnection
  wrong:

  import { SQLiteConnection } from 'database-js-sqlite';

  correct:

  import SQLiteConnection from 'database-js-sqlite';

  This package exports its `SQLiteConnection` as a default export, though typical usage with `database-js` involves letting `database-js` auto-discover the driver via the connection string rather than direct instantiation.
• Database (CJS)
  wrong:

  const Database = require('database-js-sqlite');

  correct:

  const { Connection: Database } = require('database-js');

  For CommonJS environments, `Connection` is destructured from `database-js`. While `database-js-sqlite` exports `SQLiteConnection` as a default, the quickstart's `new Database(...)` refers to the core `Connection` object.

Quickstart

Demonstrates connecting to an SQLite database, creating a table, inserting data, and querying using prepared statements with the `database-js` API.

import { Connection } from 'database-js';

// Ensure database-js-sqlite and node-sqlite3 are installed:
// npm install database-js database-js-sqlite node-sqlite3

(async () => {
    let connection;
    try {
        // Connect to an SQLite database file. It will be created if it doesn't exist.
        connection = new Connection('sqlite:///test.sqlite');
        console.log('Database connection established.');

        // Create a table if it doesn't exist
        await connection.query(
            "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, user_name TEXT, email TEXT);"
        );
        console.log('Table 'users' ensured.');

        // Insert data using a prepared statement
        let statement = await connection.prepareStatement("INSERT INTO users (user_name, email) VALUES (?, ?)");
        await statement.query('john_doe', 'john@example.com');
        await statement.query('jane_smith', 'jane@example.com');
        console.log('Users inserted.');

        // Query data using a prepared statement
        statement = await connection.prepareStatement("SELECT * FROM users WHERE user_name = ?");
        const rows = await statement.query('john_doe');
        console.log('Query result for john_doe:', rows);

    } catch (error) {
        console.error('Database operation failed:', error);
    } finally {
        if (connection) {
            await connection.close();
            console.log('Database connection closed.');
        }
    }
})();