DBINFOZ Universal Database Adapter

Common errors

• Error: Cannot find module 'dbinfo'

  cause Attempting to import or require the package using the incorrect name 'dbinfo' as shown in outdated README examples, instead of the correct package name 'dbinfoz'.
  fix Change the import/require path from `'dbinfo'` to `'dbinfoz'`. For ESM: `import { getDatabaseAdapter } from 'dbinfoz';`. For CommonJS: `const { getDatabaseAdapter } = require('dbinfoz');`.

• Error: Adapter not found for type 'postgres'

  cause The required database client library (e.g., `pg` for PostgreSQL, `mysql2` for MySQL, `mssql` for MSSQL, `sqlite3` for SQLite) has not been installed alongside `dbinfoz`.
  fix Install the corresponding database client library for the adapter type you are using. For PostgreSQL, run `npm install pg`.

• Error: connect ECONNREFUSED 127.0.0.1:5432

  cause The application could not establish a connection to the database server. This usually indicates incorrect connection parameters (host, port, user, password), the database server not running, or firewall issues.
  fix Verify that your database server is running and accessible from the application's host. Double-check all connection configuration parameters (host, port, user, password, database name) for accuracy. Ensure no firewalls are blocking the connection.

Warnings

• breaking The README examples incorrectly instruct users to `require('dbinfo')`. The package name is `dbinfoz`, and the correct import path for both CommonJS and ESM should be `'dbinfoz'`. Following the README's incorrect path will result in a 'module not found' error.
  Fix: Always use `import { getDatabaseAdapter } from 'dbinfoz';` for ESM or `const { getDatabaseAdapter } = require('dbinfoz');` for CommonJS.
• gotcha DBINFOZ acts as an adapter layer but does not include the actual database client drivers (e.g., `pg`, `mysql2`, `mssql`, `sqlite3`). Users must explicitly install the appropriate driver packages for the databases they intend to connect to. Failure to do so will result in runtime errors when attempting to instantiate an adapter for that database type.
  Fix: Install necessary database drivers: `npm install pg` for PostgreSQL, `npm install mysql2` for MySQL, `npm install mssql` for MSSQL, and `npm install sqlite3` for SQLite.
• gotcha As a 0.x.x version package, DBINFOZ is not bound by semantic versioning (SemVer) and may introduce breaking changes in minor or even patch releases without prior deprecation warnings. Review release notes carefully when upgrading.
  Fix: Pin to exact versions (`"dbinfoz": "0.14.0"`) or use cautious ranges (`"dbinfoz": "^0.14.0"`) and thoroughly test when upgrading, especially in production environments.

Install

• npm install dbinfoz npm
• yarn add dbinfoz yarn
• pnpm add dbinfoz pnpm

Imports

• getDatabaseAdapter
  wrong:

  const getDatabaseAdapter = require('dbinfo');

  correct:

  import { getDatabaseAdapter } from 'dbinfoz';

  The README examples incorrectly show `require('dbinfo')`. The correct package name for import is `dbinfoz`. Since the package ships TypeScript types, ESM `import` is preferred for modern Node.js and bundler environments. CommonJS `require` should use `'dbinfoz'`.
• DatabaseAdapter

  import type { DatabaseAdapter } from 'dbinfoz';

  Import the `DatabaseAdapter` interface for type hinting when working with a database adapter instance in TypeScript.
• DatabaseConfig

  import type { DatabaseConfig } from 'dbinfoz';

  Import the `DatabaseConfig` type for defining database connection options in TypeScript, which is a union type covering various database configurations.

Quickstart

This quickstart demonstrates how to instantiate a database adapter for SQLite or PostgreSQL, list tables, retrieve a table's schema, and execute a custom query, while also showing proper type usage and environment variable integration for sensitive credentials.

import { getDatabaseAdapter } from 'dbinfoz';
import type { DatabaseConfig, DatabaseAdapter } from 'dbinfoz';

// Configuration for a SQLite database. Replace with your actual database details.
const sqliteConfig: DatabaseConfig = {
  filename: process.env.SQLITE_DB_PATH ?? './mydb.sqlite',
};

// Configuration for a PostgreSQL database. Remember to install 'pg' separately.
const postgresConfig: DatabaseConfig = {
  host: process.env.PG_DB_HOST ?? 'localhost',
  user: process.env.PG_DB_USER ?? 'yourUsername',
  database: process.env.PG_DB_NAME ?? 'yourDatabase',
  password: process.env.PG_DB_PASSWORD ?? 'yourPassword',
  port: parseInt(process.env.PG_DB_PORT ?? '5432', 10),
};

// Choose your database type and config
const type: 'sqlite' | 'postgres' = 'sqlite'; // or 'postgres', 'mysql', 'mssql'
const config = type === 'sqlite' ? sqliteConfig : postgresConfig; // Use appropriate config

(async () => {
  let dbAdapter: DatabaseAdapter | null = null;
  try {
    dbAdapter = getDatabaseAdapter(type, config);
    console.log(`Connected to ${type} database.`);

    // List tables
    const tables = await dbAdapter.listTables();
    console.log('Tables:', tables);

    // Example: Get schema for a specific table (if it exists)
    if (tables.length > 0) {
      const firstTable = tables[0];
      console.log(`Schema for table '${firstTable}':`);
      const schema = await dbAdapter.getTableSchema(firstTable);
      console.log(schema);
    }

    // Run a custom query (example: create a table for sqlite if not exists)
    if (type === 'sqlite') {
      await dbAdapter.runQuery('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);');
      console.log('Checked/created users table.');
    }

  } catch (error: any) {
    console.error('Error:', error.message);
  } finally {
    // Some adapters (like SQLite) might have a 'close' method
    if (dbAdapter && typeof (dbAdapter as any).close === 'function') {
      await (dbAdapter as any).close();
      console.log('Database connection closed.');
    }
  }
})();