Configuration
=============

:class:`~codegen_database.config.CodegenDatabaseConfig` is the central object for
project-wide codegen_database settings.  Create one per project and pass it to
every factory and to :func:`~codegen_database.alembic.register.configure_metadata`.

Creating a config
-----------------

.. code-block:: python

   from codegen_database.config import CodegenDatabaseConfig

   config = CodegenDatabaseConfig()

Fields
------

``plugins``
~~~~~~~~~~~

A list of :class:`~codegen_database.plugin.Plugin` instances that are prepended
to every factory's plugin list.  Use :meth:`~codegen_database.config.CodegenDatabaseConfig.register`
to add plugins after construction:

.. code-block:: python

   config.register(TimestampPlugin(), TenantPlugin())

   # or at construction time
   config = CodegenDatabaseConfig(plugins=[TimestampPlugin(), TenantPlugin()])

See :doc:`plugins` for details on plugin resolution order.

``extensions``
~~~~~~~~~~~~~~

A list of :class:`~codegen_database.extension.CodegenDatabaseExtension` instances.
Use :meth:`~codegen_database.config.CodegenDatabaseConfig.use` to add extensions:

See :doc:`extensions` for the full extension guide.

``auto_discover``
~~~~~~~~~~~~~~~~~

When ``True`` (the default), codegen_database discovers extensions registered
under the ``codegen_database.ext`` entry point group.  Manually
registered extensions take precedence over discovered ones with the
same name.

Set to ``False`` to disable automatic discovery:

.. code-block:: python

   config = CodegenDatabaseConfig(auto_discover=False)

``utility_schema``
~~~~~~~~~~~~~~~~~~

The PostgreSQL schema for codegen_database-managed shared objects.  One
setting governs them all -- the ``codegen_database_date_bin`` chart polyfill
(:ref:`ext-chart`) and the ``autogenerated_identifier_pointers``
table that backs ``CodegenDatabaseAutogeneratedIdentifierColumn``.
Defaults to ``"codegen_database"``.

Override this only if your project already uses a schema named
``codegen_database``:

.. code-block:: python

   config = CodegenDatabaseConfig(utility_schema="my_utils")

Methods
-------

.. method:: CodegenDatabaseConfig.register(*plugins) -> CodegenDatabaseConfig

   Add one or more plugins to the global plugin list.  Returns
   ``self`` for chaining.

.. method:: CodegenDatabaseConfig.use(*extensions) -> CodegenDatabaseConfig

   Register one or more extensions.  Returns ``self`` for chaining.

.. attribute:: CodegenDatabaseConfig.all_plugins

   Combined list of extension plugins followed by direct plugins.
   Extension plugins are prepended so they run first.

Typical project setup
---------------------

A common pattern is to create one config module and import it
wherever factories are defined:

.. code-block:: python

   # codegen_database_setup.py
   from codegen_database.config import CodegenDatabaseConfig
   from myapp.plugins import TimestampPlugin, TenantPlugin

   codegen_database_cfg = CodegenDatabaseConfig()
   codegen_database_cfg.register(TimestampPlugin(), TenantPlugin())

.. code-block:: python

   # models.py
   from myapp.codegen_database_setup import codegen_database_cfg
   from codegen_database.factory import CodegenDatabaseSimple

   CodegenDatabaseSimple(
       "users", "app", metadata, schema_items,
       config=codegen_database_cfg,
   )

.. code-block:: python

   # migrations/env.py
   from codegen_database.alembic.register import configure_metadata
   from myapp.codegen_database_setup import codegen_database_cfg

   configure_metadata(
       target_metadata, config=codegen_database_cfg,
   )