Alinex Database Abstraction

1.1.2 verified Wed Apr 22 auth: no javascript

Alinex Database is a Node.js module that provides a comprehensive database abstraction layer, designed to simplify interactions with various relational database management systems (RDBMS) such as MySQL and PostgreSQL. Currently at version 1.1.2, this library offers key features including robust connection pooling, support for database clustering, automatic SSH tunneling for secure connections, and an object-to-query language builder. It aims for ease of configuration and use across different database types, integrating closely with the broader Alinex Namespace ecosystem for configuration management. While a specific release cadence isn't detailed, the project appears actively maintained, offering a stable API for its stated features. Its primary differentiators lie in its bundled advanced connection management capabilities and integrated query building, aiming to reduce boilerplate for common database operations.

Warnings

gotcha The library's API is heavily callback-based. Developers accustomed to modern JavaScript's Promise-based or async/await patterns will need to manually wrap or promisify the asynchronous functions. ↓

fix Use `util.promisify` for individual functions (e.g., `promisify(db.connect)`) or create custom Promise wrappers to adapt the API.

gotcha Database connection configurations are expected to be managed externally via the `alinex-config` module. Failing to provide a correct configuration for the requested instance name will lead to errors during instance creation. ↓

fix Ensure `alinex-config` is correctly set up in your project, with a 'database' section defining the required connection parameters for each named instance.

gotcha All database connections obtained from the pool via `db.connect()` must be explicitly released using `conn.release()` once they are no longer needed. Failure to release connections will lead to resource exhaustion and application instability. ↓

fix Always call `conn.release()` in both success and error paths within your callback logic, or ensure it's in a `finally` block if using Promise-wrapped functions.

Install

npm install alinex-database

yarn add alinex-database

pnpm add alinex-database

Imports

database
wrong
```
import database from 'alinex-database'
```
correct
```
const database = require('alinex-database')
```
The primary way to import the library in v1.x, as shown in the documentation, is via CommonJS `require`. Direct ESM `import` might not be fully supported or require a CommonJS interop wrapper.
instance
wrong
```
new database.Instance()
```
correct
```
database.instance('connectionName', (err, db) => { /* ... */ })
```
Database instances are obtained asynchronously through a static `instance` method on the main `database` export, utilizing a callback pattern, not via a constructor.
connect
wrong
```
db.getConnection()
```
correct
```
db.connect((err, conn) => { /* ... */ })
```
Connections are acquired from the database pool via an asynchronous `connect` method on the database instance, also using a callback. Ensure this connection is released when done.

Quickstart

This quickstart demonstrates the core workflow: obtaining a database instance, connecting to it from the pool, executing a simple SQL query, and ensuring proper connection release and database instance closure using callback functions.

const database = require('alinex-database');

// This example assumes a 'test-mysql' configuration is set up
// in your alinex-config. For example, in a config file:
// database:
//   test-mysql:
//     type: 'mysql'
//     host: 'localhost'
//     user: 'root'
//     password: 'password'
//     database: 'test_db'

database.instance('test-mysql', (err, db) => {
  if (err) {
    console.error('Error getting database instance:', err);
    return;
  }
  console.log('Database instance for "test-mysql" obtained.');

  db.connect((err, conn) => {
    if (err) {
      console.error('Error connecting to database:', err);
      return;
    }
    console.log('Connected to database. Executing query...');

    conn.query('SELECT 2 + 2 AS solution', (err, rows, fields) => {
      if (err) {
        console.error('Error executing query:', err);
        conn.release(); // Release connection even on query error
        return;
      }

      console.log('Query result: The database calculated 2+2 =', rows[0].solution);
      conn.release(); // Release connection back to the pool
      console.log('Connection released.');

      db.close((err) => {
        if (err) {
          console.error('Error closing database:', err);
          return;
        }
        console.log('Database instance closed successfully.');
      });
    });
  });
});