RelationGen

RelationGen is a small Python command-line tool that converts a plain-text relational schema definition into an SVG diagram. It lets you describe tables, attributes, primary keys, and foreign keys in a compact DSL, then generates a clean schema visualization with orthogonal connector routing.

The repository currently contains:

• relation_gen.py — the full parser, layout engine, SVG generator, and CLI entry point
• examples/sample.rsd — a sample schema definition file
• diagram.svg — an example generated SVG output

What the project does

This project parses a custom relational-schema DSL and turns it into an SVG diagram where:

• each relation becomes a titled row
• each attribute becomes a cell in that row
• primary keys are underlined
• foreign keys are connected to referenced attributes using colored routed connector lines

The generated output is intended to be simple, readable, and easy to open in a browser or embed in documents.

Requirements

• Python 3.8+ recommended
• No third-party dependencies are required

How it works

relation_gen.py includes four main parts:

1. Parser

   • Tokenizes and parses the DSL input.
   • Builds in-memory schema objects for relations and attributes.

2. Layout Engine

   • Calculates relation and cell sizes.
   • Stacks relations vertically.
   • Routes foreign-key connectors with deterministic orthogonal paths.

3. SVG Generator

   • Draws relation titles and attribute rows.
   • Underlines primary keys.
   • Draws color-coded foreign-key arrows.

4. CLI

   • Reads the input file.
   • Parses the schema.
   • Generates the layout.
   • Writes the final SVG file.

DSL format

The input file uses a simple text format based on relation blocks.

General structure

relation RELATION_NAME {
    AttributeName : TYPE
    AnotherAttribute : TYPE PK
    ForeignKeyField : TYPE FK -> TARGET_RELATION.TargetAttribute
}

Supported markers

• PK — marks an attribute as a primary key
• FK -> Relation.Attribute — marks an attribute as a foreign key reference

Supported types

The lexer explicitly supports these types:

• INT
• VARCHAR(n)
• TEXT
• DATE
• TIMESTAMP
• BOOLEAN
• FLOAT
• CHAR(n)

Example input

From examples/sample.rsd:

relation DEPARTMENT {
    DeptID : INT PK
    DeptName : VARCHAR(100)
}

relation PROFESSOR {
    ProfessorID : INT PK
    Name : VARCHAR(100)
    Email : VARCHAR(255)
    Title : VARCHAR(50)
    DeptID : INT FK -> DEPARTMENT.DeptID
}

This produces a diagram where PROFESSOR.DeptID points to DEPARTMENT.DeptID.

Usage

Run the generator from the project root:

python relation_gen.py <inputfile> --out <output.svg>

Short form for the output flag also works:

python relation_gen.py <inputfile> -o <output.svg>

Example

python relation_gen.py examples/sample.rsd --out diagram.svg

If successful, the program prints:

Successfully generated: diagram.svg

Step-by-step instructions

1. Create or edit a schema file in the DSL format, for example my_schema.rsd.

2. Define one or more relation blocks.

3. Add attributes with supported types.

4. Mark primary keys with PK.

5. Add foreign keys using FK -> TargetRelation.TargetAttribute.

6. Run the generator:

   python relation_gen.py my_schema.rsd --out my_schema.svg

7. Open the generated SVG in a browser, image viewer, or design tool.

Example workflow

Generate the provided example diagram:

python relation_gen.py examples/sample.rsd --out diagram.svg

On Windows, you can open the result with:

start diagram.svg

Error behavior

The script exits with an error when:

• the input file does not exist
• the input cannot be read
• the DSL contains invalid syntax
• the output file cannot be written

Typical errors are printed to stderr, such as:

• Error: Input file '...' not found.
• Error parsing input: ...
• Error writing output file: ...

Notes about the current implementation

• Layout is vertical: relations are stacked from top to bottom.
• Attribute labels in cells currently display attribute names, not types.
• Connector colors and stroke widths are visually differentiated.
• Output is pure SVG with a white background.

Files in this repository

relation_gen.py

Main application file containing:

• schema data models (Attribute, Relation, Schema)
• DSL tokenizer and parser (Lexer, Parser)
• diagram layout logic (LayoutEngine)
• SVG rendering (SVGGenerator)
• command-line interface (main)

examples/sample.rsd

Sample schema describing a university/job-posting style domain with relations such as:

• DEPARTMENT
• PROFESSOR
• STUDENT
• APPLICATION
• JOB_POSTING
• SPONSOR
• FUNDS
• SPONSOR_BOOKMARK
• STUDENT_BOOKMARK

It demonstrates both simple tables and join tables with composite primary keys and foreign keys.

diagram.svg

An example generated output showing the rendered schema from the sample input.

Quick start

python relation_gen.py examples/sample.rsd --out diagram.svg
start diagram.svg

License / maintenance

No license file is currently present in this repository. Add one if you plan to distribute or publish the project more broadly.