model2data 0.4.1__tar.gz → 0.5.0__tar.gz

{model2data-0.4.1 → model2data-0.5.0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 0.4.1
+Version: 0.5.0
 Summary: Generate analytics-ready datasets from DBML models
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dbt-core>=1.5.0
-Requires-Dist: dbt-duckdb>=1.5.0
+Requires-Dist: dbt-core>=1.8.5
+Requires-Dist: dbt-duckdb>=1.8.4
 Requires-Dist: faker>=37.12.0
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: typer>=0.20.0
 Provides-Extra: postgres
-Requires-Dist: dbt-postgres>=1.5.0; extra == "postgres"
+Requires-Dist: dbt-postgres>=1.8.0; extra == "postgres"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -122,7 +122,9 @@ flowchart LR
    (int, date, timestamp, ...), name-aware inference for everything else (`email`, `phone`,
    `city`, ...), foreign keys resolved against already-generated parent rows.
 3. **Scaffold.** Writes a complete dbt project around that data: CSV seeds, staging models with
-   `source`/`not_null`/`unique`/`relationships` tests, and a profile for DuckDB (zero-config,
+   `source`/`not_null`/`unique`/`relationships` tests, `accepted_values` tests for DBML
+   `Enum`-typed columns, singular SQL tests for composite primary/unique keys, table and column
+   `description:` fields pulled from DBML notes, and a profile for DuckDB (zero-config,
    file-based) or Postgres.
 
 ---
@@ -169,13 +171,19 @@ Connection details are read from environment variables (`MODEL2DATA_PG_HOST`, `M
 
 After generation, the CLI prints a short summary — tables and rows generated, relationships found in the DBML, and any columns that fell back to generic placeholder text because neither their type nor name could be matched.
 
-Pass `--unit-tests` to also generate deterministic dbt unit test fixtures (`tests/unit/test_stg_<table>.yml`) from the actually-generated seed rows:
+Pass `--unit-tests` to also generate deterministic dbt unit test fixtures (`models/staging/ut_stg_<table>.yml`) from the actually-generated seed rows:
 
 ```bash
 model2data --file examples/hackernews.dbml --rows 200 --seed 42 --unit-tests
 ```
 
-This targets dbt-core's native unit testing feature, which requires **dbt-core >= 1.8**. Since this project only requires `dbt-core>=1.5.0` by default, unit test generation is opt-in — leave the flag off if your dbt-core version is older.
+This targets dbt-core's native unit testing feature, which requires dbt-core >= 1.8 — already
+covered by this project's `dbt-core>=1.8.5` floor, so `--unit-tests` works with the base install.
+Note: on dbt-core versions in the 1.8.x line specifically, a DBML column named after a SQL
+reserved word (e.g. `by`, as in `examples/hackernews.dbml`) can fail unit test execution with a
+`syntax error` — a dbt-core-internal identifier-quoting limitation in its unit test fixture
+rendering for that release line, not something under model2data's control. It's fixed in later
+dbt-core versions; every other `--unit-tests` path works fine on 1.8.x.
 
 ---
 
@@ -186,32 +194,36 @@ The generated dbt project includes:
 ```
 dbt_{project_name}/
 ├── seeds/
-│   └── {project_name}/
+│   └── raw/
 │       ├── table1.csv
 │       └── table2.csv
 ├── models/
-│   └── {project_name}/
-│       └── staging/
-│           ├── __sources.yml
-│           ├── stg_table1.sql
-│           ├── stg_table1.yml
-│           └── ...
+│   └── staging/
+│       ├── __sources.yml
+│       ├── stg_table1.sql
+│       ├── stg_table1.yml
+│       ├── ut_stg_table1.yml  # only with --unit-tests
+│       └── ...
+├── data-tests/
+│   └── unique_combination_stg_table1_col_a_col_b.sql  # only for composite pk/unique keys
 ├── macros/
 │   └── generate_schema_name.sql
 ├── dbt_project.yml
 ├── profiles.yml  # DuckDB or Postgres config, depending on --adapter
-└── {project_name}.duckdb  # DuckDB adapter only
+└── {project_name}_profile.duckdb  # DuckDB adapter only
 ```
 
 - **Seeds**: CSV files with generated synthetic data.
 - **Staging Models**: Basic dbt models that load from seeds.
 - **Sources & Tests**: YAML configs defining sources and column tests (`not_null`, `unique`,
   `relationships`, and `accepted_values` for DBML `Enum`-typed columns). Table and column
-  `Note` text from the DBML becomes `description:` fields. Composite primary/unique keys
-  declared in an `indexes { }` block get a singular SQL test under `tests/`.
+  `Note` text from the DBML becomes `description:` fields.
+- **Composite key tests**: Composite primary/unique keys declared in an `indexes { }` block get
+  a singular SQL test under `data-tests/`, dbt's configured `test-paths`.
 - **Profiles**: Pre-configured for DuckDB (file-based) or Postgres (via env vars), with schema handling.
-- **Unit tests** (opt-in via `--unit-tests`): `tests/unit/test_stg_<table>.yml` fixtures built
-  from real generated rows. Requires dbt-core >= 1.8.
+- **Unit tests** (opt-in via `--unit-tests`): `models/staging/ut_stg_<table>.yml` fixtures built
+  from real generated rows, co-located with each staging model so dbt (which only parses unit
+  tests from `model-paths`) picks them up. Requires dbt-core >= 1.8.
 
 ---
 

{model2data-0.4.1 → model2data-0.5.0}/README.md

@@ -97,7 +97,9 @@ flowchart LR
    (int, date, timestamp, ...), name-aware inference for everything else (`email`, `phone`,
    `city`, ...), foreign keys resolved against already-generated parent rows.
 3. **Scaffold.** Writes a complete dbt project around that data: CSV seeds, staging models with
-   `source`/`not_null`/`unique`/`relationships` tests, and a profile for DuckDB (zero-config,
+   `source`/`not_null`/`unique`/`relationships` tests, `accepted_values` tests for DBML
+   `Enum`-typed columns, singular SQL tests for composite primary/unique keys, table and column
+   `description:` fields pulled from DBML notes, and a profile for DuckDB (zero-config,
    file-based) or Postgres.
 
 ---
@@ -144,13 +146,19 @@ Connection details are read from environment variables (`MODEL2DATA_PG_HOST`, `M
 
 After generation, the CLI prints a short summary — tables and rows generated, relationships found in the DBML, and any columns that fell back to generic placeholder text because neither their type nor name could be matched.
 
-Pass `--unit-tests` to also generate deterministic dbt unit test fixtures (`tests/unit/test_stg_<table>.yml`) from the actually-generated seed rows:
+Pass `--unit-tests` to also generate deterministic dbt unit test fixtures (`models/staging/ut_stg_<table>.yml`) from the actually-generated seed rows:
 
 ```bash
 model2data --file examples/hackernews.dbml --rows 200 --seed 42 --unit-tests
 ```
 
-This targets dbt-core's native unit testing feature, which requires **dbt-core >= 1.8**. Since this project only requires `dbt-core>=1.5.0` by default, unit test generation is opt-in — leave the flag off if your dbt-core version is older.
+This targets dbt-core's native unit testing feature, which requires dbt-core >= 1.8 — already
+covered by this project's `dbt-core>=1.8.5` floor, so `--unit-tests` works with the base install.
+Note: on dbt-core versions in the 1.8.x line specifically, a DBML column named after a SQL
+reserved word (e.g. `by`, as in `examples/hackernews.dbml`) can fail unit test execution with a
+`syntax error` — a dbt-core-internal identifier-quoting limitation in its unit test fixture
+rendering for that release line, not something under model2data's control. It's fixed in later
+dbt-core versions; every other `--unit-tests` path works fine on 1.8.x.
 
 ---
 
@@ -161,32 +169,36 @@ The generated dbt project includes:
 ```
 dbt_{project_name}/
 ├── seeds/
-│   └── {project_name}/
+│   └── raw/
 │       ├── table1.csv
 │       └── table2.csv
 ├── models/
-│   └── {project_name}/
-│       └── staging/
-│           ├── __sources.yml
-│           ├── stg_table1.sql
-│           ├── stg_table1.yml
-│           └── ...
+│   └── staging/
+│       ├── __sources.yml
+│       ├── stg_table1.sql
+│       ├── stg_table1.yml
+│       ├── ut_stg_table1.yml  # only with --unit-tests
+│       └── ...
+├── data-tests/
+│   └── unique_combination_stg_table1_col_a_col_b.sql  # only for composite pk/unique keys
 ├── macros/
 │   └── generate_schema_name.sql
 ├── dbt_project.yml
 ├── profiles.yml  # DuckDB or Postgres config, depending on --adapter
-└── {project_name}.duckdb  # DuckDB adapter only
+└── {project_name}_profile.duckdb  # DuckDB adapter only
 ```
 
 - **Seeds**: CSV files with generated synthetic data.
 - **Staging Models**: Basic dbt models that load from seeds.
 - **Sources & Tests**: YAML configs defining sources and column tests (`not_null`, `unique`,
   `relationships`, and `accepted_values` for DBML `Enum`-typed columns). Table and column
-  `Note` text from the DBML becomes `description:` fields. Composite primary/unique keys
-  declared in an `indexes { }` block get a singular SQL test under `tests/`.
+  `Note` text from the DBML becomes `description:` fields.
+- **Composite key tests**: Composite primary/unique keys declared in an `indexes { }` block get
+  a singular SQL test under `data-tests/`, dbt's configured `test-paths`.
 - **Profiles**: Pre-configured for DuckDB (file-based) or Postgres (via env vars), with schema handling.
-- **Unit tests** (opt-in via `--unit-tests`): `tests/unit/test_stg_<table>.yml` fixtures built
-  from real generated rows. Requires dbt-core >= 1.8.
+- **Unit tests** (opt-in via `--unit-tests`): `models/staging/ut_stg_<table>.yml` fixtures built
+  from real generated rows, co-located with each staging model so dbt (which only parses unit
+  tests from `model-paths`) picks them up. Requires dbt-core >= 1.8.
 
 ---
 

{model2data-0.4.1 → model2data-0.5.0}/model2data/cli.py

@@ -12,9 +12,9 @@ from model2data.dbt.project import (
     create_staging_models,
 )
 from model2data.dbt.tests import generate_dbt_yml, generate_unit_tests
-from model2data.generate.core import generate_data_from_dbml
+from model2data.generate.core import generate_data_from_dbml, get_cyclic_tables
 from model2data.generate.faker import get_unmapped_columns, reset_stats
-from model2data.parse.dbml import parse_dbml
+from model2data.parse.dbml import get_parse_warnings, parse_dbml
 from model2data.utils import normalize_identifier
 
 SUPPORTED_ADAPTERS = ("duckdb", "postgres")
@@ -80,8 +80,8 @@ def main(
         False,
         "--unit-tests",
         help=(
-            "Also generate deterministic dbt unit test fixtures (tests/unit/) from the "
-            "generated seed rows. Requires dbt-core >= 1.8 to run."
+            "Also generate deterministic dbt unit test fixtures (models/staging/ut_stg_*.yml) "
+            "from the generated seed rows. Requires dbt-core >= 1.8 to run."
         ),
     ),
 ):
@@ -111,6 +111,7 @@ def main(
     # Parse DBML (names untouched)
     # -------------------------
     tables, refs = parse_dbml(file)
+    parse_warnings = get_parse_warnings()
     if not tables:
         typer.echo("❌ No tables found in the provided DBML file.")
         raise typer.Exit(1)
@@ -175,6 +176,7 @@ def main(
     # -------------------------
     total_rows = sum(len(df) for df in generated_tables.values())
     unmapped = get_unmapped_columns()
+    cyclic_tables = get_cyclic_tables()
 
     typer.echo("\n📊 Summary")
     typer.echo(f"  Tables generated:        {len(generated_tables)}")
@@ -186,6 +188,15 @@ def main(
             typer.echo(f"    - {col_name} ({data_type})")
     else:
         typer.echo("  Columns using generic fallback text: 0")
+    if cyclic_tables:
+        typer.echo(
+            "  ⚠️  Tables in an unresolved FK cycle (data may not respect "
+            f"all relationships): {', '.join(cyclic_tables)}"
+        )
+    if parse_warnings:
+        typer.echo(f"  ⚠️  DBML lines model2data could not fully parse: {len(parse_warnings)}")
+        for warning in parse_warnings:
+            typer.echo(f"    - {warning}")
 
     # -------------------------
     # Done

{model2data-0.4.1 → model2data-0.5.0}/model2data/dbt/project.py

@@ -13,7 +13,7 @@ def create_project_scaffold(dest: Path, project_name: str, profile_name: str) ->
     (dest / "seeds" / "raw").mkdir(parents=True, exist_ok=True)
     (dest / "analysis").mkdir(exist_ok=True)
     (dest / "macros").mkdir(exist_ok=True)
-    (dest / "tests").mkdir(exist_ok=True)
+    (dest / "data-tests").mkdir(exist_ok=True)
     (dest / "snapshots").mkdir(exist_ok=True)
 
     # dbt_project.yml
@@ -45,10 +45,14 @@ def create_staging_models(dest: Path, project_name: str) -> None:
         model_file = models_path / f"stg_{table_name}.sql"
 
         if not model_file.exists():
+            # table_name is spliced into a single-quoted Jinja string literal;
+            # escape any embedded single quote so a DBML identifier containing
+            # one can't break the source() call.
+            escaped_name = table_name.replace("'", "\\'")
             sql_content = f"""\
 -- Auto-generated staging model for {table_name}
 select *
-from {{{{ source('raw', '{table_name}') }}}}
+from {{{{ source('raw', '{escaped_name}') }}}}
                 """
             model_file.write_text(sql_content)
 

{model2data-0.4.1 → model2data-0.5.0}/model2data/dbt/tests.py

@@ -6,11 +6,20 @@ from typing import Any, Union
 import pandas as pd
 import yaml
 
+from model2data.generate.faker import is_free_text_type
+from model2data.generate.relationships import classify_refs
 
-def _yaml_field_lines(key: str, value: str, indent: str) -> list[str]:
-    """Render `key: value` as safely-escaped YAML lines at the given indent."""
-    dumped = yaml.safe_dump({key: value}, default_flow_style=False, sort_keys=False)
-    return [f"{indent}{line}" for line in dumped.strip("\n").splitlines()]
+
+def _dump_yaml(data: dict) -> str:
+    """Dump a plain Python structure to YAML, safely escaping every value.
+
+    Every table/column/description string that ends up in generated YAML
+    goes through this single choke point instead of being hand-interpolated
+    into f-string lines, so an arbitrary (but valid) DBML identifier --
+    containing a space, colon, quote, etc. -- can never produce invalid or
+    silently-misparsed YAML.
+    """
+    return yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
 
 
 def generate_dbt_yml(dest: Path, tables: dict, refs: list[dict], source_name: str = "hackernews"):
@@ -28,27 +37,47 @@ def generate_dbt_yml(dest: Path, tables: dict, refs: list[dict], source_name: st
     # -------------------------
     # Build foreign key map
     # -------------------------
+    # Only emit a `relationships` test for refs the generator actually makes
+    # FK-aware: direct FK refs (target column is a pk/"id"), plus attribute
+    # refs that ride along an existing FK between the same two tables (see
+    # generate.core's attribute-mirroring pass). An attribute ref with no
+    # accompanying FK is left as unrelated random data by the generator, so
+    # testing it against the parent table would be a guaranteed false
+    # failure.
+    fk_refs_classified, attribute_refs_classified = classify_refs(tables, refs)
+    fk_table_pairs = {(fk["source_table"], fk["target_table"]) for fk in fk_refs_classified}
+    eligible_refs = list(fk_refs_classified) + [
+        ref
+        for ref in attribute_refs_classified
+        if (ref["source_table"], ref["target_table"]) in fk_table_pairs
+    ]
+
     fk_map = defaultdict(list)
-    for ref in refs:
+    for ref in eligible_refs:
         fk_map[(ref["source_table"], ref["source_column"])].append(ref)
 
     # -------------------------
     # Generate __sources.yml
     # -------------------------
-    sources_lines = ["version: 2", "", "sources:"]
-    sources_lines.append("  - name: raw")
-    sources_lines.append("    schema: raw")
-    sources_lines.append(f"    description: {source_name.capitalize()} raw seed data")
-    sources_lines.append("    tables:")
-
+    source_tables = []
     for table in tables.values():
         seed_name = table.name  # keep exact name
         table_desc = getattr(table, "description", None) or f"Table {seed_name}"
-        sources_lines.append(f"      - name: {seed_name}")
-        sources_lines.extend(_yaml_field_lines("description", table_desc, "        "))
-
+        source_tables.append({"name": seed_name, "description": table_desc})
+
+    sources_doc = {
+        "version": 2,
+        "sources": [
+            {
+                "name": "raw",
+                "schema": "raw",
+                "description": f"{source_name.capitalize()} raw seed data",
+                "tables": source_tables,
+            }
+        ],
+    }
     sources_file = staging_path / "__sources.yml"
-    sources_file.write_text("\n".join(sources_lines))
+    sources_file.write_text(_dump_yaml(sources_doc))
 
     # -------------------------
     # Generate individual staging model YAMLs
@@ -79,52 +108,77 @@ def generate_dbt_yml(dest: Path, tables: dict, refs: list[dict], source_name: st
                     }
                 )
 
-            model_columns.append(
-                {
-                    "name": col.name,
-                    "description": getattr(col, "description", None),
-                    "tests": tests if tests else None,
-                }
-            )
-
-        # Render model YAML
-        lines = ["version: 2", "", "models:"]
-        lines.append(f"  - name: {stg_name}")
-        lines.append("    columns:")
-        for col in model_columns:
-            lines.append(f"      - name: {col['name']}")
-            if col["description"]:
-                lines.extend(_yaml_field_lines("description", col["description"], "        "))
-            if col["tests"]:
-                lines.append("        tests:")
-                for test in col["tests"]:
-                    if isinstance(test, str):
-                        lines.append(f"          - {test}")
-                    elif "accepted_values" in test:
-                        lines.append("          - accepted_values:")
-                        lines.append("              values:")
-                        for value in test["accepted_values"]["values"]:
-                            lines.append(f"                - {value!r}")
-                    else:
-                        # relationships test with arguments
-                        for k, v in test.items():
-                            lines.append(f"          - {k}:")
-                            lines.append("              arguments:")
-                            for fk_key, fk_val in v.items():
-                                lines.append(f"                {fk_key}: {fk_val}")
+            col_doc: dict[str, Any] = {"name": col.name}
+            description = getattr(col, "description", None)
+            if description:
+                col_doc["description"] = description
+            if tests:
+                col_doc["tests"] = tests
+            model_columns.append(col_doc)
+
+        model_doc = {
+            "version": 2,
+            "models": [{"name": stg_name, "columns": model_columns}],
+        }
 
         # Write YAML to same folder as SQL model
         yml_file = staging_path / f"{stg_name}.yml"
-        yml_file.write_text("\n".join(lines))
+        yml_file.write_text(_dump_yaml(model_doc))
 
     # -------------------------
     # Composite key singular tests
     # -------------------------
     _generate_composite_key_tests(dest, tables)
 
+    # -------------------------
+    # Seed column-type overrides
+    # -------------------------
+    _generate_seed_config(dest, tables)
+
+
+def _generate_seed_config(dest: Path, tables: dict) -> None:
+    """
+    Force every free-text column (see `is_free_text_type`) to VARCHAR in
+    the seed loader config, instead of letting dbt/duckdb sniff the type
+    from CSV content. Some generated text is all-digit (EAN13 barcodes,
+    zero-padded postcodes, ...) and would otherwise be silently loaded as
+    an integer, overflowing or dropping leading zeros.
+    """
+    seed_entries = []
+
+    for table in tables.values():
+        column_types = {
+            col.name: "varchar" for col in table.columns if is_free_text_type(col.data_type)
+        }
+        if not column_types:
+            continue
+
+        seed_entries.append({"name": table.name, "config": {"column_types": column_types}})
+
+    if not seed_entries:
+        return
+
+    seeds_doc = {"version": 2, "seeds": seed_entries}
+
+    seed_raw_path = dest / "seeds" / "raw"
+    seed_raw_path.mkdir(parents=True, exist_ok=True)
+    (seed_raw_path / "__seed_config.yml").write_text(_dump_yaml(seeds_doc))
+
+
+def _quote_sql_identifier(name: str) -> str:
+    """ANSI double-quote a raw column identifier for use in generated SQL.
+
+    Both supported adapters (DuckDB and Postgres) accept ANSI double-quoting,
+    which is required once a DBML identifier contains a space, colon, or
+    other character that would otherwise break an unquoted `select`/`group
+    by` clause. A literal `"` inside the identifier is escaped by doubling,
+    the standard ANSI SQL convention.
+    """
+    return '"' + name.replace('"', '""') + '"'
+
 
 def _generate_composite_key_tests(dest: Path, tables: dict) -> None:
-    tests_path = dest / "tests"
+    tests_path = dest / "data-tests"
     tests_path.mkdir(parents=True, exist_ok=True)
 
     for table in tables.values():
@@ -136,7 +190,8 @@ def _generate_composite_key_tests(dest: Path, tables: dict) -> None:
             if len(columns) < 2:
                 continue
 
-            columns_csv = ", ".join(columns)
+            quoted_columns = [_quote_sql_identifier(c) for c in columns]
+            columns_csv = ", ".join(quoted_columns)
             test_name = "unique_combination_" + "_".join([stg_name, *columns])
             sql = (
                 f"select {columns_csv}, count(*) as n\n"
@@ -158,8 +213,12 @@ def generate_unit_tests(
 
     Since staging models are pure `select * from {{ source(...) }}` passthroughs,
     a handful of already-generated rows can serve as both `given` and `expect`.
+
+    Written alongside each staging model (under `model-paths`, which is where
+    dbt actually parses unit tests from) as `ut_stg_<table>.yml`, parallel to
+    the `stg_<table>.yml` schema file generated by `generate_dbt_yml`.
     """
-    unit_tests_path = dest / "tests" / "unit"
+    unit_tests_path = dest / "models" / "staging"
     unit_tests_path.mkdir(parents=True, exist_ok=True)
 
     for table in tables.values():
@@ -169,6 +228,11 @@ def generate_unit_tests(
 
         sample_rows = _rows_as_native_dicts(df.head(sample_size))
         stg_name = f"stg_{table.name}"
+        # table.name is spliced into a single-quoted Jinja string literal (the
+        # source() call is evaluated by dbt as an expression, not treated as
+        # a literal YAML string); escape any embedded single quote so an
+        # unusual DBML identifier can't break that call.
+        escaped_name = table.name.replace("'", "\\'")
 
         unit_test = {
             "unit_tests": [
@@ -177,7 +241,7 @@ def generate_unit_tests(
                     "model": stg_name,
                     "given": [
                         {
-                            "input": f"source('raw', '{table.name}')",
+                            "input": f"source('raw', '{escaped_name}')",
                             "rows": sample_rows,
                         }
                     ],
@@ -188,7 +252,7 @@ def generate_unit_tests(
             ]
         }
 
-        yml_file = unit_tests_path / f"test_{stg_name}.yml"
+        yml_file = unit_tests_path / f"ut_{stg_name}.yml"
         yml_file.write_text(yaml.safe_dump(unit_test, sort_keys=False, default_flow_style=False))
 
 

{model2data-0.4.1 → model2data-0.5.0}/model2data/generate/core.py

@@ -16,6 +16,23 @@ from model2data.parse.dbml import TableDef
 
 fake = Faker()
 
+# Tables the most recent generate_data_from_dbml() call found stuck in an
+# unresolved FK cycle (never reached indegree 0 during the topological
+# sort). Exposed out-of-band, mirroring generate.faker's
+# reset_stats()/get_unmapped_columns() pattern, so the CLI can surface a
+# warning without changing this module's existing return signature.
+_cycle_state: dict[str, list[str]] = {"cyclic_tables": []}
+
+
+def reset_cycle_state() -> None:
+    """Clear the record of tables found in an unresolved FK cycle."""
+    _cycle_state["cyclic_tables"] = []
+
+
+def get_cyclic_tables() -> list[str]:
+    """Return table names stuck in an unresolved FK cycle by the last run."""
+    return list(_cycle_state["cyclic_tables"])
+
 
 # ---------------------------------------------------------
 # Public API
@@ -36,6 +53,8 @@ def generate_data_from_dbml(
         random.seed(seed)
         Faker.seed(seed)
 
+    reset_cycle_state()
+
     # ---------------------------------------------------------
     # Classify references
     # ---------------------------------------------------------
@@ -76,6 +95,7 @@ def generate_data_from_dbml(
             )
 
         df = pd.DataFrame(data)
+        df = _resolve_self_referencing_fks(df, table_def, table_name, fk_lookup, row_count)
         df = _deduplicate_composite_keys(df, table_def)
 
         # -----------------------------------------------------
@@ -110,6 +130,7 @@ def generate_data_from_dbml(
 
             df[child_column] = df[fk_column].map(lookup)
 
+        df = _coerce_integer_dtypes(df, table_def)
         generated[table_name] = df
 
     return generated
@@ -118,6 +139,25 @@ def generate_data_from_dbml(
 # ---------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------
+def _coerce_integer_dtypes(df: pd.DataFrame, table_def: TableDef) -> pd.DataFrame:
+    """
+    Cast int/bigint/smallint-typed columns to pandas' nullable "Int64" dtype.
+
+    `generate_column_values` fills "empty" nullable columns with `None`
+    (absent an explicit default). Building a plain `pd.DataFrame` from a
+    Python list mixing ints and `None` silently upcasts that column to
+    float64, so whole numbers round-trip through the CSV seed as "70.0"
+    instead of "70" and blanks. Int64 keeps them as integers and renders
+    nulls as empty cells, matching the DBML-declared type.
+    """
+    for column in table_def.columns:
+        base_type = column.data_type.lower().split("(")[0].strip()
+        if any(key in base_type for key in ["int", "integer", "bigint", "smallint"]):
+            df[column.name] = df[column.name].astype("Int64")
+
+    return df
+
+
 def _deduplicate_composite_keys(
     df: pd.DataFrame,
     table_def: TableDef,
@@ -158,6 +198,45 @@ def _deduplicate_composite_keys(
     return df
 
 
+def _resolve_self_referencing_fks(
+    df: pd.DataFrame,
+    table_def: TableDef,
+    table_name: str,
+    fk_lookup: dict[tuple[str, str], tuple[str, str]],
+    row_count: int,
+) -> pd.DataFrame:
+    """
+    Re-generate any FK column that references its own table (e.g. a
+    `manager_id` on `employees` pointing back at `employees.id`) using the
+    table's own just-built parent column as the value pool.
+
+    These columns can't be resolved during the main per-column generation
+    pass above because the table isn't done building itself yet (its own
+    df isn't added to `generated` until the whole loop iteration finishes),
+    so `fk_series` falls through to None there and the column gets
+    unrelated random values instead. Once `df` exists we know the real
+    parent-column values and can fix it up here.
+    """
+    for column in table_def.columns:
+        fk_target = fk_lookup.get((table_name, column.name))
+        if not fk_target:
+            continue
+
+        parent_table, parent_column = fk_target
+        if parent_table != table_name or parent_column not in df.columns:
+            continue
+
+        ensure_unique = "pk" in column.settings
+        df[column.name] = generate_column_values(
+            column=column,
+            row_count=row_count,
+            fk_series=df[parent_column],
+            ensure_unique=ensure_unique,
+        )
+
+    return df
+
+
 def _determine_row_count(table_name: str, base_rows: int) -> int:
     """
     Return the base number of rows for all tables.
@@ -199,9 +278,17 @@ def _topological_table_order(
             if indegree[neighbor] == 0:
                 queue.append(neighbor)
 
-    # Safety net for disconnected tables
-    for name in tables.keys():
-        if name not in order:
-            order.append(name)
+    # Any table not reached by the Kahn's-algorithm pass above never had its
+    # indegree reduced to 0, which (unlike a genuinely disconnected table,
+    # which starts at indegree 0 and is processed by the loop above) can only
+    # happen if it sits inside -- or depends on -- an unresolved multi-table
+    # FK cycle. Append it to the order anyway (still generate *something*
+    # rather than crash on an unusual-but-not-invalid schema), but record it
+    # so the CLI can warn the user their generated FK data may not respect
+    # every relationship.
+    leftover = sorted(name for name in tables if name not in order)
+    if leftover:
+        _cycle_state["cyclic_tables"] = leftover
+    order.extend(leftover)
 
     return order