pg_cron 2.0.0

data/lib/generators/pg_cron/version_helper.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PgCron
+  module Generators
+    # Works out which version of a definition we are creating.
+    #
+    # Copied from Fx::Generators::VersionHelper. The scan is over db/cron rather
+    # than db/functions, and there is one type instead of two, so
+    # definition_for_version takes no `type`.
+    #
+    # @api private
+    class VersionHelper
+      def initialize(file_name:, definition_path:)
+        @file_name = file_name
+        @definition_path = definition_path
+      end
+
+      def previous_version
+        @previous_version ||= existing_versions.max || 0
+      end
+
+      def current_version
+        previous_version.next
+      end
+
+      def updating_existing?
+        previous_version > 0
+      end
+
+      def creating_new?
+        previous_version == 0
+      end
+
+      def definition_for_version(version:)
+        PgCron::Definition.job(name: file_name, version: version)
+      end
+
+      private
+
+      VERSION_PATTERN = /v(\d+)/
+      private_constant :VERSION_PATTERN
+
+      attr_reader :file_name, :definition_path
+
+      def existing_versions
+        Dir
+          .glob("#{file_name}_v*.sql", base: definition_path)
+          .map { |file| file[VERSION_PATTERN, 1].to_i }
+          .compact
+      end
+    end
+  end
+end

data/lib/pg_cron/adapters/postgres/connection.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module PgCron
+  module Adapters
+    class Postgres
+      # Decorates an ActiveRecord connection with methods that help determine
+      # the connection's capabilities.
+      #
+      # The F(x) equivalent asks about DROP FUNCTION argument lists. The
+      # capability that matters here is whether pg_cron is installed at all:
+      # cron.job does not exist until CREATE EXTENSION pg_cron has run, and that
+      # additionally requires pg_cron in shared_preload_libraries and a server
+      # restart. Every caller checks this first so a migration or a schema dump
+      # against a database without cron is a no-op rather than an error.
+      #
+      # @api private
+      class Connection < SimpleDelegator
+        def pg_cron_enabled?
+          extension_enabled?("pg_cron")
+        end
+      end
+    end
+  end
+end

