Source code for codegen_database.ext.pg_cron

"""pg_cron extension for codegen_database.

:class:`PGCronExtension` wires pg_cron support into the codegen_database
lifecycle.  Register it on a
:class:`~codegen_database.config.CodegenDatabaseConfig` to
enable declarative cron job scheduling via
:class:`~codegen_database.ext.cron.base.CronJob` and
:class:`~codegen_database.ext.refresh.plugin.IncrementalRefreshPlugin`.

Usage::

    from codegen_database.config import CodegenDatabaseConfig
    from codegen_database.ext.pg_cron import PGCronExtension

    config = CodegenDatabaseConfig()
    config.use(PGCronExtension())

After registration, any
:class:`~codegen_database.ext.cron.base.CronJob` stored in metadata
(e.g. by
:class:`~codegen_database.ext.refresh.plugin.IncrementalRefreshPlugin`
with a ``schedule`` argument) will be diffed against the live ``cron.job``
table during ``alembic revision --autogenerate``.  Alembic emits
``op.execute("SELECT cron.schedule(...)")`` for new or changed jobs.

The extension also auto-declares the ``pg_cron`` PostgreSQL extension in
metadata so that the Alembic comparator can emit
``CREATE EXTENSION IF NOT EXISTS pg_cron CASCADE`` when needed.

Convenience re-exports::

    from codegen_database.ext.pg_cron import (
        PGCronExtension,
        CronJob,
        register_cron_job,
        PGExtension,
        register_pg_extension,
    )
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING

from codegen_database.ext.cron.alembic import register_cron_alembic_events
from codegen_database.ext.cron.base import CronJob, register_cron_job
from codegen_database.extension import CodegenDatabaseExtension
from codegen_database.pg_extension import (
    PGExtension,
    register_pg_extension,
)

if TYPE_CHECKING:
    from sqlalchemy import MetaData

__all__ = [
    "CronJob",
    "PGCronExtension",
    "PGExtension",
    "register_cron_job",
    "register_pg_extension",
]

_PG_CRON_EXTENSION = PGExtension("pg_cron", schema="cron", cascade=True)




@dataclass
class PGCronExtension(CodegenDatabaseExtension):
    """Wire pg_cron support into the codegen_database lifecycle.

    When registered on a
    :class:`~codegen_database.config.CodegenDatabaseConfig`:

    - ``configure_metadata`` declares ``pg_cron`` as a required
      PostgreSQL extension so Alembic can create it when absent.
    - ``configure_alembic`` registers the cron job comparator and
      renderer so ``alembic revision --autogenerate`` emits
      ``SELECT cron.schedule(...)`` for new or changed jobs, and
      the extension comparator so
      ``CREATE EXTENSION IF NOT EXISTS pg_cron CASCADE`` is emitted
      when pg_cron is missing.

    Plugins that use pg_cron (e.g.
    :class:`~codegen_database.ext.refresh.plugin.IncrementalRefreshPlugin`
    with a ``schedule`` argument) call
    :func:`~codegen_database.pg_extension.assert_pg_extension_declared` to
    verify this extension is registered, giving a clear error message
    when it is absent.

    Args:
        name: Extension name.  Defaults to ``"pg_cron"``.

    """

    name: str = "pg_cron"



    def configure_metadata(self, metadata: MetaData) -> None:
        """Declare pg_cron as a required PostgreSQL extension."""
        register_pg_extension(metadata, _PG_CRON_EXTENSION)




    def configure_alembic(self) -> None:
        """Register cron and extension Alembic comparators/renderers."""
        register_cron_alembic_events()