Database-js2 Common Database Interface

Common errors

• Error: Driver not found for scheme 'sqlite'

  cause The specific database driver package (e.g., `database-js-sqlite`) has not been installed.
  fix Install the required driver package for your database type: `npm install database-js-sqlite` (for SQLite), `npm install database-js-mysql` (for MySQL), etc.

• TypeError: Cannot read properties of undefined (reading 'Connection')

  cause The `Connection` symbol was not correctly imported, likely due to mixing CommonJS `require` with incorrect property access, or attempting to use ESM `import`.
  fix Ensure you are using `const Connection = require('database-js2').Connection;` for CommonJS environments.

• UnhandledPromiseRejectionWarning: (some database error message)

  cause A Promise returned by a database operation (`query`, `close`, etc.) was rejected, and the rejection was not handled with a `.catch()` block.
  fix Always chain a `.catch()` method to your promise-based database operations, or use `try...catch` blocks with `async/await` to handle potential errors gracefully.

Warnings

• deprecated The `database-js2` package is officially deprecated. It will only receive critical bug fixes and no new features. All new development has moved to the `database-js` package (v3.x+).
  Fix: Migrate your projects to use the `database-js` package (npm install database-js) and update your code to its API, which is largely compatible but may have minor breaking changes in newer major versions.
• breaking This package is CommonJS-only. Direct `import` statements (ESM) are not supported. Attempting to use ESM imports will lead to module resolution errors.
  Fix: Use `const MySymbol = require('database-js2').MySymbol;` for all imports. For new projects, consider migrating to the `database-js` package which offers better ESM support.
• gotcha Drivers for specific databases (e.g., MySQL, PostgreSQL, SQLite) are not bundled with `database-js2`. You must install the relevant driver package separately (e.g., `npm install database-js-sqlite`) for your chosen database schema.
  Fix: Before establishing a connection, ensure the corresponding driver package for your database type is installed via npm. For example, for `sqlite:///`, ensure `database-js-sqlite` is installed.

Install

• npm install database-js2 npm
• yarn add database-js2 yarn
• pnpm add database-js2 pnpm

Imports

• Connection
  wrong:

  import { Connection } from 'database-js2';

  correct:

  const Connection = require('database-js2').Connection;

  This package (`database-js2` v1.x) is CommonJS-only. Attempting to use ESM `import` will result in a runtime error or unexpected behavior, as it does not export named ESM modules.

Quickstart

This example demonstrates how to establish a connection to an SQLite database, create a table, insert data using prepared statements, query specific data, and properly close the connection using async/await.

const Connection = require('database-js2').Connection;
const fs = require('fs');
const path = require('path');

const dbPath = path.join(__dirname, 'test.sqlite');

// Create a dummy SQLite database file if it doesn't exist
if (!fs.existsSync(dbPath)) {
    fs.writeFileSync(dbPath, '');
}

// Ensure the SQLite driver is installed: npm install database-js-sqlite
// If using 'mysql' or 'postgres', install their respective drivers.

const conn = new Connection(`sqlite:///${dbPath}`);

async function runExample() {
    try {
        // Create a table if it doesn't exist
        await conn.prepareStatement("CREATE TABLE IF NOT EXISTS states (id INTEGER PRIMARY KEY, name TEXT)").query();
        console.log("Table 'states' ensured.");

        // Insert some data
        await conn.prepareStatement("INSERT INTO states (name) VALUES (?)").query("California");
        await conn.prepareStatement("INSERT INTO states (name) VALUES (?)").query("Texas");
        await conn.prepareStatement("INSERT INTO states (name) VALUES (?)").query("Florida");
        console.log("Data inserted.");

        // Query data with a prepared statement
        const statement = conn.prepareStatement("SELECT * FROM states WHERE name = ?");
        const results = await statement.query("Texas");
        console.log("Query Results for 'Texas':", results);

        // Close the connection
        await conn.close();
        console.log("Connection closed. Example finished.");
    } catch (reason) {
        console.error("Error during example execution:", reason);
        if (conn) {
            try {
                await conn.close();
            } catch (closeReason) {
                console.error("Error closing connection:", closeReason);
            }
        }
    }
}

runExample();