Support plain SQL migrations

This introduces ROM::SQL::Migration::SQLMigration, which allows you to
write migrations as a .sql file in the migration directory.

SQL migrations have a very simple grammar:

1. Files are organized into two directions (up and down). Each
   direction may contain one or more `begin..end` sections; all
   sections for a direction execute sequentially in source order
   at apply time. Each section keeps its own `split=` setting,
   so a single direction may mix splitting strategies across
   sections.
2. Directives are written as SQL line comments using the `-- @migrate`
   sigil. The leading `--` keeps directive lines valid SQL syntax (so
   editors, syntax highlighters, and linters treat them as comments);
   the `@migrate` sigil disambiguates them from author-written `--`
   comments. Plain `-- ...` comments without the `@migrate` sigil are
   treated as part of the SQL body and pass through verbatim.
3. Optional settings may be provided in a pragma line before the up/down sections
4. Pragma and begin lines accept `key=value` settings separated by spaces or tabs
5. Each direction begins with a direction directive followed by one
   or more begin directives
6. The begin directive may itself carry settings (e.g. statement splitting strategy)
7. Each section concludes with an end directive
8. Down migrations are optional, but they always must follow the up migration
9. Empty sections (begin..end with no SQL body) are silently skipped

Author: alassek

lib/rom/sql/errors.rb

@@ -19,6 +19,7 @@ module SQL
     MissingPrimaryKeyError    = Class.new(StandardError)
     MigrationError            = Class.new(StandardError)
     UnsupportedConversion     = Class.new(MigrationError)
+    SQLParseError             = Class.new(MigrationError)
 
     ERROR_MAP = {
       Sequel::DatabaseError => DatabaseError,

lib/rom/sql/migration/migrator.rb

@@ -9,6 +9,8 @@
 require 'rom/sql/migration/inline_runner'
 require 'rom/sql/migration/writer'
 
+Sequel.extension :sql_migrations
+
 module ROM
   module SQL
     module Migration

lib/rom/sql/migration/sql_migration.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+require "rom/sql/types"
+
+module ROM
+  module SQL
+    module Migration
+      # A single executable statement extracted from a `.sql` migration
+      # section, paired with the source line where it begins. The line is
+      # used to annotate backtraces when execution fails.
+      #
+      # @api private
+      Statement = Data.define(:sql, :line)
+
+      # A migration translated from a `.sql` file by `SQLParser`.
+      #
+      # Quacks like `Sequel::SimpleMigration`: Sequel's migrator only calls
+      # `#apply(db, direction)` and `#use_transactions` on the loaded object
+      # (transaction wrapping happens outside `#apply`, in the migrator's
+      # `checked_transaction`). Unlike `SimpleMigration`, statements are held
+      # as plain arrays and executed directly via `db.run` — no `instance_exec`
+      # indirection — which gives us a seam to rewrite the backtrace of a
+      # failing statement so it points back into the `.sql` file.
+      #
+      # @api private
+      class SQLMigration < Dry::Struct
+        Filename   = Types::Coercible::String
+        Settings   = Types::Strict::Hash.default { {} }
+        Direction  = Types::Strict::Symbol.enum(:up, :down)
+        Statements = Types::Array.of(Types.Instance(Statement))
+
+        attribute :filename, Filename
+        attribute :settings, Settings
+
+        attribute :up, Statements
+        attribute? :down, Statements
+
+        # Return a copy with additional settings merged in.
+        #
+        # @api private
+        def with(**settings)
+          new(settings: self.settings.merge(settings))
+        end
+
+        # Whether to run inside a transaction.
+        #
+        # @return [Boolean, nil] nil leaves the choice to the database default
+        #
+        # @api private
+        def use_transactions
+          settings[:transaction]
+        end
+
+        # Execute the statements for the given direction against the database.
+        #
+        # @param db [Sequel::Database]
+        # @param direction [Symbol] :up or :down
+        #
+        # @api private
+        def apply(db, direction)
+          unless Direction.valid?(direction)
+            raise ArgumentError, "Invalid migration direction specified (#{direction.inspect})"
+          end
+
+          statements = public_send(direction)
+          return unless statements
+
+          statements.each do |statement|
+            db.run(statement.sql)
+          rescue Sequel::DatabaseError => e
+            raise annotate(e, statement, direction)
+          end
+        end
+
+        private
+
+        # Prepend a synthetic frame pointing at the failing statement's source
+        # location, so the migration file appears at the top of the backtrace.
+        #
+        # @api private
+        def annotate(error, statement, direction)
+          frame = "#{filename}:#{statement.line}:in '#{direction}'"
+          error.set_backtrace([frame, *(error.backtrace || [])])
+          error
+        end
+      end
+    end
+  end
+end