PyDBML

Common errors

• pydbml.exceptions.PyDBMLParsingException: Error while parsing line X: Unexpected token 'Y'

  cause The DBML input string contains a syntax error or uses a feature not yet supported by pydbml.
  fix Carefully review the DBML syntax around the indicated line `X` and column `Y`. Compare it against the official DBML specification (dbml.org) and ensure it adheres to pydbml's supported feature set. Common issues include missing commas, incorrect bracket usage, or malformed definitions.

• pydbml.exceptions.PyDBMLParsingException: Error while parsing line X: Identifier '...' contains unsupported unicode characters

  cause You are attempting to parse a DBML file that uses unicode characters in identifiers (e.g., table or column names) on `pydbml` version 1.2.0 or newer, where this feature is temporarily disabled.
  fix Modify your DBML file to use only ASCII characters for identifiers. Alternatively, if unicode identifiers are essential, consider using a `pydbml` version older than 1.2.0, acknowledging that it might not include the latest bug fixes or features.

• ImportError: cannot import name 'DBMLParser' from 'pydbml'

  cause You are trying to import a class named `DBMLParser` which does not exist in the `pydbml` library. The primary function for parsing is directly available as `parse`.
  fix Use `from pydbml import parse` to import the main parsing function. There is no `DBMLParser` class to instantiate directly.

Warnings

• breaking Unicode characters in identifiers (e.g., table or column names) are temporarily disabled starting from v1.2.0 due to performance considerations. DBML files using them will fail to parse.
  Fix: Avoid using unicode characters in identifiers in your DBML schemas. If this functionality is critical and you accept potential performance impacts, you may need to downgrade to a version prior to 1.2.0.
• gotcha SQL rendering in versions prior to 1.2.1 might incorrectly omit quotes for string default values or ignore falsy default values (e.g., 0, false) entirely.
  Fix: Upgrade to `pydbml 1.2.1` or newer to ensure correct SQL rendering of string and falsy default values in your generated DDL.
• gotcha The SQL and DBML rendering engine was significantly rewritten in v1.1.0 to support external renderers. If you rely on exact output formatting from versions older than 1.1.0, verify generated SQL/DBML after upgrading.
  Fix: Review the generated SQL/DBML output after upgrading from versions older than 1.1.0 to ensure compatibility with your existing tooling or expectations, as subtle formatting or feature interpretations may have changed.

Install

• pip install pydbml Install latest version

Imports

• parse
  wrong:

  from pydbml.parser import parse

  correct:

  from pydbml import parse

  The `parse` function is a top-level import from the `pydbml` package.

Quickstart

This quickstart demonstrates how to parse a DBML string using `pydbml.parse` and then render the parsed object to SQL DDL and back to DBML format.

from pydbml import parse

# Define a DBML string
dbml_content = """
Project "MyProject" {
    database_type: 'PostgreSQL'
    Note: 'A simple example project'
}

Table "users" {
    id int [pk, increment]
    username varchar [unique, not null]
    email varchar [unique]
    created_at timestamp [default: `now()`]
}

Table "posts" {
    id int [pk, increment]
    title varchar [not null]
    content text
    user_id int [ref: > users.id]
    created_at timestamp [default: `now()`]
}
"""

# Parse the DBML content
try:
    parsed_dbml = parse(dbml_content)
    print("DBML parsed successfully.")

    # Render to SQL DDL
    sql_output = parsed_dbml.sql()
    print("\n--- Generated SQL ---")
    print(sql_output)

    # Optionally, render back to DBML (can differ slightly in formatting)
    dbml_output = parsed_dbml.dbml()
    print("\n--- Generated DBML (re-rendered) ---")
    print(dbml_output)

except Exception as e:
    print(f"An error occurred during parsing or rendering: {e}")