collimator

Collimator

Collimator is a JavaScript library that uses reflection techniques to introspect PostgreSQL databases:

• Enumerate table names and identify primary keys
• Generate JSON Schema v4 for a given table
• Extract table relationship information using foreign key constraints

Why?

Traditionally, programmers have defined their schema by writing model definitions in application code. Some kind of migration tool then transforms this schema into SQL, and applies it against a database.

Collimator allows this pattern to be reversed. The database now becomes the canonical source of your application's schema and relationship metadata.

Prior Art

The approach to schema extraction is inspired by DDL.js. Collimator's implementation is currently not as robust as DDL.js, and only targets PostgreSQL (an intentional design decision, and unlikely to change). However, Collimator supports the extraction of relationship information.

Installation

Install as a dependency in your application with npm install --save collimator.

Usage

Enumerate table names and primary keys with collimator.tables(db).

Generate JSON Schema with collimator.schema(db, 'tableName').

Extract relationship information with collimator.relationships(db, 'tableName').

The top-level Collimator functions (tables, schema and relationships) accept a pg-promise connection as their first argument, and return a promise. For further guidance, please refer to the examples and API Documentation.

Change Log

Please consult the Change Log for detailed notes on each release.

Development

Install dependencies with:

npm install

Run the tests with:

gulp

Run unit test coverage with:

gulp coverage

Update API documentation with:

gulp docs

Enter development mode with:

gulp dev

This will watch the src and spec directories and run gulp automatically when a change is detected. Note that it will not run the tests until it detects a change, so you may prefer to run it with gulp & gulp dev.