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,8 @@ module SQL
     MissingPrimaryKeyError    = Class.new(StandardError)
     MigrationError            = Class.new(StandardError)
     UnsupportedConversion     = Class.new(MigrationError)
+    SQLParseError             = Class.new(MigrationError)
+    SQLEnvError               = 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,110 @@
+# 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`.
+      #
+      # @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))
+
+        # Matches `${NAME}` substitution references in statement bodies when the
+        # `env=true` pragma is set. Only the braced form is recognized, leaving
+        # `$$`-quoted bodies and `$1` positional params untouched.
+        SUBSTITUTION = /\$\{(?<name>[A-Za-z_]\w*)\}/
+
+        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 [true, false, 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 [:up, :down]
+        #
+        # @api private
+        def apply(db, direction)
+          unless Direction.valid?(direction)
+            raise ArgumentError, "Invalid migration direction specified (#{direction.inspect})"
+          end
+
+          statements = public_send(direction) or return
+
+          # Resolve every statement before running any, so a missing environment
+          # variable aborts before producing side effects.
+          finalized = statements.map { |statement| sub(statement) }
+
+          finalized.each do |statement|
+            db.run(statement.sql)
+          rescue Sequel::DatabaseError => e
+            raise annotate(e, statement, direction)
+          end
+        end
+
+        private
+
+        # Return the statement with `${NAME}` environment-variable substitution
+        # applied to its SQL when the `env` pragma is set. Raises `SQLEnvError`
+        # for a referenced variable that is not present in `ENV`.
+        #
+        # @api private
+        def sub(statement)
+          return statement unless settings[:env]
+
+          sql = statement.sql.gsub(SUBSTITUTION) do
+            name = Regexp.last_match[:name]
+            ENV.fetch(name) do
+              raise SQLEnvError,
+                    "Undefined environment variable ${#{name}} in #{filename}:#{statement.line}"
+            end
+          end
+
+          statement.with(sql:)
+        end
+
+        # 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