Generathor-DB

Generathor-DB is a powerful introspection engine that retrieves the structure of your database (MySQL and PostgreSQL) and standardizes it into a consistent format.

Designed to work seamlessly with Generathor, it enables automatic generation of models, controllers, migrations, and more, by providing a high-level abstraction of your database schema.

Features

• 🔍 Introspection: Deeply scans tables, columns, indexes, primary keys, and relations.
• 🐘 PostgreSQL & 🐬 MySQL Support: Built-in support for the most popular relational databases.
• 🔧 Transformers: Modify and enrich the scanned data before handing it over to your generators.

Installation

npm install generathor-db

[!IMPORTANT] Since drivers are lazy-loaded, you must install the driver for your database manually:

• For MySQL: npm install mysql2
• For PostgreSQL: npm install pg

Usage

Simple Example (MySQL)

import { Source } from 'generathor-db';

const source = new Source({
  type: 'mysql',
  configuration: {
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'password',
    database: 'my_app'
  }
});

PostgreSQL with Transformers

import { Source } from 'generathor-db';

const source = new Source({
  type: 'postgresql',
  configuration: {
    host: 'localhost',
    port: 5432,
    user: 'postgres',
    password: 'password',
    database: 'my_app',
    schema: 'public' // Optional, defaults to 'public'
  }
}, [
  (item) => {
    // Add custom metadata for your generators
    item.className = item.table.charAt(0).toUpperCase() + item.table.slice(1);
  }
]);

API Documentation

Source

The constructor accepts the following parameters:

| Parameter | Type | Required | Description | |-------------------------|-----------------|----------|--------------------------------------------------| | sourceConfiguration | EngineInput | Yes | Connection and configuration options. | | transformers | Transformer[] | No | Array of functions to modify items after scanning. |

Transformer

A simple callback used to modify or enrich an Item before it is consumed.

type Transformer = (item: Item) => void;

Engine Configurations

Engine Input

The sourceConfiguration (or EngineInput in TypeScript) defines which database to scan and how to connect to it.

| Field | Type | Required | Description | |-----------------|----------------------------------------------------|----------|------------------------------------------------| | type | 'mysql' | 'postgresql' | Yes | The database engine type. | | configuration | MySQLConfiguration | PostgreSQLConfiguration | Yes | Engine-specific connection details. | | excludes | string[] | No | List of table names to ignore during scanning. |

MySQL Configuration

| Field | Type | Required | Description | |------------|----------|----------|----------------------------| | host | string | Yes | Database host. | | port | number | Yes | Database port (e.g. 3306). | | user | string | Yes | Database username. | | password | string | Yes | Database password. | | database | string | Yes | Database name. |

PostgreSQL Configuration

| Field | Type | Required | Description | |-------------------------------|-----------|----------|--------------------------------------------------------| | host | string | Yes | Database host. | | port | number | Yes | Database port (e.g. 5432). | | user | string | Yes | Database username. | | password | string | Yes | Database password. | | database | string | Yes | Database name. | | schema | string | No | Introspected schema (defaults to 'public'). | | includeForeignKeysAsIndexes | boolean | No | Treat FKs as indexes (defaults to false). |

Standardized Format (Item)

Each item represent a table in your database.

| Property | Type | Required | Description | |--------------|-----------------------|----------|-------------------------------------| | table | string | Yes | Table name. | | schema | string | Yes | Schema or database name. | | columns | Column[] | Yes | Array of column definitions. | | indexes | Index[] | Yes | Array of index definitions. | | relations | Relation[] | Yes | Foreign key relationships. | | primaryKey | { columns: string[] } | Yes | List of primary key columns. |

Column Detail

| Property | Type | Required | Description | |-----------------|------------|----------|----------------------------------------------| | name | string | Yes | Column name. | | type | string | Yes | Canonical type (string, int, date, boolean, float). | | subType | string | No | More specific type (e.g. datetime, json). | | nullable | boolean | Yes | Whether it accepts NULL. | | default | any | Yes | Default value. | | comment | string | Yes | Database comment/description. | | unsigned | boolean | No | Whether it's numeric unsigned. | | autoincrement | boolean | No | Whether it's an identity/auto-increment. | | size | number | No | Max length or precision. | | scale | number | No | Decimal scale. | | enum | string[] | No | Allowed values for enum types. |

Index Detail

| Property | Type | Required | Description | |-----------|---------------------|----------|------------------------------------| | type | 'unique' | 'index' | Yes | Type of index (unique or regular). | | columns | string[] | Yes | Columns involved in the index. | | index | string | Yes | Name of the index. |

Relation Detail

| Property | Type | Required | Description | |---------------|----------------------------|----------|----------------------------------------------| | type | 'belongs-to' | 'has-many' | Yes | Type of relationship between tables. | | columns | string[] | Yes | Columns involved in the relationship. | | references | string[] | Yes | Columns referenced in the related table. | | on | object | Yes | Details of the related table. | | on.database | string | Yes | Schema/Database of the related table. | | on.table | string | Yes | Name of the related table. |