{"id":16599,"library":"alinex-database","title":"Alinex Database Abstraction","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/alinex/node-database","tags":["javascript","database","mysql","postgres","postgresql","rdbms"],"install":[{"cmd":"npm install alinex-database","lang":"bash","label":"npm"},{"cmd":"yarn add alinex-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add alinex-database","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The library relies on `alinex-config` for external database connection configurations, which is crucial for instance creation.","package":"alinex-config","optional":false},{"reason":"An optional native driver that can be installed for improved performance with PostgreSQL databases.","package":"pq-native","optional":true}],"imports":[{"note":"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.","wrong":"import database from 'alinex-database'","symbol":"database","correct":"const database = require('alinex-database')"},{"note":"Database instances are obtained asynchronously through a static `instance` method on the main `database` export, utilizing a callback pattern, not via a constructor.","wrong":"new database.Instance()","symbol":"instance","correct":"database.instance('connectionName', (err, db) => { /* ... */ })"},{"note":"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.","wrong":"db.getConnection()","symbol":"connect","correct":"db.connect((err, conn) => { /* ... */ })"}],"quickstart":{"code":"const database = require('alinex-database');\n\n// This example assumes a 'test-mysql' configuration is set up\n// in your alinex-config. For example, in a config file:\n// database:\n//   test-mysql:\n//     type: 'mysql'\n//     host: 'localhost'\n//     user: 'root'\n//     password: 'password'\n//     database: 'test_db'\n\ndatabase.instance('test-mysql', (err, db) => {\n  if (err) {\n    console.error('Error getting database instance:', err);\n    return;\n  }\n  console.log('Database instance for \"test-mysql\" obtained.');\n\n  db.connect((err, conn) => {\n    if (err) {\n      console.error('Error connecting to database:', err);\n      return;\n    }\n    console.log('Connected to database. Executing query...');\n\n    conn.query('SELECT 2 + 2 AS solution', (err, rows, fields) => {\n      if (err) {\n        console.error('Error executing query:', err);\n        conn.release(); // Release connection even on query error\n        return;\n      }\n\n      console.log('Query result: The database calculated 2+2 =', rows[0].solution);\n      conn.release(); // Release connection back to the pool\n      console.log('Connection released.');\n\n      db.close((err) => {\n        if (err) {\n          console.error('Error closing database:', err);\n          return;\n        }\n        console.log('Database instance closed successfully.');\n      });\n    });\n  });\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Use `util.promisify` for individual functions (e.g., `promisify(db.connect)`) or create custom Promise wrappers to adapt the API.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `alinex-config` is correctly set up in your project, with a 'database' section defining the required connection parameters for each named instance.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[],"ecosystem":"npm"}