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.

.. list-table::
   :header-rows: 1
   :widths: 15 25 60

   * - 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
       :class:`~codegen_database.config.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
       :mod:`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 :mod:`codegen_database.ext` submodule bundles
       tables, views, functions, plugins and/or a
       :class:`~codegen_database.extension.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 :doc:`extensions`).

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>``.