riverqueue 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce8622d0f151131d632d673e694e8ea90ded0502ba912274c7d044076063ee9
-  data.tar.gz: 1df7e4f2f10a3cfe36d3d08793a38b5400bf12dd32c3db3d3fd248184523d961
+  metadata.gz: c862e762c9679461633535e60ce0063ea7cad3fbe42d1f4b35c97350826ee3e0
+  data.tar.gz: 9a80c1852a2d587408fdc8e4c0c0c6b1af20bba5c60c0b777787f87248eb4cc9
 SHA512:
-  metadata.gz: c09ee3fefb3b0d9bdb4bd969761117470a84b7bcfa1278819446471c53348356ddffea3fa424d0cf086f57b1134ec49c1d470d03314286d21d50c9d1670568a4
-  data.tar.gz: a79a913f6f455f8a6a14e989ae72c415adb39248d97c1457b2cfd077b74ce41676e1f3bc79239d4a33d2653485074de7a8a6fd414699fec2e30b97c1fedb3d11
+  metadata.gz: 1b189d118fbb38fbf14f961ce645505c0a47e28421c1b0af11154c2dde5d6d057a4ddf25f88b4fc5a3d8f602c931db792281d89a73c8d0dab230fb9266aab1d4
+  data.tar.gz: ebf174f14f464c6be842647ddfc3a23a5ee3b33ffd84ce8c10b471849192bedcbc1e05db8e15d457ccf6cfbdfe8e3c04090882c636abb9fa2b6111ad2ffd483b

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-30
+
+### Added
+
+- Add `river migrate-get` for offline Postgres/SQLite SQL export with version selection, exclusions, and schema substitution; `river validate` to check migration state without applying changes; and `river version` / `river --version` to report active core, Pro, and Ruby runtime versions. Export and validation support `--line pro`. [PR #1560](https://github.com/riverqueue/river/pull/1560).
+
 ## [0.14.0] - 2026-10-26
 
 ### Added

data/docs/migrations.md

@@ -40,6 +40,68 @@ bundle exec river migrate-down --database-url postgres://localhost/my_app --yes
 Down migrations can delete jobs and other data. Back up the database and stop
 workers first. `--target 0 --yes` removes the complete selected migration line.
 
+## Validating migration state
+
+Use `validate` in a deployment check to require every bundled migration in the
+selected line to be applied:
+
+```sh
+bundle exec river validate --database-url postgres://localhost/my_app
+bundle exec river validate --database-url postgres://localhost/my_app --line pro
+```
+
+Validation exits with status 0 and no output when the selected line is current.
+Pending migrations are listed on stderr with exit status 1. Invalid history or
+connection errors also return 1. Validation reads migration history without
+applying migrations or changing data; it does not inspect individual tables or
+columns for schema drift. It accepts the same `DATABASE_URL`, `--schema`, and
+driver selection as the migration commands. Validate main and Pro separately.
+
+## Version information
+
+`version` and the top-level `--version` flag print the active core gem version
+and Ruby runtime version, plus the Pro gem version when `riverqueue-pro` is
+active in the bundle:
+
+```sh
+bundle exec river version
+bundle exec river --version
+```
+
+Neither command connects to a database or loads a database adapter. The
+`--version` option on `migrate-get` still selects migration versions to export.
+
+## Exporting SQL for other frameworks
+
+`migrate-get` prints SQL without connecting to a database or requiring a River
+driver gem. Select exactly one of `--version` or `--all`, and one of `--up` or
+`--down`:
+
+```sh
+bundle exec river migrate-get --version 3 --up > river3.up.sql
+bundle exec river migrate-get --version 3 --down > river3.down.sql
+bundle exec river migrate-get --all --exclude-version 1 --up > river_all.up.sql
+bundle exec river migrate-get --all --exclude-version 1 --down > river_all.down.sql
+```
+
+`--version` and `--exclude-version` accept comma-separated values and may be
+repeated. Explicit versions retain the supplied order. `--all` exports up SQL
+in ascending order and down SQL in descending order. Version 1 creates River's
+migration-tracking table and can usually be omitted with another framework.
+Preserve version boundaries and apply each migration in its own transaction.
+
+Export defaults to Postgres and ignores `DATABASE_URL`. Use
+`--database-url sqlite://` (or `sqlite3://`) to select SQLite SQL; the URL is only
+a dialect hint. `--schema jobs` qualifies Postgres objects with that schema.
+Without it, objects are unqualified. Schema placeholders are always substituted.
+
+With `riverqueue-pro` installed, export Pro's bundled SQL using the same command:
+
+```sh
+bundle exec river migrate-get --line pro --version 1 --up > river_pro_1.up.sql
+bundle exec river migrate-get --line pro --version 1 --down > river_pro_1.down.sql
+```
+
 ## Ruby API
 
 ```ruby

data/lib/cli.rb

@@ -5,14 +5,16 @@ require_relative "migration_cli"
 require_relative "worker_runner"
 
 module River
-  # Shared command dispatch for migrations and dedicated worker processes.
+  # Shared command dispatch for migrations, version information, and workers.
   module CLI
     # Runs a River command and returns its process exit status.
     def self.run(argv, err: $stderr, out: $stdout)
+      return version(argv.drop(1), err: err, out: out) if %w[version --version].include?(argv.first)
       return worker(argv.drop(1), out: out) if argv.first == "worker"
 
       if argv.empty? || %w[-h --help].include?(argv.first)
-        out.puts("Usage: river worker|migrate-up|migrate-down|migrate-status [options]")
+        out.puts("Usage: river worker|migrate-up|migrate-down|migrate-get|migrate-status|validate|version [options]")
+        out.puts("Use river --version to print gem and Ruby versions.")
         return 0
       end
 
@@ -22,6 +24,29 @@ module River
       1
     end
 
+    # Prints active gem versions and the Ruby runtime without loading adapters.
+    def self.version(argv, err:, out:)
+      parser = OptionParser.new do |args|
+        args.banner = "Usage: river version | river --version"
+        args.on("-h", "--help") do
+          out.puts(args)
+          return 0
+        end
+      end
+      args = argv.dup
+      parser.parse!(args)
+      raise ArgumentError, parser.banner unless args.empty?
+
+      out.puts("River version #{Gem.loaded_specs["riverqueue"]&.version || "(unknown)"}")
+      pro = Gem.loaded_specs["riverqueue-pro"]
+      out.puts("River Pro version #{pro.version}") if pro
+      out.puts("Ruby #{RUBY_VERSION}")
+      0
+    rescue ArgumentError, OptionParser::ParseError => error
+      err.puts("Version failed: #{error.message}")
+      1
+    end
+
     def self.worker(argv, out:)
       options = {} #: Hash[Symbol, untyped]
       parser = OptionParser.new do |args|

data/lib/migration_cli.rb

@@ -11,14 +11,21 @@ module River
       # @type var active_record_base: untyped
       options = {line: "main"} #: Hash[Symbol, untyped]
       parser = OptionParser.new do |args|
-        args.banner = "Usage: river migrate-up|migrate-down|migrate-status [options]"
-        args.on("--database-url URL", "Defaults to DATABASE_URL") { |value| options[:url] = value }
+        args.banner = "Usage: river migrate-up|migrate-down|migrate-get|migrate-status|validate [options]"
+        args.on("--database-url URL", "Defaults to DATABASE_URL; migrate-get uses only the dialect (default: Postgres)") { |value| options[:url] = value }
         args.on("--line NAME", %w[main pro]) { |value| options[:line] = value }
         args.on("--schema NAME") { |value| options[:schema] = value }
         args.on("--steps N", Integer) { |value| options[:steps] = value }
         args.on("--target VERSION", Integer) { |value| options[:target] = value }
         args.on("--dry-run") { options[:dry_run] = true }
         args.on("--yes", "Confirm destructive down migrations") { options[:yes] = true }
+        args.separator ""
+        args.separator "migrate-get: export SQL without a database connection or driver gem"
+        args.on("--all", "Export all versions in migration order") { options[:all] = true }
+        args.on("--up", "Export up SQL") { options[:up] = true }
+        args.on("--down", "Export down SQL") { options[:down] = true }
+        args.on("--version N[,N...]", "Versions in the supplied order; repeatable") { |value| (options[:version] ||= []).concat(parse_versions(value, "--version")) }
+        args.on("--exclude-version N[,N...]", "Versions to omit; repeatable") { |value| (options[:exclude_version] ||= []).concat(parse_versions(value, "--exclude-version")) }
         args.on("-h", "--help") {
           out.puts(args)
           return 0
@@ -28,7 +35,19 @@ module River
       args = argv.dup
       parser.parse!(args)
       command = args.shift
-      raise ArgumentError, parser.banner unless %w[migrate-up migrate-down migrate-status].include?(command) && args.empty?
+      raise ArgumentError, parser.banner unless %w[migrate-up migrate-down migrate-get migrate-status validate].include?(command) && args.empty?
+
+      incompatible_options = options.keys & ((command == "migrate-get") ? %i[dry_run steps target yes] : %i[all down exclude_version up version])
+      incompatible_options |= options.keys & %i[dry_run steps target yes] if command == "validate"
+      unless incompatible_options.empty?
+        raise ArgumentError, "#{incompatible_options.map { |key| "--#{key.to_s.tr("_", "-")}" }.join(", ")} cannot be used with #{command}"
+      end
+
+      if options[:line] == "pro"
+        require "riverqueue-pro"
+      end
+      migrator_class = (options[:line] == "pro") ? River.const_get(:Pro).const_get(:Migrator) : River::Migrator
+      return export(options, migrator_class, out: out) if command == "migrate-get"
 
       url = options[:url] || ENV["DATABASE_URL"]
       raise ArgumentError, "provide --database-url or DATABASE_URL" if url.nil? || url.empty?
@@ -39,11 +58,6 @@ module River
 
       adapter = detect_driver
 
-      if options[:line] == "pro"
-        require "riverqueue-pro"
-      end
-
-      migrator_class = (options[:line] == "pro") ? River.const_get(:Pro).const_get(:Migrator) : River::Migrator
       if adapter == "activerecord"
         require "riverqueue-activerecord"
         active_record_base = Object.const_get("ActiveRecord::Base")
@@ -56,7 +70,13 @@ module River
       end
 
       migrator = migrator_class.new(driver, schema: options[:schema])
-      if command == "migrate-status"
+      if command == "validate"
+        pending = migrator.status.reject(&:applied)
+        unless pending.empty?
+          err.puts("unapplied migrations: #{pending.map(&:version).join(", ")}")
+          return 1
+        end
+      elsif command == "migrate-status"
         migrator.status.each { |migration| out.puts("#{migration.applied ? "applied" : "pending"} #{migration.version.to_s.rjust(3, "0")} #{migration.name}") }
       else
         migrations = migrator.migrate(direction: (command == "migrate-up") ? :up : :down,
@@ -86,5 +106,52 @@ module River
       driver
     end
     private_class_method :detect_driver
+
+    def self.export(options, migrator_class, out:)
+      versions = options.fetch(:version, [])
+      excluded = options.fetch(:exclude_version, [])
+      raise ArgumentError, "pass exactly one of --all or --version" if !!options[:all] == versions.any?
+      raise ArgumentError, "pass exactly one of --up or --down" if !!options[:up] == !!options[:down]
+
+      backend = case options[:url] || "postgres://"
+      when /\Apostgres(?:ql)?:/i then :postgresql
+      when /\Asqlite3?:/i then :sqlite
+      else raise ArgumentError, "--database-url must use postgres:, postgresql:, sqlite:, or sqlite3:"
+      end
+      schema = options[:schema]
+      raise ArgumentError, "SQLite does not support a migration schema option" if backend == :sqlite && schema
+      raise ArgumentError, "schema must be a simple SQL identifier" if schema && !schema.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+      migrations = migrator_class.migrations(backend: backend, line: options[:line])
+      selected = if options[:all]
+        options[:down] ? migrations.reverse : migrations
+      else
+        versions.map do |version|
+          migrations.find { |migration| migration.version == version } || raise(ArgumentError, "migration #{version} does not exist")
+        end
+      end
+      selected = selected.reject { |migration| excluded.include?(migration.version) }
+      direction = options[:down] ? "down" : "up"
+      selected.each_with_index do |migration, index|
+        out.puts if index.positive?
+        out.puts("-- River #{options[:line]} migration #{migration.version.to_s.rjust(3, "0")} [#{direction}]")
+        sql = options[:down] ? migration.sql_down : migration.sql_up
+        out.puts(sql.gsub("/* TEMPLATE: schema */", schema ? %("#{schema}".) : "").strip)
+      end
+      0
+    end
+    private_class_method :export
+
+    def self.parse_versions(value, flag)
+      raise ArgumentError, "#{flag} must contain positive integers separated by commas" unless value.match?(/\A[0-9]+(?:,[0-9]+)*\z/)
+
+      value.split(",").map do |entry|
+        version = Integer(entry, 10)
+        raise ArgumentError, "#{flag} must contain positive integers" unless version.positive?
+
+        version
+      end
+    end
+    private_class_method :parse_versions
   end
 end

data/lib/migrator.rb

@@ -15,22 +15,29 @@ module River
     def initialize(driver, line: "main", migrations_path: File.expand_path("../migration", __dir__.to_s), schema: nil)
       @backend = driver.migration_backend
       @driver = driver
-      raise ArgumentError, "unsupported migration backend" unless [:postgresql, :sqlite].include?(@backend)
-      raise ArgumentError, "invalid migration line" unless line.match?(/\A[a-z][a-z0-9_]*\z/)
       raise ArgumentError, "SQLite does not support a migration schema option" if @backend == :sqlite && schema
 
       @line = line
+      @migrations = Migrator.migrations(backend: @backend, line: line, migrations_path: migrations_path)
       @mutex = Mutex.new
       @requested_schema = schema
+    end
 
-      directory = File.join(migrations_path, @backend.to_s, line)
-      @migrations = Dir.glob(File.join(directory, "*.up.sql")).sort.map do |path|
+    # Returns bundled SQL without a driver or database connection.
+    def self.migrations(backend: :postgresql, line: "main", migrations_path: File.expand_path("../migration", __dir__.to_s))
+      raise ArgumentError, "unsupported migration backend" unless [:postgresql, :sqlite].include?(backend)
+      raise ArgumentError, "invalid migration line" unless line.match?(/\A[a-z][a-z0-9_]*\z/)
+
+      directory = File.join(migrations_path, backend.to_s, line)
+      migrations = Dir.glob(File.join(directory, "*.up.sql")).sort.map do |path|
         version, name = File.basename(path).delete_suffix(".up.sql").split("_", 2)
         Migration.new(Integer(version.to_s, 10), name, File.read(path).freeze, File.read(path.sub(/\.up\.sql\z/, ".down.sql")).freeze)
       end.freeze
-      unless @migrations.any? && @migrations.map(&:version) == (1..@migrations.length).to_a
+      unless migrations.any? && migrations.map(&:version) == (1..migrations.length).to_a
         raise ArgumentError, "migration files must contain contiguous versions starting at 1"
       end
+
+      migrations
     end
 
     # Applies pending migrations up (all by default) or down (one by default).

data/sig/migrator.rbs

@@ -5,6 +5,8 @@ end
 module River
   module MigrationCLI
     def self.detect_driver: () -> String
+    def self.export: (Hash[Symbol, untyped], untyped, out: untyped) -> Integer
+    def self.parse_versions: (String, String) -> Array[Integer]
     def self.run: (Array[String], ?err: untyped, ?out: untyped) -> Integer
   end
   class Migrator
@@ -31,6 +33,7 @@ module River
     @schema: untyped
     attr_reader migrations: Array[Migration]
     def initialize: (untyped, ?line: String, ?migrations_path: String, ?schema: untyped) -> void
+    def self.migrations: (?backend: Symbol, ?line: String, ?migrations_path: String) -> Array[Migration]
     def migrate: (?direction: Symbol, ?dry_run: bool, ?steps: untyped, ?target: untyped) -> Array[Migration]
     def status: () -> Array[Status]
     private

data/sig/worker_runner.rbs

@@ -1,3 +1,7 @@
+class Gem::BasicSpecification
+  attr_reader version: Gem::Version
+end
+
 module Process
   def self.exit!: (?Integer) -> bot
 end
@@ -5,6 +9,7 @@ end
 module River
   module CLI
     def self.run: (Array[String], ?err: untyped, ?out: untyped) -> Integer
+    def self.version: (Array[String], err: untyped, out: untyped) -> Integer
     def self.worker: (Array[String], out: untyped) -> Integer
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riverqueue
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Blake Gentry