https://github.com/ymmy833y/dbml-relationalizer
A CLI tool that generates DBML for table relationships based on database schema information and relationship definition files
https://github.com/ymmy833y/dbml-relationalizer
cli dbml relationships
Last synced: about 1 month ago
JSON representation
A CLI tool that generates DBML for table relationships based on database schema information and relationship definition files
- Host: GitHub
- URL: https://github.com/ymmy833y/dbml-relationalizer
- Owner: Ymmy833y
- License: mit
- Created: 2025-01-13T00:20:18.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-01-25T04:41:05.000Z (9 months ago)
- Last Synced: 2025-02-25T12:31:04.401Z (8 months ago)
- Topics: cli, dbml, relationships
- Language: TypeScript
- Homepage:
- Size: 74.2 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @ymmy/dbml-relationalizer
`@ymmy/dbml-relationalizer` is a CLI tool that generates **DBML (Database Markup Language)** representations of table relationships based on **database schema information** and **relationship definition files**.
Key Features:
- Automatically generate DBML by fetching schema information from an existing database
- Allow user-defined relationship additions through a `relations.yml` file
- Provide an inference feature that infers relationships from table and column names---
## Installation
### From npm (recommended)
```bash
npm install -g @ymmy/dbml-relationalizer
```### Or, clone the repository and install locally
```bash
git clone https://github.com/Ymmy833y/dbml-relationalizer.git
cd dbml-relationalizer
npm install
npm run build
npm link # Global installation
```After installation, you can use the `relation2dbml` command in your terminal or command line.
---
## Usage
Follow the steps below to generate DBML from a database schema and a custom relationship definition file:
### 1. Create a `relations.yml` file
Refer to [relations.sample.yml](https://github.com/Ymmy833y/dbml-relationalizer/blob/master/relations.sample.yml) for an example. For more details on how to write your own definitions, see [Relationship Definition File](#relationship-definition-file-relationsyml).
### 2. Run the CLI command
For example:
```bash
relation2dbml mysql mysql://user:pass@localhost:3306/dbname -o schema.dbml
```
This connects to the specified MySQL database and processes the schema information along with any relationships defined in `relations.yml`.### 3. Check the output
- If you specify an output file (e.g., `-o schema.dbml`), the resulting DBML is saved to that file.
- If you do not specify an output file, the DBML is printed to `stdout` (the console).---
## Options
- `-o, --out-file `: Specify the output file path for the generated DBML. If omitted, the result is printed to stdout.
- `-v, --verbose`: Set log level to `debug` for more detailed logs.
- `-i, --input-file `: Specify the path to the relationship definition file (e.g., `relations.yml`). Defaults to `./relations.yml`.---
## Relationship Definition File (`relations.yml`)
If you want to define custom relationships, create a `relations.yml` file with the following structure:
```yaml
inference:
enabled: true
strategy: defaultrelations:
- parentQualifiedColumn: "users.id"
childQualifiedColumns:
- "orders.user_id"
ignoreChildQualifiedColumns:
- "some_other_table.user_id"
- parentQualifiedColumn: "products.id"
childQualifiedColumns:
- "orders.product_id"
ignoreSelfReferences: false
```### Inference Feature
The **inference** feature looks at **primary keys (PK)** and **unique keys** to guess which tables and columns may be related, and generates inferred relationships in the DBML output. You can configure this in `relations.yml` under the `inference` section:
```yaml
inference:
enabled: true
strategy: default # 'default' (e.g., users.id), or 'identical' (e.g., users.user_id)
```- `enabled` (boolean):
Set to `true` to enable inference.- `strategy` (string):
- `default`: Uses `pluralize` to get the singular form of table names and looks for `_` columns (e.g., for `users.id`, look for `user_id`).
- `identical`: Assumes child columns share the same name as the parent column (e.g., if the parent is `users.user_id`, the child is also `%.user_id`).### Defining Relationships Manually
Within the relations block, you can define relationships manually:
- `parentQualifiedColumn` (Required): Specifies the parent table’s column (wildcards not supported).
- `childQualifiedColumns` (Optional): Specifies the child table’s columns (% wildcard supported).
- `ignoreChildQualifiedColumns` (Optional): Specifies any child columns to exclude (% wildcard supported).When entering values, please use the **`tableName.columnName`** format.
#### Wildcard Examples
- `%.item_id`: Matches any `item_id` column in all tables (e.g., `foo.item_id`)
- `%.order_%date`: Matches any column in all tables that starts with `order_` and ends with `date` (e.g., `foo.order_created_date`, `foo.order_date`)---
### About Self-Referencing Relationships
Although rare, **self-referencing** relationships are also supported.
- By default, `ignoreSelfReferences` is set to `true`, so self-referencing relationships are excluded without additional configuration.
- To include self-referencing relationships, set `ignoreSelfReferences: false`.#### Example of Self-Referencing
When `ignoreSelfReferences: false` is specified, a self-referencing relationship such as the following may be generated:
```dbml
Ref "infer_fk_user_user_user_id":"user"."user_id" < "user"."user_id"
```---
## License
This tool is released under the MIT License. See the [LICENSE](LICENSE) file for details.