Module layout

codegen_database’s public API is split into three clearly-scoped buckets. Knowing which bucket a symbol lives in tells you when to reach for it and from where to import it.

Bucket

Import prefix

What lives here

Declarative primitives

codegen_database

Base classes, column types, view/function/check/FK/index helpers, plugin and extension base classes, and CodegenDatabaseConfig. These are the building blocks you compose to describe a schema.

Migration glue

codegen_database.alembic

The hooks you wire into your project’s env.py (alembic_hook, configure_metadata, render_item, process_revision_directives) plus the naming-convention dictionary. Everything else inside codegen_database.alembic is internal machinery and should not be imported by downstream code.

Pre-built features

codegen_database.ext

Ledgers, audit query builders, state machines, incremental refresh, cron, row-level security, chart helpers. Each codegen_database.ext submodule bundles tables, views, functions, plugins and/or a CodegenDatabaseExtension that composes primitives from the top level to solve a specific problem.

Why the split

  • Primitives are the only imports you need to read a codegen_database model file and understand what is being declared.

  • Migration glue is code that only runs at schema-change time, inside Alembic’s context. It is isolated so that regular application code never has to pull in Alembic machinery.

  • Pre-built features sit on top of the primitives. Each one is opt-in: you import it only if you want the behavior. Users can write their own package under the same convention (myproject.codegen_database_ext.X) and discover it via the codegen_database.ext entry point group (see Extension system).

Rule of thumb

If you are writing class MyTable(CodegenDatabaseBase), you only need imports from codegen_database. If you are wiring env.py, you only need imports from codegen_database.alembic. If you are reaching for a ledger query builder or a cron job, that lives in codegen_database.ext.<feature>.