{"id":16564,"library":"ueberdb2","title":"UeberDB2: Abstract Your Databases","description":"ueberdb2 is a Node.js library that provides a high-level abstraction layer over various database systems, allowing them to be used as simple key-value stores. It currently stands at version 5.0.48 and generally follows a release cadence driven by bug fixes, dependency updates, and new database support. Key differentiators include its ability to use a cache and buffer for performance optimization, reducing database transaction overhead through bulk writing, and offering a unified API across a wide array of database backends like MySQL, PostgreSQL, MongoDB, Redis, SQLite, Elasticsearch, and SurrealDB. It supports complex JSON objects and provides methods for getting and setting subkeys, making it versatile for diverse data storage needs.","status":"active","version":"5.0.48","language":"javascript","source_language":"en","source_url":"https://github.com/ether/ueberDB","tags":["javascript","database","keyvalue","typescript"],"install":[{"cmd":"npm install ueberdb2","lang":"bash","label":"npm"},{"cmd":"yarn add ueberdb2","lang":"bash","label":"yarn"},{"cmd":"pnpm add ueberdb2","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { Database } = require('ueberdb2');","symbol":"Database","correct":"import { Database } from 'ueberdb2';"},{"note":"Importing types for better type checking in TypeScript projects is good practice. `UeberDBInstance` represents the instance returned by `new Database()`.","symbol":"UeberDBInstance","correct":"import type { UeberDBInstance } from 'ueberdb2';"},{"note":"Use `DatabaseOptions` type for configuring your database connection, ensuring all options are correctly typed.","symbol":"DatabaseOptions","correct":"import type { DatabaseOptions } from 'ueberdb2';"}],"quickstart":{"code":"import { Database } from 'ueberdb2';\nimport type { DatabaseOptions } from 'ueberdb2';\n\n(async () => {\n  // Example: Using MySQL. Ensure 'mysql2' package is installed: npm install mysql2\n  const mysqlOptions: DatabaseOptions = {\n    user: process.env.DB_USER ?? 'root',\n    host: process.env.DB_HOST ?? 'localhost',\n    password: process.env.DB_PASSWORD ?? '',\n    database: process.env.DB_DATABASE ?? 'store',\n    engine: 'InnoDB',\n  };\n\n  const db = new Database('mysql', mysqlOptions);\n\n  try {\n    await db.init();\n    console.log('Database initialized successfully.');\n\n    await db.set('myKey', { data: 'someValue', timestamp: Date.now() });\n    console.log('Set myKey:', await db.get('myKey'));\n\n    const subValue = await db.getSub('myKey', ['data']);\n    console.log('Get subkey data:', subValue);\n\n    await db.setSub('myKey', ['nested', 'prop'], 'nestedValue');\n    console.log('Set nested subkey. Full object:', await db.get('myKey'));\n\n    console.log('Finding keys matching \"myK*\":', await db.findKeys('myK*', null));\n\n  } catch (error) {\n    console.error('Database operation failed:', error);\n  } finally {\n    await db.close();\n    console.log('Database connection closed.');\n  }\n})();","lang":"typescript","description":"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."},"warnings":[{"fix":"Refactor all database interactions to use `await` with the returned Promises or `.then/.catch`.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js environment to version 18.0.0 or higher. Consider using an LTS version for production.","message":"The minimum supported Node.js version is now 18.0.0. Running `ueberdb2` on older Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Before initializing a `Database` instance, install the required database driver: `npm install <your-database-driver-package>` (e.g., `npm install mysql2`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always call `await db.init();` and ensure it completes before making `set`, `get`, `findKeys`, etc., calls.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const ueberdb = require('ueberdb2'); const db = new ueberdb.Database(...)`. For ESM, use `import { Database } from 'ueberdb2'; const db = new Database(...)`.","cause":"Attempting to destructure `Database` from a CommonJS `require('ueberdb2')` without correctly accessing the `Database` property on the default export.","error":"TypeError: ueberdb.Database is not a constructor"},{"fix":"Install the required database driver package: `npm install <driver-name>` (e.g., `npm install mysql2`).","cause":"The npm package for the specified database driver (e.g., `mysql2`, `pg`, `redis`) is not installed in your project's `node_modules`.","error":"Error: Driver for <database-type> not found or could not be loaded. Please ensure the corresponding npm package is installed."},{"fix":"Wrap `await` calls in `try...catch` blocks or chain `.catch()` to handle potential errors from asynchronous database operations.","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.","error":"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()."},{"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.","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.","error":"Error: connect ECONNREFUSED <host>:<port>"}],"ecosystem":"npm"}