Skip to content

Home

Jump to bottom
do- edited this page Apr 28, 2025 · 161 revisions

doix-db is an extension to the doix framework for working with relational databases.

tl;dr

Start a trivial Web service project with doix-http, add a connection to PostgreSQL or to ClickHouse and hack on.

Description

Basically, this is the common RDB interface for doix, the same as ODBC for Windows, JDBC for Java and so on.

But, aside from only processing given statements, it offers several SQL generation features.

Connection & Basic Usage

For an Application to operate on a database, you have to register therein the properly configured vendor specific DbPool:

const {DbPoolPg} = require ('doix-db-postgresql')
// const {DbPoolCh} = require ('doix-db-clickhouse')

///...
      pools: {
        db        : new DbPoolPg (conf.db),       
//      dbArchive : new DbPoolCh (conf.dbArchive),
      },
///...

Then, corresponding DbClient instances will be automatically injected in execution contexts:

const dt = await this.db.getScalar ('SELECT CURRENT_DATE')
//         await this.dbArchive.do ('ALTER TABLE facts DROP PARTITION ?', [dt])

Asynchronous methods can be called right away; initialization and cleanup are up to doix internals.

Just in case, the hosting application is always visible with all its internals, including pools Map, so developers may operate on it directly, at their own risk:

this.app.pools.get ('db').pool.end () // see https://node-postgres.com/apis/pool#poolend

Executing Arbitrary SQL

What application developers mostly need here, are the next methods:

These ones are all wrappers around one basic method absent from the common doix-db library and implemented in each vendor specific extension.

Like every process in doix, each SQL statement execution is transparently logged, with references to the containing job.

Model Based SQL Generation

Far from embracing the MDA approach in its totality, doix-db is developed keeping in mind that an application must be aware of, and effectively use meta information about data structures in operates on. Even more, a well designed application must keep the image of the required structure of its database and should be able to upgrade the actual (maybe outdated) one to that target state: primarily, with automatic migrations during deployments.

To this end, doix-db offers DbModel: the class implementing a metainformation store loadable from modules, along with Application's ones. Each of such modules describes a table, sql view or another database object.

A DbModel instance can be passed to a DbPool constructor. In this case, each related DbClient, say this.db, receives the corresponding this.db.model, which makes metadata available to use in API calls described further.

Reference

Clone this wiki locally