databricks-schema 0.8.0__tar.gz → 0.10.0__tar.gz

{databricks_schema-0.8.0 → databricks_schema-0.10.0}/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Project
 
-`databricks-schema` — CLI + Python library that extracts, diffs, and generates SQL for Databricks Unity Catalog schemas stored as YAML or JSON files (one file per schema). Pydantic v2 models serve as the intermediate representation for future bidirectional sync.
+`databricks-schema` — CLI + Python library that extracts, diffs, and generates SQL for Databricks Unity Catalog schemas stored as YAML or JSON files (one file per schema) or DBML (one file per catalog). Pydantic v2 models serve as the intermediate representation for future bidirectional sync.
 
 ## Key commands
 
@@ -18,9 +18,10 @@ uv run databricks-schema --help
 
 ```
 databricks_schema/
-  models.py      # Pydantic v2 models: Catalog, Schema, Table, Column, PrimaryKey, ForeignKey
+  models.py      # Pydantic v2 models: Catalog, Schema, Table, Column, PrimaryKey, ForeignKey (Schema/Table carry grants)
   extractor.py   # CatalogExtractor — wraps databricks-sdk
-  yaml_io.py     # schema/catalog to/from YAML and JSON; _strip_empty removes None + empty collections
+  yaml_io.py     # schema/catalog to/from YAML and JSON; _strip_empty removes None + empty collections; load_schema_dir (all formats)
+  dbml_io.py     # schema/catalog to/from DBML; own writer, PyDBML grammar for parsing
   diff.py        # diff_schemas / diff_catalogs / diff_catalog_with_dir / diff_schema_dirs; FieldChange, ColumnDiff, TableDiff, SchemaDiff, CatalogDiff
   sql_gen.py     # schema_diff_to_sql — pure SQL generation from SchemaDiff; no SDK/IO
   cli.py         # argparse CLI: extract, diff, generate-sql, validate, diff-files, list-catalogs, list-schemas
@@ -29,6 +30,7 @@ tests/
   test_models.py
   test_extractor.py  # all SDK calls mocked with MagicMock
   test_yaml_io.py
+  test_dbml_io.py
   test_diff.py       # pure model comparison, no SDK calls
   test_sql_gen.py    # pure SQL generation tests, no SDK calls
   test_validate.py
@@ -49,18 +51,25 @@ skills/databricks-schema-cli/SKILL.md  # Agent Skill: teaches an AI agent to dri
 - Column order in YAML = SDK position (None → 9999)
 - `_strip_empty`: removes `None` and empty `dict`/`list`; preserves `False`, `0`, empty strings
 - `yaml_io.py` has parallel YAML and JSON functions (`schema_to_yaml`/`schema_to_json`, etc.)
-- `diff_catalog_with_dir` accepts `fmt: Literal["yaml", "json"] = "yaml"` to select file format
+- `diff_catalog_with_dir` / `diff_schema_dirs` / `load_schema_dir` take `fmt: SchemaFormat` (`"yaml" | "json" | "dbml"`, default `"yaml"`)
+- DBML is one document per catalog (`extract -f dbml -o DIR` writes `DIR/<catalog>.dbml`): Catalog → `Project`, Schema → `TableGroup` (always emitted), PK → `indexes { (...) [pk] }`, FK → `Ref`
+- DBML has no key/value metadata: tags/grants/owner/table_type/storage_location are trailing `@key: value` lines in notes (`@tags`/`@grants` = JSON objects); writer output must round-trip exactly and stay parseable by `@dbml/core`
+- PyDBML is optional (`databricks-schema[dbml]` extra; also in the `dev` group): `dbml_io` imports it in a top-level `try/except ImportError` setting `PYDBML_AVAILABLE`; writing DBML must never need it, readers raise `DbmlDependencyError` (CLI exits 2)
+- `dbml_io` parses via PyDBML's grammar (`pydbml.definitions`) but resolves refs itself, so refs to tables outside the file are kept; never build a PyDBML `Database` (it rejects such refs and reflows note text) and never use PyDBML's renderer (it leaves complex types unquoted)
+- For DBML directories, `--schema` filters match schema names (YAML/JSON match file stems)
 - CLI: catalog is a required positional argument (not a flag)
-- `extract` `--format`/`-f` selects output format (`yaml` default, `json` opt-in); dest is `fmt`
-- `diff` auto-detects format from files present in the directory; exits 2 on mixed YAML+JSON
+- `extract` `--format`/`-f` selects output format (`yaml` default, `json`/`dbml` opt-in); dest is `fmt`
+- `diff` auto-detects format from files present in the directory; exits 2 on mixed formats
 - `diff`'s second positional arg is a directory if one exists at that path, else a second catalog name (`diff_catalogs`); first `catalog` arg is always the live side
 - `TableType` is re-exported from `databricks.sdk.service.catalog` — do not redefine it
 - `--include-metadata` flag (on `extract`, `diff`, `generate-sql`, `diff-files`) adds `owner` to output/comparison; `extract` additionally includes `storage_location` in its output (not compared by `diff`/`generate-sql`/`diff-files`); excluded by default
 - `--include-tags` flag (on `extract`, `diff`, `generate-sql`) enables Unity Catalog tag lookups; excluded by default
+- `--include-grants` flag (on `extract`, `diff`, `generate-sql`, `diff-files`) adds `grants: dict[str, list[str]]` (principal → sorted privileges) on `Schema`/`Table` via `grants.list()` — direct grants only, never inherited/effective ones; diff functions take `include_grants` and ignore grants otherwise; a grants `FieldChange` holds only differing principals
+- `generate-sql` emits `GRANT` for stored-not-live privileges and `REVOKE` for live-not-stored; `REVOKE` is destructive and follows `--allow-drop`
 - `--quiet`/`-q` flag (on `extract`, `diff`, `generate-sql`, `diff-files`) raises the log level to suppress progress messages; errors always print
 - `diff` command exits 0 (no changes) or 1 (differences found) — useful in CI
 - Diff result types are dataclasses (not Pydantic); comparison functions are pure (no SDK calls)
-- `generate-sql` auto-detects format from files; exits 2 on mixed YAML+JSON or empty directory
+- `generate-sql` auto-detects format from files; exits 2 on mixed formats or empty directory; invalid DBML exits 2
 - `generate-sql` destructive statements commented out by default; `--allow-drop` emits real DROPs
 - `sql_gen.py` is pure (no SDK, no I/O); diff direction: `FieldChange.old` = stored (target), `.new` = live
 - FK refs in SQL use same catalog as the source table (`ref_schema` + `ref_table` from model)

{databricks_schema-0.8.0 → databricks_schema-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: databricks-schema
-Version: 0.8.0
+Version: 0.10.0
 Summary: Databricks Unity Catalog schema extractor
 Project-URL: Homepage, https://github.com/frizzleqq/databricks-schema
 Project-URL: Repository, https://github.com/frizzleqq/databricks-schema
@@ -18,14 +18,16 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
-Requires-Dist: databricks-sdk>=0.64.0
+Requires-Dist: databricks-sdk>=0.121.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
+Provides-Extra: dbml
+Requires-Dist: pydbml<2,>=1.2.1; extra == 'dbml'
 Description-Content-Type: text/markdown
 
 # databricks-schema
 
-A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas in YAML format. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
+A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas as YAML, JSON or [DBML](https://dbml.dbdiagram.io/docs/) files. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
 
 ## Getting Started
 
@@ -129,12 +131,18 @@ name: main
 comment: Main production schema
 tags:
   env: prod
+grants:
+  analysts:
+    - USE_SCHEMA
 tables:
   - name: users
     table_type: MANAGED
     comment: User accounts
     tags:
       domain: identity
+    grants:
+      analysts:
+        - SELECT
     columns:
       - name: id
         data_type: bigint
@@ -158,6 +166,64 @@ tables:
           - id
 ```
 
