IDatabaseAdapter

IDatabaseAdapter

Core interface for database connectivity and operations.

Interface Definition

interface IDatabaseAdapter {
  connect(params: unknown): Promise<void>;
  prepare(query: string): Promise<IStatementAdapter>;
  exec(query: string): Promise<void>;
  transaction(fn: (items: any[]) => void): Promise<Function>;
  tableColumnInformation(tableName: string): Promise<TableColumnInfo[]>;
  tableExists(tableName: string): Promise<boolean>;
  close(): Promise<void>;
}

---

Methods

connect(params)

Establish connection to the database.

Parameters:

• params (unknown) - Database-specific connection configuration

Returns: Promise<void>

Example:

await adapter.connect({ host: 'localhost', database: 'myapp' });

---

prepare(query)

Prepare a SQL query for execution. Must convert @paramName syntax to database-specific format.

Parameters:

• query (string) - SQL query with @paramName parameters

Returns: Promise<IStatementAdapter>

Example:

const stmt = await adapter.prepare('SELECT * FROM users WHERE id = @id');
const user = await stmt.get({ id: 1 });

---

exec(query)

Execute DDL statements without returning results.

Parameters:

• query (string) - SQL query string

Returns: Promise<void>

Example:

await adapter.exec('CREATE TABLE users (id INT PRIMARY KEY, name TEXT)');

---

transaction(fn)

Execute operations within a transaction. Return commit function.

Parameters:

• fn ((items: any[]) => void) - Transaction operations

Returns: Promise<Function> - Commit function

Example:

const commit = await adapter.transaction(() => {
  // Operations here
});
await commit();

---

tableColumnInformation(tableName)

Retrieve column metadata for a table.

Parameters:

• tableName (string) - Table name

Returns: Promise<TableColumnInfo[]>

TableColumnInfo:

type TableColumnInfo = {
  cid: number; // Column position
  name: string; // Column name
  type: string; // Data type
  notnull: number; // 1 = NOT NULL, 0 = nullable
  dflt_value: string | null; // Default value
  pk: number; // 1 = primary key, 0 = not
};

---

tableExists(tableName)

Check whether a table exists in the database.

Parameters:

• tableName (string) - Table name to check

Returns: Promise<boolean>

Example:

const exists = await adapter.tableExists('users');
if (!exists) {
  console.log('Table does not exist');
}

---

close()

Close database connection and cleanup resources.

Returns: Promise<void>

---

Usage

Register adapter with Container:

import { Container } from '@iamkirbki/database-handler-core';
import { MyDatabaseAdapter } from '@yourorg/database-handler-mydatabase';

const adapter = new MyDatabaseAdapter();
await adapter.connect(config);

Container.getInstance().registerAdapter('default', adapter, true);

---

Creating Custom Adapters

See Custom Adapter Guide for complete implementation details.

Quick reference:

• Convert @paramName to your database's parameter format (?, $1, etc.)
• Query information schema for tableColumnInformation()
• Wrap statement objects with IStatementAdapter implementation
• Handle transactions with begin/commit/rollback

---

See Also

• Custom Adapter Guide - Full implementation guide
• IStatementAdapter - Statement execution interface
• ISchemaBuilder - Schema operations interface
• PostgreSQL Adapter - Reference implementation
• SQLite Adapter - Reference implementation