Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• cron_ext/extension.py
• cron_ext/entry.py
• cron_ext/main.py
• cron_ext/stores/crontab.py
• cron_ext/stores/base.py
• cron_ext/stores/stdout.py

cron-ext is a Meltano utility extension designed to provide job scheduling by bridging Meltano schedules with the system's cron daemon. It automates the generation of executable shell scripts for Meltano tasks and manages their lifecycle within a system crontab. The extension translates Meltano-native schedule definitions into standard cron syntax while maintaining isolation between different Meltano projects through project-specific identifiers in the crontab.

Sources: README.md:1-10, cron_ext/extension.py:27-50

Core Components

The system is built on three primary pillars: the CLI Entrypoint, the Extension Logic, and the Storage Layer.

1. CLI Entrypoint (main.py)

Built using the typer library, this layer handles user interaction and command-line arguments. It maps user commands like install, uninstall, and list to the underlying Cron extension logic.

2. Extension Logic (extension.py)

The Cron class, inheriting from ExtensionBase, contains the core business logic. It interacts with the Meltano system to retrieve schedule metadata, generates wrapper shell scripts in the .meltano/run/cron-ext/ directory, and coordinates updates to the chosen storage target.
Sources: cron_ext/extension.py:27-44, cron_ext/main.py:19-25

3. Storage Layer (stores/)

The storage layer provides an abstraction for where cron entries are persisted. It uses a strategy pattern to support different output targets.
Sources: cron_ext/stores/base.py:10-28

Component	Description	Relevant File
EntryStore	Abstract base class defining the interface for reading/writing cron entries.	cron_ext/stores/base.py
CrontabEntryStore	Manages persistent entries in the actual system crontab using crontab -l and crontab -.	cron_ext/stores/crontab.py
StdoutEntryStore	A non-managed store that simply prints generated cron lines to the terminal.	cron_ext/stores/stdout.py

Data Flow: Schedule Installation

The installation process involves querying Meltano for active schedules, generating executable bash scripts that encapsulate environment variables, and updating the crontab within a protected project-specific block.

The diagram shows the flow from the user command to the final system crontab update.
Sources: cron_ext/extension.py:65-80, cron_ext/extension.py:105-125, cron_ext/stores/crontab.py:35-60

Script Generation and Execution

For every Meltano schedule, the extension creates a shell script that ensures the task runs in the correct context.

• Pathing: The script changes directory to the MELTANO_PROJECT_ROOT.
• Environment: It captures the PATH and VIRTUAL_ENV present during installation and merges them with schedule-specific environment variables.
• Logging: Execution output is piped to /usr/bin/logger -t meltano to ensure cron job logs are captured by the system logger.
• Permissions: Scripts are automatically granted execution permissions (stat.S_IXUSR).

# Internal script template logic
command_script.write_text(
    f"(cd '{self.meltano_project_dir}' && {env_str} "
    f"meltano {cmd} {args}) 2>&1 | /usr/bin/logger -t meltano\n"
)

Sources: cron_ext/extension.py:84-103, README.md:12-20

Management and Isolation

The extension manages isolation in the crontab by wrapping project entries in specific header and footer comments based on the MELTANO_PROJECT_ID.

Crontab Section Management

The CrontabEntryStore uses regex patterns to locate the block designated for the current project. This prevents the extension from interfering with other cron jobs or other Meltano projects on the same system.

The diagram illustrates how the CrontabEntryStore isolates project-specific schedules within the system crontab.
Sources: cron_ext/stores/crontab.py:88-105, cron_ext/entry.py:5-8

Orphaned Entry Detection

The list command can identify "orphaned" entries—cron jobs that exist in the crontab for the project but no longer have a corresponding schedule defined in meltano.yml. This is achieved by comparing entries matched by entry_pattern against the set of IDs returned by meltano schedule list.
Sources: cron_ext/main.py:44-55, cron_ext/extension.py:73-81

Conclusion

The architecture of meltano-cron-ext provides a robust bridge between Meltano's internal scheduling and the ubiquitous cron utility. By abstracting the storage layer and automating script generation with environment preservation, it ensures that Meltano tasks run reliably in a production-like environment while maintaining clean system configuration through project-based isolation.