Schema-first generation and domain-based file splitting

[remiv1]

Context

sqlacodegen's core philosophy is clear: generate Python model code from an external source of truth that describes a database structure. Today, that source is a live database URL. This RFC proposes a natural generalization of that philosophy along two complementary axes.

Problem 1 — Greenfield projects have no database yet

When starting a new project, there is no existing database to reflect from. Developers currently have to write SQLAlchemy models by hand, or use a separate tool with no connection to sqlacodegen's ecosystem. A schema description file (TOML or JSON) would serve as a valid source of truth in the same way a live DB does — just earlier in the development lifecycle.

Problem 2 — Large schemas produce unmanageable single files

On real-world databases with 40–100+ tables, the current output is a monolithic file with thousands of lines. This is difficult to review, maintain, and split manually, especially in team environments.

Proposed workflow

Two new optional capabilities, both non-breaking:

Step 1 — Manifest export

sqlacodegen --export-manifest manifest.csv <db_url>

Exports a flat CSV listing all tables and columns. No code generated yet.

Step 2 — Human annotation

The developer adds a domain column to the CSV, assigning each table to a business domain:

table, domain
clients, crm
contacts, crm
invoices, accounting
products, catalog

Step 3 — Domain-aware generation

sqlacodegen --manifest manifest.csv <db_url> --output-dir models/

Generates one file per domain: models/crm.py, models/accounting.py, etc.

Step 4 (future) — Schema-first generation

sqlacodegen --from-schema schema.toml --output-dir models/

Bypasses the DB entirely. The TOML file is the source of truth.

Why this fits sqlacodegen's philosophy

The project already supports extensibility via the sqlacodegen.generators entry point system. This proposal follows the same spirit: the DB URL is one possible source, a structured file is another. The manifest acts as the bridge between technical schema and business semantics — something a database cannot encode on its own.

What I am not proposing

This is not a PR. It is a question about direction. If the maintainer sees value here, the manifest + domain-splitting feature could be prototyped as an external plugin first using the existing entry point mechanism, before any discussion of merging into core.

Current version context

This is raised against v4.0.3. If the scope feels too large for a minor version, a v5 horizon seems appropriate.
Happy to discuss, prototype, or simply take a "not in scope" answer — all useful signals.

[sheinbergon]

Generally speaking, this going to be a hard pass on my end (maybe @agronholm has a different opinion). This just shifts the source of truth to something completely non-standard and breaks the philosophy behind the migration -> local database -> models codgen approach this (and other codgen libs in other languages) follow.

[sheinbergon]

Regarding the unmaintainable large files - I find it odd that the whatever AI wrote this thinks this is an issue, but you're not supposed to do any maintenance aside from re-running this lib. If you have any missing features that require manual maintenance, please open GitHub issues and we'll do our best to fix them and release new versions.

[agronholm]

I agree with @sheinbergon 100%. The post reads like written by a clueless AI agent, and seems like complete nonsense.

[remiv1]

OK, I used AI Agent to write with a good english language, but idea was mine !

print("Thank's for time spent to make a response.")

Have a nice day !