Factories
=========

codegen_database factories generate SQLAlchemy tables, views, triggers,
functions, and Alembic migrations from declarative configuration.
Every factory sits on the same plugin-driven pipeline
(:doc:`plugins`), so ordering rules, singleton conflicts, and
extension hooks behave uniformly regardless of which factory you
pick.

Four factories ship out of the box:

- **Simple** -- one table, direct CRUD.  Best for reference data.
- **Append-only (SCD Type 2)** -- full change history via an
  append-only attributes log.  Best for slowly changing dimensions.
- **EAV** -- sparse attributes stored as rows and pivoted back to
  columns.  Best for highly dynamic or optional fields.
- **Ledger** -- an append-only event stream with running-balance,
  rollup, and chart helpers.  See :doc:`ledgers` for the full
  guide.

All factories support declarative
:class:`~codegen_database.check.CodegenDatabaseCheck`,
:class:`~codegen_database.index.CodegenDatabaseIndex`, and inline
:class:`~codegen_database.fk.CodegenDatabaseForeignKey` on columns.  See
:doc:`constraints_and_indices` for a walkthrough with generated
SQL.


Simple
------

A single backing table.  Suitable for reference data and simple
lookups that don't need change history.

**Example configuration:**

.. literalinclude:: ../scripts/examples/simple.py
   :language: python
   :start-after: # --- example start ---
   :end-before: # --- example end ---
   :dedent:

**Usage:**

.. literalinclude:: ../scripts/examples/simple.sql
   :language: sql

.. include:: _generated/dim_simple.rst


Append-only (SCD Type 2)
------------------------

Tracks full change history using an append-only attributes log.
Every update creates a new row in the attributes table; the root
table points to the latest version.  A join view presents the
current state.  Ideal for slowly changing dimensions where audit
trails matter.

**Example configuration:**

.. literalinclude:: ../scripts/examples/append_only.py
   :language: python
   :start-after: # --- example start ---
   :end-before: # --- example end ---
   :dedent:

**Usage** -- inserts and updates go through the factory view;
the triggers manage the internal tables:

.. literalinclude:: ../scripts/examples/append_only.sql
   :language: sql

.. include:: _generated/dim_append_only.rst


EAV (Entity-Attribute-Value)
----------------------------

Stores attributes as rows rather than columns, using typed value
columns (``string_value``, ``integer_value``, etc.) with a check
constraint enforcing exactly one non-null value per row.  A pivot
view reconstructs the familiar columnar layout.  Ideal for sparse
or highly dynamic attributes where most entities only have a
subset of possible fields.

**Example configuration:**

.. literalinclude:: ../scripts/examples/eav.py
   :language: python
   :start-after: # --- example start ---
   :end-before: # --- example end ---
   :dedent:

**Usage** -- the factory view looks like a normal table; the
triggers decompose columns into EAV rows behind the scenes:

.. literalinclude:: ../scripts/examples/eav.sql
   :language: sql

.. include:: _generated/dim_eav.rst


Ledger
------

:class:`~codegen_database.factory.ledger.CodegenDatabaseLedger` generates an
append-only event stream designed for inventory, double-entry
accounting, audit trails, and any other append-only delta model.
On top of the event stream codegen_database ships a toolbox of query and
function builders: per-period rollups, running-balance windows,
gap-filled period axes, rollup charts, and a double-entry
specialization that normalizes deltas by each account's
``normal_side``.

The chart helpers depend on :ref:`ext-chart` for the
``codegen_database_date_bin`` polyfill.

See :doc:`ledgers` for the full walkthrough with worked
examples, and :doc:`ledger_actions` for attaching named
PostgreSQL functions to a ledger.