data/lib/pg_cron/adapters/postgres/jobs.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "pg_cron/job"
+require "pg_cron/adapters/postgres/query_executor"
+
+module PgCron
+  module Adapters
+    class Postgres
+      # Fetches scheduled jobs from the postgres connection.
+      #
+      # The F(x) counterpart is Adapters::Postgres::Functions, which reads
+      # pg_proc. This reads cron.job — pg_cron's own catalogue.
+      #
+      # @api private
+      class Jobs
+        # The query used to retrieve the jobs considered dumpable into
+        # `db/schema.rb`.
+        #
+        # jobname can be NULL: cron.schedule() has an arity that does not take
+        # one. Such a job cannot be expressed as create_cron_job, which is keyed
+        # by name, so it is excluded rather than dumped wrongly.
+        JOBS_WITH_DEFINITIONS_QUERY = <<~SQL.freeze
+          SELECT
+              jobname,
+              schedule,
+              command,
+              database,
+              username,
+              active
+          FROM cron.job
+          WHERE jobname IS NOT NULL
+          ORDER BY jobname;
+        SQL
+
+        # Wraps #all as a static facade.
+        #
+        # @return [Array<PgCron::Job>]
+        def self.all(connection)
+          PgCron::Adapters::Postgres::QueryExecutor.call(
+            connection: connection,
+            query: JOBS_WITH_DEFINITIONS_QUERY,
+            model_class: PgCron::Job
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pg_cron/adapters/postgres/query_executor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PgCron
+  module Adapters
+    class Postgres
+      # Executes database queries and maps results to domain objects.
+      #
+      # Copied from Fx::Adapters::Postgres::QueryExecutor.
+      #
+      # @api private
+      class QueryExecutor
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(connection:, query:, model_class:)
+          @connection = connection
+          @query = query
+          @model_class = model_class
+        end
+
+        # @return [Array] Array of domain objects
+        def call
+          results_from_postgres.map { |result| model_class.new(result) }
+        end
+
+        private
+
+        attr_reader :connection, :query, :model_class
+
+        def results_from_postgres
+          connection.execute(query)
+        end
+      end
+    end
+  end
+end

data/lib/pg_cron/adapters/postgres.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "pg_cron/adapters/postgres/connection"
+require "pg_cron/adapters/postgres/jobs"
+
+module PgCron
+  # Database adapters.
+  #
+  # Ships with a Postgres adapter only — pg_cron is a Postgres extension, so
+  # there is no other engine to support — but the interface is the same one F(x)
+  # defines, so an alternative could be substituted the same way.
+  module Adapters
+    # The Postgres adapter.
+    #
+    # @param [#connection] connectable An object that returns the connection to
+    #   use. Defaults to `ActiveRecord::Base`.
+    #
+    # @example
+    #  PgCron.configure do |config|
+    #    config.adapter = PgCron::Adapters::Postgres.new
+    #  end
+    class Postgres
+      def initialize(connectable = ActiveRecord::Base)
+        @connectable = connectable
+      end
+
+      # Whether pg_cron is installed in this database.
+      #
+      # Every statement checks this first, so a migration that schedules a job
+      # still runs against a database without the extension — a test database,
+      # or an environment where cron is not wanted — instead of every such
+      # migration needing its own guard.
+      def pg_cron_enabled?
+        connection.pg_cron_enabled?
+      end
+
+      # Every scheduled job in the database.
+      #
+      # Used by {PgCron::SchemaDumper} to populate `schema.rb`. Returns
+      # nothing when pg_cron is not installed, because cron.job does not exist
+      # then and a schema dump must not fail on a database that simply has no
+      # cron.
+      #
+      # @return [Array<PgCron::Job>]
+      def jobs
+        return [] unless connection.pg_cron_enabled?
+
+        PgCron::Adapters::Postgres::Jobs.all(connection)
+      end
+
+      # Creates a job in the database.
+      #
+      # The definition is executed AS GIVEN — it is the cron.schedule() call from
+      # db/cron/<name>_v01.sql, so the schedule, the command and any quoting are
+      # that file's business. This neither parses nor rewrites it, which is the
+      # substantive difference from assembling SQL by interpolating values: a
+      # name or command containing a quote produced broken SQL that way.
+      #
+      # @param sql_definition [String] The SQL for the job.
+      # @return [void]
+      def create_job(sql_definition)
+        execute(sql_definition)
+      end
+
+      # Updates a job in the database.
+      #
+      # NOT drop-then-create, which is what F(x) does for a function: pg_cron's
+      # cron.schedule() against an existing jobname REPLACES that job, so the
+      # update is a single statement. Dropping first would leave a window with
+      # no schedule, and on a frequently-firing job that window is a missed run.
+      #
+      # The existence check is deliberate — cron.schedule() would otherwise
+      # silently CREATE a job that was expected to be there, hiding a migration
+      # applied out of order.
+      #
+      # @param name [String, Symbol] The name of the job.
+      # @param sql_definition [String] The SQL for the job.
+      # @return [void]
+      def update_job(name, sql_definition)
+        connection.transaction do
+          unless job_exists?(name)
+            raise PG::InternalError, "ERROR: could not find valid entry for job '#{name}'"
+          end
+
+          execute(sql_definition)
+        end
+      end
+
+      # Drops the job from the database.
+      #
+      # @param name [String, Symbol] The name of the job to drop.
+      # @return [void]
+      def drop_job(name)
+        execute("SELECT cron.unschedule(#{quoted(name)});")
+      end
+
+      private
+
+      attr_reader :connectable
+
+      delegate :execute, to: :connection
+
+      def connection
+        PgCron::Adapters::Postgres::Connection.new(connectable.connection)
+      end
+
+      def job_exists?(name)
+        execute("SELECT 1 FROM cron.job WHERE jobname = #{quoted(name)}").any?
+      end
+
+      def quoted(name)
+        "'#{name.to_s.gsub("'", "''")}'"
+      end
+    end
+  end
+end

data/lib/pg_cron/command_recorder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PgCron
+  # Makes the statements reversible, following F(x)'s CommandRecorder.
+  #
+  # The `revert_to_version` handling is the point. Inverting create_cron_job is
+  # a drop, but inverting DROP or UPDATE is only meaningful if the migration
+  # said what to go back to — otherwise a rollback either fails or, worse,
+  # leaves the job missing. That is why the previous schedule_pg_cron_job /
+  # unschedule_pg_cron_job pair could not invert an update at all.
+  module CommandRecorder
+    def create_cron_job(*args, &block)
+      record(:create_cron_job, args, &block)
+    end
+
+    def drop_cron_job(*args, &block)
+      record(:drop_cron_job, args, &block)
+    end
+
+    def update_cron_job(*args, &block)
+      record(:update_cron_job, args, &block)
+    end
+
+    def invert_create_cron_job(args)
+      [:drop_cron_job, args.first]
+    end
+
+    def invert_drop_cron_job(args)
+      perform_cron_job_inversion(:create_cron_job, args)
+    end
+
+    def invert_update_cron_job(args)
+      perform_cron_job_inversion(:update_cron_job, args)
+    end
+
+    private
+
+    def perform_cron_job_inversion(method, args)
+      name, options = args
+      options ||= {}
+
+      unless options[:revert_to_version]
+        message = "`#{method}` is reversible only if given a `revert_to_version`"
+        raise ActiveRecord::IrreversibleMigration, message
+      end
+
+      [method, [name, { version: options[:revert_to_version] }]]
+    end
+  end
+end

data/lib/pg_cron/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PgCron
+  class Configuration
+    # Kept for anything still referencing it. PgCron::Definition owns the real
+    # path; a literal rather than an interpolation of Definition::DIRECTORY so
+    # this does not depend on require order.
+    JOBS_DIRECTORY = "db/cron"
+
+    # The adapter used to run cron statements. Defaults to the Postgres adapter
+    # over the application's own connection.
+    attr_reader :adapter
+
+    def initialize(adapter: PgCron::Adapters::Postgres.new)
+      @adapter = adapter
+    end
+
+    attr_writer :adapter
+
+    # Retained so `PgCronRails.connection`-era callers keep working.
+    def connection
+      adapter
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.database
+    configuration.adapter
+  end
+end

data/lib/pg_cron/definition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PgCron
+  # Resolves a job name and version to its definition file.
+  #
+  # Modelled on F(x)'s Fx::Definition: versioned SQL files, looked up first
+  # alongside any engine's migration paths and then in the app's own db/.
+  #
+  # SQL rather than the YAML this gem used to read. A job's body is a SQL
+  # statement either way, so YAML meant a SQL string embedded in a YAML scalar —
+  # nothing could syntax-check it, dollar-quoting had to survive two levels of
+  # escaping, and the schema dumper could not round-trip it. A .sql file holds
+  # the cron.schedule() call verbatim.
+  #
+  # @api private
+  class Definition
+    JOB = "job"
+
+    # `db/cron`, singular. F(x) derives its directory from the type
+    # ("function" -> db/functions) because it manages two kinds of object; this
+    # gem manages one, and "db/jobs" would read like Active Job's queues rather
+    # than the database's schedule.
+    DIRECTORY = "cron"
+
+    def self.job(name:, version:)
+      new(name: name, version: version, type: JOB)
+    end
+
+    def initialize(name:, version:, type: JOB)
+      @name = name
+      @version_number = version.to_i
+      @type = type
+    end
+
+    def to_sql
+      content = File.read(find_file || full_path)
+      raise "Define #{type} in #{path} before migrating." if content.empty?
+
+      content
+    end
+
+    def full_path
+      Rails.root.join(path)
+    end
+
+    def path
+      @_path ||= File.join("db", DIRECTORY, filename)
+    end
+
+    def version
+      version_number.to_s.rjust(2, "0")
+    end
+
+    private
+
+    attr_reader :name, :version_number, :type
+
+    def filename
+      @_filename ||= "#{name}_v#{version}.sql"
+    end
+
+    # Engines can ship a db/cron beside their migrations; look there before
+    # falling back to the host application's.
+    def find_file
+      migration_paths.lazy
+        .map { |migration_path| File.expand_path(File.join("..", "..", path), migration_path) }
+        .find { |definition_path| File.exist?(definition_path) }
+    end
+
+    def migration_paths
+      Rails.application.config.paths["db/migrate"].expanded
+    end
+  end
+end

data/lib/pg_cron/job.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PgCron
+  # A scheduled job as it exists in cron.job, and how it is written back into
+  # db/schema.rb.
+  #
+  # F(x)'s equivalent is Fx::Function, whose identity is a signature — name plus
+  # argument types, because Postgres allows overloads. A cron job has none:
+  # pg_cron keys on jobname, so the name is the identity and scheduling over an
+  # existing name replaces it.
+  #
+  # @api private
+  class Job
+    include Comparable
+
+    attr_reader :name, :schedule, :command, :database, :username, :active
+
+    def initialize(row)
+      @name = row.fetch("jobname")
+      @schedule = row.fetch("schedule")
+      @command = row.fetch("command")
+      @database = row.fetch("database", nil)
+      @username = row.fetch("username", nil)
+      @active = row.fetch("active", nil)
+    end
+
+    def <=>(other)
+      name <=> other.name
+    end
+
+    def ==(other)
+      name == other.name && definition == other.definition
+    end
+
+    # Rebuilt as a cron.schedule() call rather than dumped verbatim: pg_cron
+    # stores the PARTS (jobname, schedule, command) in cron.job and keeps no
+    # record of the statement that created them, so there is nothing to quote
+    # back. This is the same reason F(x) can use pg_get_functiondef and this
+    # cannot.
+    #
+    # The command is dollar-quoted because any non-trivial SQL command contains
+    # quotes of its own. $job$ rather than $$ so a command that itself uses $$
+    # (a plpgsql body, say) still nests correctly.
+    def definition
+      <<~SQL
+        SELECT cron.schedule(
+            #{quote(name)},
+            #{quote(schedule)},
+            $job$#{command}$job$
+        );
+      SQL
+    end
+
+    def to_schema
+      <<~SCHEMA.indent(2)
+        create_cron_job :#{name}, sql_definition: <<-'SQL'
+        #{definition.indent(4).rstrip}
+        SQL
+      SCHEMA
+    end
+
+    private
+
+    def quote(value)
+      "'#{value.to_s.gsub("'", "''")}'"
+    end
+  end
+end

data/lib/pg_cron/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module PgCron
+  class Railtie < ::Rails::Railtie
+    railtie_name :pg_cron
+
+    initializer "pg_cron.load" do
+      ActiveSupport.on_load :active_record do
+        PgCron.load
+      end
+    end
+
+    rake_tasks do
+      path = File.expand_path("..", __dir__)
+      Dir.glob("#{path}/tasks/**/*.rake").each do |task|
+        load task
+      end
+    end
+  end
+end

data/lib/pg_cron/schema_dumper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PgCron
+  # Writes scheduled jobs into db/schema.rb.
+  #
+  # F(x)'s SchemaDumper with `functions`/`triggers` replaced by `jobs`. Hooking
+  # #tables rather than #extensions is F(x)'s choice and is load-bearing:
+  # #extensions is private AND redefined by the PostgreSQL-specific dumper, so a
+  # module prepended to ActiveRecord::SchemaDumper never intercepts it and the
+  # dump silently comes out with no cron section.
+  #
+  # Emitted after super, so the cron block follows the tables and F(x)'s
+  # functions — which matters, because a create_cron_job line schedules a command
+  # that generally calls them.
+  #
+  # @api private
+  module SchemaDumper
+    def tables(stream)
+      super
+
+      jobs(stream)
+    end
+
+    private
+
+    def jobs(stream)
+      dumpable_jobs_in_database = PgCron.database.jobs
+
+      dumpable_jobs_in_database.each do |job|
+        stream.puts
+        stream.puts(job.to_schema)
+      end
+    end
+  end
+end