@dforge-core/schema-importer

Convert DBML schemas into ready-to-install dForge module packages.

Takes a .dbml file describing your database schema and generates a complete module structure: entities, data views, menus, folders, security roles, and a migration notes file highlighting decisions that need manual review.

Install

npm install -g @dforge-core/schema-importer

Or run directly:

npx @dforge-core/schema-importer my-module --from-dbml schema.dbml

Usage

dforge-import <output-dir> --from-dbml <file> [options]

Options

| Option | Description | Default | |---|---|---| | --from-dbml <file> | Input DBML file (required) | | | --name <name> | Display name for the module | derived from output dir | | --no-audit-traits | Disable audit column detection | enabled | | --fk-heuristic <level> | Minimum confidence for implicit FK detection: high, medium, low | medium |

Example

Given a crm.dbml file:

Table accounts {
  account_id integer [pk, increment]
  name varchar(200) [not null]
  website varchar(255)
  credit_limit numeric(12,2)
  created_at timestamptz [default: `now()`]
  updated_at timestamptz [default: `now()`]
}

Table contacts {
  contact_id integer [pk, increment]
  account_id integer [not null]
  first_name varchar(100) [not null]
  last_name varchar(100) [not null]
  email varchar(255)
  phone varchar(50)
}

Ref: contacts.account_id > accounts.account_id

Run:

dforge-import ./crm --from-dbml crm.dbml --name "CRM"

Output:

crm/
  manifest.json
  entities/
    account.json
    contact.json
  ui/
    data_views.json
    menus.json
    folders.json
  security/
    roles.json
  MIGRATION_NOTES.md

What it does

Type inference -- Maps SQL/DBML column types to dForge field types. Uses name-based heuristics to detect email, phone, url, currency, and textarea fields beyond raw type mapping.

Relationship inference -- Processes explicit DBML Ref: declarations and detects implicit foreign keys from naming conventions (e.g. account_id -> accounts.account_id), with configurable confidence thresholds.

Audit trait detection -- Recognizes created_at/updated_at and created_by/updated_by patterns, applying the appropriate dForge trait (audit or audit-full) and hiding those columns from views.

FK + Reference pattern -- Every foreign key generates both a hidden FK column and a visible Reference column with entity linking, following dForge conventions.

Enum to dropdown -- DBML Enum types become dropdown options on the referencing field.

Lookup table detection -- Small tables (id + name only) are flagged as potential dropdown candidates in the migration notes.

Composite keys -- Tables with composite primary keys are supported without forcing an identity trait.

Programmatic API

import { parseDbml, generateModule, writeModuleToDirectory } from '@dforge-core/schema-importer';

const schema = parseDbml(dbmlSource);
const module = generateModule(schema, {
  moduleCode: 'crm',
  displayName: 'CRM',
  auditTraits: true,
  fkHeuristic: 'medium',
});
writeModuleToDirectory(module, './output/crm');

Development

npm install
npm run build
npm test

License

MIT