Module: PgCron::Statements

Defined in:
lib/pg_cron/statements.rb

Overview

Migration methods for pg_cron schedules, following F(x)'s conventions exactly: a name, an optional version naming a file in db/cron, an optional sql_definition that takes its place, and revert_to_version so a rollback restores the previous definition instead of dropping the job outright.

Replaces schedule_pg_cron_job / unschedule_pg_cron_job / update_pg_cron_job, which took only a name and read a YAML file. Those had no versioning, so a changed schedule left no record of what it had been and a rollback could only delete the job.

Instance Method Summary collapse

Instance Method Details

#create_cron_job(name, version: nil, sql_definition: nil, revert_to_version: nil) ⇒ void

This method returns an undefined value.

Create a new cron job.

Examples:

Create from db/cron/drain_juicefs_events_v01.sql

create_cron_job(:drain_juicefs_events, version: 1)

Create from provided SQL string

create_cron_job(:drain_juicefs_events, sql_definition: <<~SQL)
  SELECT cron.schedule(
    'drain_juicefs_events',
    '* * * * *',
    $$SELECT juicefs_index_events(500)$$
  );
SQL

Parameters:

  • name (String, Symbol) —

    The job's name. pg_cron keys on jobname, so this is its identity — scheduling over an existing name replaces it.

  • version (Integer) (defaults to: nil) —

    The version number, used to find the definition file in db/cron. Defaults to 1.

  • sql_definition (String) (defaults to: nil) —

    The SQL for the job. An error is raised if sql_definition and version are both set, as they are mutually exclusive.



37
38
39
40
41
42
43
44
 
# File 'lib/pg_cron/statements.rb', line 37

def create_cron_job(name, version: nil, sql_definition: nil, revert_to_version: nil)
  validate_cron_version_and_sql_definition_exclusive!(version, sql_definition)
  version ||= 1

  return unless PgCron.database.pg_cron_enabled?

  PgCron.database.create_job(resolve_cron_sql_definition(sql_definition, name, version))
end

#drop_cron_job(name, revert_to_version: nil) ⇒ void

This method returns an undefined value.

Drop a cron job by name.

Parameters:

  • name (String, Symbol) —

    The job's name.

  • revert_to_version (Integer) (defaults to: nil) —

    Used to reverse this on rake db:rollback; passed as version to #create_cron_job.



53
54
55
56
57
 
# File 'lib/pg_cron/statements.rb', line 53

def drop_cron_job(name, revert_to_version: nil)
  return unless PgCron.database.pg_cron_enabled?

  PgCron.database.drop_job(name)
end

#update_cron_job(name, version: nil, sql_definition: nil, revert_to_version: nil) ⇒ void

This method returns an undefined value.

Update a cron job.

One statement, not unschedule-then-schedule: cron.schedule() against an existing jobname REPLACES that job. Dropping first would leave a window in which the schedule does not exist, and on a frequently-firing job that window is a missed run.

Parameters:

  • name (String, Symbol) —

    The job's name.

  • version (Integer) (defaults to: nil) —

    The version number, used to find the definition file in db/cron.

  • sql_definition (String) (defaults to: nil) —

    The SQL for the job.

  • revert_to_version (Integer) (defaults to: nil) —

    The version to roll back to.



73
74
75
76
77
78
79
80
 
# File 'lib/pg_cron/statements.rb', line 73

def update_cron_job(name, version: nil, sql_definition: nil, revert_to_version: nil)
  validate_cron_version_or_sql_definition_present!(version, sql_definition)
  validate_cron_version_and_sql_definition_exclusive!(version, sql_definition)

  return unless PgCron.database.pg_cron_enabled?

  PgCron.database.update_job(name, resolve_cron_sql_definition(sql_definition, name, version))
end