+### DBML
+
+Writing DBML works out of the box; reading it back (`diff`, `generate-sql`, `validate`, `diff-files`, `catalog_from_dbml`) needs the optional `dbml` extra, which installs [PyDBML](https://github.com/Vanderhoof/PyDBML):
+
+```bash
+pip install 'databricks-schema[dbml]'
+uv tool install 'databricks-schema[dbml]'
+```
+
+Without it, those commands exit `2` with a message saying how to install it.
+
+Use `--format dbml` to write the catalog as a single [DBML](https://dbml.dbdiagram.io/docs/) document — `{output-dir}/{catalog}.dbml` with `--output-dir`, or stdout without. Unlike YAML/JSON, DBML is one file per catalog, so that foreign keys between schemas resolve within the file. Paste it into [dbdiagram.io](https://dbdiagram.io) for an ER diagram, or point `diff`, `generate-sql`, `validate` and `diff-files` at the directory just like a YAML/JSON one.
+
+```dbml
+Project "prod_catalog" {
+    database_type: 'Databricks'
+}
+
+TableGroup "main" [note: 'Main production schema'] {
+    "main"."users"
+}
+
+Table "main"."users" {
+    "id" bigint [not null, note: 'Primary key']
+    "email" string
+    "org_id" bigint
+    "settings" "struct<theme:string,beta:boolean>"
+
+    indexes {
+        ("id") [pk, name: 'pk_users']
+    }
+
+    Note: '''User accounts
+
+@table_type: MANAGED
+@tags: {"domain": "identity"}'''
+}
+
+Ref "fk_org": "main"."users"."org_id" > "orgs"."organizations"."id"
+```
+
+How the model maps to DBML:
+
+| Model | DBML |
+|---|---|
+| Catalog | `Project` (comment in its `Note`) |
+| Schema | `TableGroup` named after the schema (comment in its `note`); written for every schema, so empty schemas survive |
+| Table / column comment | `Note` / `note:` |
+| `nullable: false` | `not null` |
+| Primary key | `indexes { (...) [pk, name: '...'] }` |
+| Foreign key | `Ref "<name>": ... > ...` |
+| Complex types (`struct<...>`, `map<...>`) | double-quoted type |
+| `tags`, `grants`, `owner`, `table_type`, `storage_location` | trailing `@key: value` lines in the note (`@tags` and `@grants` are JSON objects) |
+
+Everything round-trips: reading a written file gives back exactly the extracted model. Hand-written DBML (e.g. exported from dbdiagram) is accepted too — tables without a schema land in `public`, column `pk` and inline `ref:` settings are understood, and constructs with no Unity Catalog equivalent (enums, sticky notes, other indexes, defaults, many-to-many refs, TableGroups that don't match a schema) are ignored. A directory may hold several `.dbml` files, but each schema may be defined in only one of them.
+
+### Catalog document
+
 Without `--output-dir`, `extract` prints a single `Catalog` document to stdout instead — the same schema shape nested under a `schemas` list, with the catalog name as a top-level field:
 
 ```yaml
@@ -231,12 +297,24 @@ Include Unity Catalog tags in the output (extra API calls per entity; excluded b
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-tags
 ```
 
+Include grants (principal → privileges) on schemas and tables. Only grants made directly on each object are extracted — privileges inherited from a parent catalog or schema are left out, so they don't show up repeatedly on every child (one extra API call per schema/table; excluded by default):
+
+```bash
+databricks-schema extract <catalog> --output-dir ./schemas/ --include-grants
+```
+
 Include additional metadata (`owner`, `storage_location`) in the output:
 
 ```bash
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-metadata
 ```
 
+Write a single DBML file (`./schemas/<catalog>.dbml`) instead — see [DBML](#dbml):
+
+```bash
+databricks-schema extract <catalog> --output-dir ./schemas/ --format dbml
+```
+
 Control the number of parallel workers (default: 4), useful for large schemas with many tags:
 
 ```bash
@@ -245,7 +323,7 @@ databricks-schema extract <catalog> --output-dir ./schemas/ --workers 8
 
 ### `diff`
 
-Compare the live catalog against previously extracted schema files (format auto-detected from the directory — YAML or JSON, not mixed):
+Compare the live catalog against previously extracted schema files (format auto-detected from the directory — YAML, JSON or DBML, not mixed):
 
 ```bash
 databricks-schema diff <catalog> ./schemas/
@@ -289,6 +367,12 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema diff <catalog> ./schemas/ --include-metadata
 ```
 
+Include direct grants in the comparison (excluded by default; without it, grants in the files are ignored):
+
+```bash
+databricks-schema diff <catalog> ./schemas/ --include-grants
+```
+
 Get the same comparison as structured JSON or YAML instead of the `+`/`-`/`~` tree (exit codes unchanged) — useful for scripts or agents:
 
 ```bash
@@ -298,7 +382,7 @@ databricks-schema diff <catalog> ./schemas/ --format yaml
 
 ### `generate-sql`
 
-Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected, YAML or JSON, not mixed). Statements are printed to stdout by default:
+Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected — YAML, JSON or DBML, not mixed). Statements are printed to stdout by default:
 
 ```bash
 databricks-schema generate-sql <catalog> ./schemas/
@@ -310,7 +394,7 @@ Write one `.sql` file per schema to a directory instead:
 databricks-schema generate-sql <catalog> ./schemas/ --output-dir ./migrations/
 ```
 
-Destructive statements (`DROP SCHEMA`, `DROP TABLE`, `DROP COLUMN`) are emitted as SQL comments by default. Pass `--allow-drop` to emit them as executable statements:
+Destructive statements (`DROP SCHEMA`, `DROP TABLE`, `DROP COLUMN`, `REVOKE`) are emitted as SQL comments by default. Pass `--allow-drop` to emit them as executable statements:
 
 ```bash
 databricks-schema generate-sql <catalog> ./schemas/ --allow-drop
@@ -334,6 +418,12 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema generate-sql <catalog> ./schemas/ --include-metadata
 ```
 
+Include direct grants in the comparison, emitting `GRANT` for privileges in the files but not live and (commented-out unless `--allow-drop`) `REVOKE` for privileges live but not in the files:
+
+```bash
+databricks-schema generate-sql <catalog> ./schemas/ --include-grants
+```
+
 ### `validate`
 
 Validate local schema files for structural integrity (no Databricks connection needed):
@@ -347,7 +437,7 @@ Pass `--format json` or `--format yaml` for an `{"issues": [...]}` document inst
 ### `diff-files`
 
 Compare two local directories of schema files (no Databricks connection needed). Same output,
-exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` flags as `diff`:
+exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` / `--include-grants` flags as `diff`:
 
 ```bash
 databricks-schema diff-files ./schemas-prod/ ./schemas-test/
@@ -382,6 +472,10 @@ catalog = extractor.extract_catalog("my_catalog", schema_filter=["main", "raw"])
 # Include Unity Catalog tags (extra API calls per entity; excluded by default)
 catalog = extractor.extract_catalog("my_catalog", include_tags=True)
 
+# Include direct (non-inherited) grants on schemas and tables; compare them with
+# diff_schemas(..., include_grants=True) and friends
+catalog = extractor.extract_catalog("my_catalog", include_grants=True)
+
 # Include additional metadata (owner, storage_location)
 catalog = extractor.extract_catalog("my_catalog", include_metadata=True)
 
@@ -392,7 +486,12 @@ yaml_text = catalog_to_yaml(catalog)
 schema = schema_from_yaml(open("schemas/main.yaml").read())
 print(schema.tables[0].columns)
 
-# Compare live catalog against local YAML files
+# DBML: one document per catalog
+from databricks_schema import catalog_from_dbml, catalog_to_dbml
+Path("schemas/my_catalog.dbml").write_text(catalog_to_dbml(catalog))
+catalog = catalog_from_dbml(Path("schemas/my_catalog.dbml").read_text())
+
+# Compare live catalog against local YAML files (fmt="json" / fmt="dbml" for other formats)
 result = diff_catalog_with_dir(catalog, Path("./schemas/"))
 if result.has_changes:
     for schema_diff in result.schemas:

{databricks_schema-0.8.0 → databricks_schema-0.10.0}/README.md

@@ -1,6 +1,6 @@
 # databricks-schema
 
-A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas in YAML format. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
+A CLI tool and Python library that uses the Databricks SDK to extract and diff Unity Catalog schemas as YAML, JSON or [DBML](https://dbml.dbdiagram.io/docs/) files. It can also generate Databricks Spark SQL to apply schema changes across catalogs.
 
 ## Getting Started
 
@@ -104,12 +104,18 @@ name: main
 comment: Main production schema
 tags:
   env: prod
+grants:
+  analysts:
+    - USE_SCHEMA
 tables:
   - name: users
     table_type: MANAGED
     comment: User accounts
     tags:
       domain: identity
+    grants:
+      analysts:
+        - SELECT
     columns:
       - name: id
         data_type: bigint
@@ -133,6 +139,64 @@ tables:
           - id
 ```
 
+### DBML
+
+Writing DBML works out of the box; reading it back (`diff`, `generate-sql`, `validate`, `diff-files`, `catalog_from_dbml`) needs the optional `dbml` extra, which installs [PyDBML](https://github.com/Vanderhoof/PyDBML):
+
+```bash
+pip install 'databricks-schema[dbml]'
+uv tool install 'databricks-schema[dbml]'
+```
+
+Without it, those commands exit `2` with a message saying how to install it.
+
+Use `--format dbml` to write the catalog as a single [DBML](https://dbml.dbdiagram.io/docs/) document — `{output-dir}/{catalog}.dbml` with `--output-dir`, or stdout without. Unlike YAML/JSON, DBML is one file per catalog, so that foreign keys between schemas resolve within the file. Paste it into [dbdiagram.io](https://dbdiagram.io) for an ER diagram, or point `diff`, `generate-sql`, `validate` and `diff-files` at the directory just like a YAML/JSON one.
+
+```dbml
+Project "prod_catalog" {
+    database_type: 'Databricks'
+}
+
+TableGroup "main" [note: 'Main production schema'] {
+    "main"."users"
+}
+
+Table "main"."users" {
+    "id" bigint [not null, note: 'Primary key']
+    "email" string
+    "org_id" bigint
+    "settings" "struct<theme:string,beta:boolean>"
+
+    indexes {
+        ("id") [pk, name: 'pk_users']
+    }
+
+    Note: '''User accounts
+
+@table_type: MANAGED
+@tags: {"domain": "identity"}'''
+}
+
+Ref "fk_org": "main"."users"."org_id" > "orgs"."organizations"."id"
+```
+
+How the model maps to DBML:
+
+| Model | DBML |
+|---|---|
+| Catalog | `Project` (comment in its `Note`) |
+| Schema | `TableGroup` named after the schema (comment in its `note`); written for every schema, so empty schemas survive |
+| Table / column comment | `Note` / `note:` |
+| `nullable: false` | `not null` |
+| Primary key | `indexes { (...) [pk, name: '...'] }` |
+| Foreign key | `Ref "<name>": ... > ...` |
+| Complex types (`struct<...>`, `map<...>`) | double-quoted type |
+| `tags`, `grants`, `owner`, `table_type`, `storage_location` | trailing `@key: value` lines in the note (`@tags` and `@grants` are JSON objects) |
+
+Everything round-trips: reading a written file gives back exactly the extracted model. Hand-written DBML (e.g. exported from dbdiagram) is accepted too — tables without a schema land in `public`, column `pk` and inline `ref:` settings are understood, and constructs with no Unity Catalog equivalent (enums, sticky notes, other indexes, defaults, many-to-many refs, TableGroups that don't match a schema) are ignored. A directory may hold several `.dbml` files, but each schema may be defined in only one of them.
+
+### Catalog document
+
 Without `--output-dir`, `extract` prints a single `Catalog` document to stdout instead — the same schema shape nested under a `schemas` list, with the catalog name as a top-level field:
 
 ```yaml
@@ -206,12 +270,24 @@ Include Unity Catalog tags in the output (extra API calls per entity; excluded b
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-tags
 ```
 
+Include grants (principal → privileges) on schemas and tables. Only grants made directly on each object are extracted — privileges inherited from a parent catalog or schema are left out, so they don't show up repeatedly on every child (one extra API call per schema/table; excluded by default):
+
+```bash
+databricks-schema extract <catalog> --output-dir ./schemas/ --include-grants
+```
+
 Include additional metadata (`owner`, `storage_location`) in the output:
 
 ```bash
 databricks-schema extract <catalog> --output-dir ./schemas/ --include-metadata
 ```
 
+Write a single DBML file (`./schemas/<catalog>.dbml`) instead — see [DBML](#dbml):
+
+```bash
+databricks-schema extract <catalog> --output-dir ./schemas/ --format dbml
+```
+
 Control the number of parallel workers (default: 4), useful for large schemas with many tags:
 
 ```bash
@@ -220,7 +296,7 @@ databricks-schema extract <catalog> --output-dir ./schemas/ --workers 8
 
 ### `diff`
 
-Compare the live catalog against previously extracted schema files (format auto-detected from the directory — YAML or JSON, not mixed):
+Compare the live catalog against previously extracted schema files (format auto-detected from the directory — YAML, JSON or DBML, not mixed):
 
 ```bash
 databricks-schema diff <catalog> ./schemas/
@@ -264,6 +340,12 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema diff <catalog> ./schemas/ --include-metadata
 ```
 
+Include direct grants in the comparison (excluded by default; without it, grants in the files are ignored):
+
+```bash
+databricks-schema diff <catalog> ./schemas/ --include-grants
+```
+
 Get the same comparison as structured JSON or YAML instead of the `+`/`-`/`~` tree (exit codes unchanged) — useful for scripts or agents:
 
 ```bash
@@ -273,7 +355,7 @@ databricks-schema diff <catalog> ./schemas/ --format yaml
 
 ### `generate-sql`
 
-Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected, YAML or JSON, not mixed). Statements are printed to stdout by default:
+Generate Databricks Spark SQL statements to bring the live catalog in line with local schema files (format auto-detected — YAML, JSON or DBML, not mixed). Statements are printed to stdout by default:
 
 ```bash
 databricks-schema generate-sql <catalog> ./schemas/
@@ -285,7 +367,7 @@ Write one `.sql` file per schema to a directory instead:
 databricks-schema generate-sql <catalog> ./schemas/ --output-dir ./migrations/
 ```
 
-Destructive statements (`DROP SCHEMA`, `DROP TABLE`, `DROP COLUMN`) are emitted as SQL comments by default. Pass `--allow-drop` to emit them as executable statements:
+Destructive statements (`DROP SCHEMA`, `DROP TABLE`, `DROP COLUMN`, `REVOKE`) are emitted as SQL comments by default. Pass `--allow-drop` to emit them as executable statements:
 
 ```bash
 databricks-schema generate-sql <catalog> ./schemas/ --allow-drop
@@ -309,6 +391,12 @@ Include `owner` in the comparison (excluded by default):
 databricks-schema generate-sql <catalog> ./schemas/ --include-metadata
 ```
 
+Include direct grants in the comparison, emitting `GRANT` for privileges in the files but not live and (commented-out unless `--allow-drop`) `REVOKE` for privileges live but not in the files:
+
+```bash
+databricks-schema generate-sql <catalog> ./schemas/ --include-grants
+```
+
 ### `validate`
 
 Validate local schema files for structural integrity (no Databricks connection needed):
@@ -322,7 +410,7 @@ Pass `--format json` or `--format yaml` for an `{"issues": [...]}` document inst
 ### `diff-files`
 
 Compare two local directories of schema files (no Databricks connection needed). Same output,
-exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` flags as `diff`:
+exit codes, `--format json`/`yaml`, and `--schema` / `--include-metadata` / `--include-grants` flags as `diff`:
 
 ```bash
 databricks-schema diff-files ./schemas-prod/ ./schemas-test/
@@ -357,6 +445,10 @@ catalog = extractor.extract_catalog("my_catalog", schema_filter=["main", "raw"])
 # Include Unity Catalog tags (extra API calls per entity; excluded by default)
 catalog = extractor.extract_catalog("my_catalog", include_tags=True)
 
+# Include direct (non-inherited) grants on schemas and tables; compare them with
+# diff_schemas(..., include_grants=True) and friends
+catalog = extractor.extract_catalog("my_catalog", include_grants=True)
+
 # Include additional metadata (owner, storage_location)
 catalog = extractor.extract_catalog("my_catalog", include_metadata=True)
 
@@ -367,7 +459,12 @@ yaml_text = catalog_to_yaml(catalog)
 schema = schema_from_yaml(open("schemas/main.yaml").read())
 print(schema.tables[0].columns)
 
-# Compare live catalog against local YAML files
+# DBML: one document per catalog
+from databricks_schema import catalog_from_dbml, catalog_to_dbml
+Path("schemas/my_catalog.dbml").write_text(catalog_to_dbml(catalog))
+catalog = catalog_from_dbml(Path("schemas/my_catalog.dbml").read_text())
+
+# Compare live catalog against local YAML files (fmt="json" / fmt="dbml" for other formats)
 result = diff_catalog_with_dir(catalog, Path("./schemas/"))
 if result.has_changes:
     for schema_diff in result.schemas:

{databricks_schema-0.8.0 → databricks_schema-0.10.0}/databricks_schema/__init__.py

@@ -1,5 +1,14 @@
 from databricks.sdk.service.catalog import TableType
 
+from databricks_schema.dbml_io import (
+    DbmlDependencyError,
+    DbmlParseError,
+    catalog_from_dbml,
+    catalog_to_dbml,
+    schema_from_dbml,
+    schema_to_dbml,
+    schemas_from_dbml,
+)
 from databricks_schema.diff import (
     CatalogDiff,
     ColumnDiff,
@@ -20,6 +29,7 @@ from databricks_schema.yaml_io import (
     catalog_from_yaml,
     catalog_to_json,
     catalog_to_yaml,
+    load_schema_dir,
     schema_from_json,
     schema_from_yaml,
     schema_to_json,
@@ -32,6 +42,8 @@ __all__ = [
     "CatalogExtractor",
     "Column",
     "ColumnDiff",
+    "DbmlDependencyError",
+    "DbmlParseError",
     "FieldChange",
     "ForeignKey",
     "PrimaryKey",
@@ -42,18 +54,24 @@ __all__ = [
     "TableType",
     "ValidationIssue",
     "ValidationResult",
+    "catalog_from_dbml",
     "catalog_from_json",
     "catalog_from_yaml",
+    "catalog_to_dbml",
     "catalog_to_json",
     "catalog_to_yaml",
     "diff_catalog_with_dir",
     "diff_catalogs",
     "diff_schema_dirs",
     "diff_schemas",
+    "load_schema_dir",
     "schema_diff_to_sql",
+    "schema_from_dbml",
     "schema_from_json",
     "schema_from_yaml",
+    "schema_to_dbml",
     "schema_to_json",
     "schema_to_yaml",
+    "schemas_from_dbml",
     "validate_schemas",
 ]