UeberDB2: Abstract Your Databases

Common errors

• TypeError: ueberdb.Database is not a constructor

  cause Attempting to destructure `Database` from a CommonJS `require('ueberdb2')` without correctly accessing the `Database` property on the default export.
  fix For CommonJS, use `const ueberdb = require('ueberdb2'); const db = new ueberdb.Database(...)`. For ESM, use `import { Database } from 'ueberdb2'; const db = new Database(...)`.

• Error: Driver for <database-type> not found or could not be loaded. Please ensure the corresponding npm package is installed.

  cause The npm package for the specified database driver (e.g., `mysql2`, `pg`, `redis`) is not installed in your project's `node_modules`.
  fix Install the required database driver package: `npm install <driver-name>` (e.g., `npm install mysql2`).

• UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().

  cause A database operation (e.g., `db.set`, `db.get`, `db.init`) returned a Promise that rejected, but there was no `.catch()` handler or `try...catch` block around the `await` call.
  fix Wrap `await` calls in `try...catch` blocks or chain `.catch()` to handle potential errors from asynchronous database operations.

• Error: connect ECONNREFUSED <host>:<port>

  cause The database server is not running, is configured incorrectly, or network connectivity is blocked. This is a common connection error for relational and NoSQL databases.
  fix Verify that your database server is running, reachable from your application host, and that the connection details (host, port, user, password, database name) in your `DatabaseOptions` are correct.

Warnings

• breaking UeberDB2 v5.x has dropped support for callbacks and is exclusively `async/await` based. All database methods now return Promises. Legacy code using callbacks will break.
  Fix: Refactor all database interactions to use `await` with the returned Promises or `.then/.catch`.
• breaking The minimum supported Node.js version is now 18.0.0. Running `ueberdb2` on older Node.js versions will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 18.0.0 or higher. Consider using an LTS version for production.
• breaking Database drivers like Elasticsearch and Redis have seen internal client library updates in v5.0.0. Specifically, Elasticsearch uses `@elastic/elasticsearch` v7.17.0, and Redis has updated its client configuration object. Some old database drivers (CrateDB, LevelDB, LMDB) have been dropped.
  Fix: Review the specific client library documentation for your chosen database if you encounter connection or configuration issues. If using Elasticsearch, ensure you've enabled `migrate_to_newer_schema` option if needed.
• gotcha Database drivers are peer dependencies. `ueberdb2` itself has '0 Dependencies' in its `package.json` to keep the package light. You *must* manually install the corresponding npm package for your chosen database (e.g., `mysql2` for MySQL, `pg` for PostgreSQL, `redis` for Redis) as `ueberdb2` does not install them automatically.
  Fix: Before initializing a `Database` instance, install the required database driver: `npm install <your-database-driver-package>` (e.g., `npm install mysql2`).
• gotcha The `db.init()` method is asynchronous and *must* be awaited before any other database operations are performed. Failing to await `init()` can lead to race conditions or errors as the database connection may not be established.
  Fix: Always call `await db.init();` and ensure it completes before making `set`, `get`, `findKeys`, etc., calls.

Install

• npm install ueberdb2 npm
• yarn add ueberdb2 yarn
• pnpm add ueberdb2 pnpm

Imports

• Database
  wrong:

  const { Database } = require('ueberdb2');

  correct:

  import { Database } from 'ueberdb2';

  While CommonJS `require` still works for the main `ueberdb2` object, `Database` is a named export. For optimal compatibility and TypeScript support, ESM `import` is recommended, especially since v5.
• UeberDBInstance

  import type { UeberDBInstance } from 'ueberdb2';

  Importing types for better type checking in TypeScript projects is good practice. `UeberDBInstance` represents the instance returned by `new Database()`.
• DatabaseOptions

  import type { DatabaseOptions } from 'ueberdb2';

  Use `DatabaseOptions` type for configuring your database connection, ensuring all options are correctly typed.

Quickstart

This quickstart demonstrates initializing a MySQL database, setting and retrieving key-value pairs, accessing subkeys, setting nested subkeys, and using `findKeys` to query patterns. It highlights `async/await` usage and environment variable best practices for credentials.

import { Database } from 'ueberdb2';
import type { DatabaseOptions } from 'ueberdb2';

(async () => {
  // Example: Using MySQL. Ensure 'mysql2' package is installed: npm install mysql2
  const mysqlOptions: DatabaseOptions = {
    user: process.env.DB_USER ?? 'root',
    host: process.env.DB_HOST ?? 'localhost',
    password: process.env.DB_PASSWORD ?? '',
    database: process.env.DB_DATABASE ?? 'store',
    engine: 'InnoDB',
  };

  const db = new Database('mysql', mysqlOptions);

  try {
    await db.init();
    console.log('Database initialized successfully.');

    await db.set('myKey', { data: 'someValue', timestamp: Date.now() });
    console.log('Set myKey:', await db.get('myKey'));

    const subValue = await db.getSub('myKey', ['data']);
    console.log('Get subkey data:', subValue);

    await db.setSub('myKey', ['nested', 'prop'], 'nestedValue');
    console.log('Set nested subkey. Full object:', await db.get('myKey'));

    console.log('Finding keys matching "myK*":', await db.findKeys('myK*', null));

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