4383 / pydbml

DBML parser and builder for Python

DBML parser for Python

Compliant with DBML v2.5.3 syntax

PyDBML is a Python parser and builder for DBML syntax.

The project was rewritten in May 2022, the new version 1.0.0 is not compatible with versions 0.x.x. See details in Upgrading to PyDBML 1.0.0.

Docs:

• Class Reference
• Creating DBML schema
• Upgrading to PyDBML 1.0.0

PyDBML requires Python v3.8 or higher

Installation

You can install PyDBML using pip:

pip3 install pydbml

Quick start

To parse a DBML file, import the PyDBML class and initialize it with Path object

>>> from pydbml import PyDBML
>>> from pathlib import Path
>>> parsed = PyDBML(Path('test_schema.dbml'))

or with file stream

>>> with open('test_schema.dbml') as f:
...     parsed = PyDBML(f)

or with entire source string

>>> with open('test_schema.dbml') as f:
...     source = f.read()
>>> parsed = PyDBML(source)
>>> parsed
<Database>

The parser returns a Database object that is a container for the parsed DBML entities.

You can access tables inside the tables attribute:

>>> for table in parsed.tables:
...     print(table.name)
...
orders
order_items
products
users
merchants
countries

Or just by getting items by index or full table name:

>>> parsed[1]
<Table 'public' 'order_items'>
>>> parsed['public.countries']
<Table 'public' 'countries'>

Other attributes are:

• refs — list of all references,
• enums — list of all enums,
• table_groups — list of all table groups,
• project — the Project object, if was defined.

Generate SQL for your DBML Database by accessing the sql property:

>>> print(parsed.sql)  # doctest:+ELLIPSIS
CREATE TYPE "orders_status" AS ENUM (
  'created',
  'running',
  'done',
  'failure',
);
<BLANKLINE>
CREATE TYPE "product status" AS ENUM (
  'Out of Stock',
  'In Stock',
);
<BLANKLINE>
CREATE TABLE "orders" (
  "id" int PRIMARY KEY AUTOINCREMENT,
  "user_id" int UNIQUE NOT NULL,
  "status" "orders_status",
  "created_at" varchar
);
...

Generate DBML for your Database by accessing the dbml property:

>>> parsed.project.items['author'] = 'John Doe'
>>> print(parsed.dbml)  # doctest:+ELLIPSIS
Project "test_schema" {
    author: 'John Doe'
    Note {
        'This schema is used for PyDBML doctest'
    }
}
<BLANKLINE>
Enum "orders_status" {
    "created"
    "running"
    "done"
    "failure"
}
<BLANKLINE>
Enum "product status" {
    "Out of Stock"
    "In Stock"
}
<BLANKLINE>
Table "orders" {
    "id" int [pk, increment]
    "user_id" int [unique, not null]
    "status" "orders_status"
    "created_at" varchar
}
<BLANKLINE>
Table "order_items" {
    "order_id" int
    "product_id" int
    "quantity" int [default: 1]
}
...