pgdd 0.1.0

data/lib/pgdd/database_inspector.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Pgdd
+  # Reads everything it can about one database through an ActiveRecord connection
+  class DatabaseInspector
+    INTERNAL_TABLES = %w[schema_migrations ar_internal_metadata].freeze
+
+    def initialize(connection, name:, root: Dir.pwd, count_rows: false, include_internal: false)
+      @connection       = connection
+      @name             = name
+      @root             = root
+      @count_rows       = count_rows
+      @include_internal = include_internal
+    end
+
+    def call
+      Database.new(
+        name:               @name,
+        adapter:            @connection.adapter_name,
+        location:           location,
+        server_version:     server_version,
+        schema_version:     schema_version,
+        pending_migrations: pending_migrations,
+        migrations:         migrations,
+        extensions:         extensions,
+        enums:              enums,
+        tables:             data_sources.map { |name, kind| table(name, kind) }
+      )
+    end
+
+    def postgres? = @connection.adapter_name.match?(/postg/i)
+    def sqlite?   = @connection.adapter_name.match?(/sqlite/i)
+
+    # [[name, kind], ...] for every table and view
+    def data_sources
+      sources = @connection.tables.map { |name| [name, 'table'] } +
+                @connection.views.map { |name| [name, materialized_views.include?(name) ? 'materialized view' : 'view'] }
+      sources.reject! { |name, _| INTERNAL_TABLES.include?(name) } unless @include_internal
+      sources.sort
+    end
+
+    def table(name, kind)
+      Table.new(
+        name:              name,
+        kind:              kind,
+        comment:           table_comment(name),
+        primary_key:       @connection.primary_key(name),
+        columns:           columns(name),
+        indexes:           indexes(name),
+        foreign_keys:      foreign_keys(name),
+        check_constraints: check_constraints(name),
+        triggers:          triggers.fetch(name) { [] },
+        **row_stats(name, kind)
+      )
+    end
+
+    def columns(table_name)
+      @connection.columns(table_name).map do |c|
+        sql_type = c.sql_type.to_s
+        sql_type += '[]' if c.respond_to?(:array?) && c.array?
+        Column.new(
+          name:     c.name,
+          sql_type: sql_type,
+          null:     c.null,
+          default:  c.default_function || c.default,
+          comment:  c.respond_to?(:comment) ? c.comment : nil
+        )
+      end
+    end
+
+    def indexes(table_name)
+      @connection.indexes(table_name).map do |i|
+        Index.new(name: i.name, columns: Array(i.columns), unique: i.unique, where: i.where, using: i.using)
+      end
+    end
+
+    def foreign_keys(table_name)
+      return [] unless @connection.supports_foreign_keys?
+
+      @connection.foreign_keys(table_name).map do |fk|
+        ForeignKey.new(name: fk.name, column: fk.column, to_table: fk.to_table,
+                       primary_key: fk.primary_key, on_delete: fk.on_delete, on_update: fk.on_update)
+      end
+    end
+
+    def check_constraints(table_name)
+      return [] unless @connection.respond_to?(:supports_check_constraints?) && @connection.supports_check_constraints?
+
+      @connection.check_constraints(table_name).map { |c| Constraint.new(name: c.name, expression: c.expression) }
+    end
+
+    def table_comment(table_name)
+      @connection.table_comment(table_name) if @connection.supports_comments?
+    end
+
+    def row_stats(table_name, kind)
+      stats = relation_stats.fetch(table_name) { {} }
+      rows  = stats[:rows]
+
+      if @count_rows && kind != 'view'
+        rows = @connection.select_value("SELECT COUNT(*) FROM #{@connection.quote_table_name(table_name)}").to_i
+        return { rows: rows, rows_estimated: false, bytes: stats[:bytes] }
+      end
+
+      { rows: rows, rows_estimated: !rows.nil?, bytes: stats[:bytes] }
+    end
+
+    # { table_name => { rows:, bytes: } }; rows are planner estimates
+    def relation_stats
+      @relation_stats ||=
+        if postgres? then postgres_relation_stats
+        elsif sqlite? then sqlite_relation_stats
+        else {}
+        end
+    end
+
+    def postgres_relation_stats
+      sql = <<~SQL
+        SELECT c.relname AS name, c.reltuples::bigint AS rows, pg_total_relation_size(c.oid) AS bytes
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+         WHERE c.relkind IN ('r', 'p', 'm') AND n.nspname = ANY (current_schemas(false))
+      SQL
+      @connection.select_all(sql).to_h do |row|
+        rows = row['rows'].to_i
+        [row['name'], { rows: rows.negative? ? nil : rows, bytes: row['bytes'].to_i }]
+      end
+    end
+
+    # Needs SQLite compiled with the dbstat virtual table; sizes include indexes
+    def sqlite_relation_stats
+      sql = <<~SQL
+        SELECT m.tbl_name AS name, SUM(d.pgsize) AS bytes
+          FROM dbstat d JOIN sqlite_master m ON m.name = d.name
+         GROUP BY m.tbl_name
+      SQL
+      @connection.select_all(sql).to_h { |row| [row['name'], { bytes: row['bytes'].to_i }] }
+    rescue ActiveRecord::StatementInvalid
+      {}
+    end
+
+    # { table_name => [Trigger, ...] }
+    def triggers
+      @triggers ||=
+        if postgres? then postgres_triggers
+        elsif sqlite? then sqlite_triggers
+        else {}
+        end
+    end
+
+    def postgres_triggers
+      sql = <<~SQL
+        SELECT event_object_table AS table_name, trigger_name, action_timing,
+               string_agg(event_manipulation, ' OR ' ORDER BY event_manipulation) AS events,
+               action_statement
+          FROM information_schema.triggers
+         WHERE trigger_schema = ANY (current_schemas(false))
+         GROUP BY event_object_table, trigger_name, action_timing, action_statement
+         ORDER BY 1, 2
+      SQL
+      @connection.select_all(sql).group_by { |r| r['table_name'] }.transform_values do |rows|
+        rows.map { |r| Trigger.new(name: r['trigger_name'], timing: r['action_timing'], events: r['events'], action: r['action_statement']) }
+      end
+    end
+
+    def sqlite_triggers
+      sql = "SELECT tbl_name, name, sql FROM sqlite_master WHERE type = 'trigger' ORDER BY tbl_name, name"
+      @connection.select_all(sql).group_by { |r| r['tbl_name'] }.transform_values do |rows|
+        rows.map { |r| Trigger.new(name: r['name'], timing: nil, events: nil, action: r['sql']) }
+      end
+    end
+
+    def materialized_views
+      @materialized_views ||=
+        postgres? ? @connection.select_values('SELECT matviewname FROM pg_matviews WHERE schemaname = ANY (current_schemas(false))') : []
+    end
+
+    # { enum_type_name => [values] } for PostgreSQL enum types
+    def enums
+      return {} unless postgres?
+
+      sql = <<~SQL
+        SELECT t.typname AS name, string_agg(e.enumlabel, ',' ORDER BY e.enumsortorder) AS labels
+          FROM pg_type t
+          JOIN pg_enum e ON e.enumtypid = t.oid
+          JOIN pg_namespace n ON n.oid = t.typnamespace
+         WHERE n.nspname = ANY (current_schemas(false))
+         GROUP BY t.typname ORDER BY 1
+      SQL
+      @connection.select_all(sql).to_h { |r| [r['name'], r['labels'].split(',')] }
+    end
+
+    def extensions
+      @connection.respond_to?(:extensions) ? @connection.extensions.sort : []
+    end
+
+    def location
+      @connection.pool.db_config.database
+    rescue StandardError
+      nil
+    end
+
+    def server_version
+      sql = if postgres? then 'SHOW server_version'
+            elsif sqlite? then 'SELECT sqlite_version()'
+            else 'SELECT version()'
+            end
+      @connection.select_value(sql)
+    rescue StandardError
+      nil
+    end
+
+    def schema_version
+      migration_context&.current_version
+    rescue StandardError
+      nil
+    end
+
+    def pending_migrations
+      migration_context&.needs_migration?
+    rescue StandardError
+      nil
+    end
+
+    # Every migration file on this database's migrations paths, oldest first
+    def migrations
+      MigrationScanner.new(migrations_paths, root: @root).call
+    end
+
+    def migrations_paths
+      Array(migration_context&.migrations_paths)
+    rescue StandardError
+      []
+    end
+
+    def migration_context
+      pool = @connection.pool
+      return pool.migration_context if pool.respond_to?(:migration_context)
+
+      @connection.migration_context if @connection.respond_to?(:migration_context)
+    end
+  end
+end

data/lib/pgdd/erd_writer.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Pgdd
+  # Builds Graphviz ERDs from a Database: one per table (the table in full,
+  # its parents and children by key columns) plus one for the whole schema.
+  # Dark theme on a transparent background; boxes and edges link to the
+  # table pages when name_for is given.
+  class ErdWriter
+    FORMATS = %w[svg dot png pdf].freeze
+
+    GRAPH_ATTRS = 'rankdir=LR bgcolor="transparent" fontname="Arial" nodesep=0.3 ranksep=1.0'
+    NODE_ATTRS  = 'shape=plaintext fontname="Arial" fontsize=12 fontcolor="#e6e6e6"'
+    EDGE_ATTRS  = 'fontname="Arial" fontsize=9 color="#7aa2f7" fontcolor="#9aa4b2"'
+    BORDER      = '#c8d1dc'
+    TITLE_BG    = '#2b3a55'
+    TYPE_COLOR  = '#9aa4b2'
+
+    class Error < Pgdd::Error; end
+
+    # A link the models declare but the database cannot enforce: from_table.column
+    # points at to_table's id whenever type_column names model. macro is the
+    # inverse side's has_one or has_many; name is the polymorphic association.
+    PolymorphicKey = Data.define(:name, :column, :type_column, :to_table, :primary_key, :model, :macro)
+
+    class << self
+      # For text inside HTML-like labels and their attributes
+      def escape(value)
+        value.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;').gsub('"', '&quot;')
+      end
+
+      # A double-quoted DOT attribute value
+      def quote(value)
+        %("#{value.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"').gsub(/\s*\n\s*/, ' ')}")
+      end
+
+      # HTML-like label with a title row and one row (and port) per column,
+      # or per column named in only. A url makes the whole box a link; comments
+      # become hover tooltips, which Graphviz only emits for cells that carry a
+      # link of their own.
+      def node(table, url: nil, only: nil)
+        cell_link = url ? %( href="#{escape(url)}") : ''
+        columns   = only ? table.columns.select { |c| only.include?(c.name) } : table.columns
+        rows      = [title_row(table, cell_link)] + columns.map { |c| column_row(c, cell_link) }
+        label     = %(<<table border="0" cellborder="1" cellspacing="0" cellpadding="6" color="#{BORDER}">#{rows.join}</table>>)
+
+        attrs = ["label=#{label}"]
+        attrs << "URL=#{quote(url)}" if url
+        attrs << "tooltip=#{quote(table.comment)}" if table.comment
+        %("#{table.name}" [#{attrs.join(' ')}];)
+      end
+
+      def title_row(table, cell_link)
+        %(<tr><td bgcolor="#{TITLE_BG}"#{cell_link}><font point-size="16" color="#ffffff"><b>#{escape(table.name)}</b></font></td></tr>)
+      end
+
+      # One row per column, with a port for edges and the comment as a tooltip
+      def column_row(column, cell_link)
+        tooltip = column.comment ? %( title="#{escape(column.comment)}") : ''
+        %(<tr><td port="#{escape(column.name)}" align="left"#{cell_link}#{tooltip}>#{escape(column.name)} ) +
+          %(<font color="#{TYPE_COLOR}">[#{escape(column.sql_type)}]</font></td></tr>)
+      end
+
+      # Crow's foot on the child column, bar and ring on the parent key; a
+      # PolymorphicKey is dashed, with a single tee when its inverse is has_one
+      def edge(from_table, fk, url: nil)
+        column = Array(fk.column).first
+        key    = Array(fk.primary_key).first || 'id'
+        attrs  = ['arrowhead=teeodot', 'dir=both', "label=#{quote(column)}"]
+        attrs.concat(edge_attrs(fk, "#{from_table}.#{column} references #{fk.to_table}.#{key}"))
+        attrs << "URL=#{quote(url)}" if url
+        %("#{from_table}":"#{column}":e -> "#{fk.to_table}":"#{key}":w [#{attrs.join(' ')}];)
+      end
+
+      # Tail, style and tooltip: a solid crow's foot for a foreign key; dashed,
+      # with a single tee when the inverse is has_one, for a polymorphic key
+      def edge_attrs(fk, reference)
+        return ['arrowtail=crow', "tooltip=#{quote(reference)}"] unless fk.is_a?(PolymorphicKey)
+
+        [fk.macro == :has_one ? 'arrowtail=tee' : 'arrowtail=crow', 'style=dashed',
+         "tooltip=#{quote("#{reference} when #{fk.type_column} is #{fk.model} (polymorphic #{fk.name})")}"]
+      end
+
+      # nodes and edges are DOT statements from .node and .edge
+      def graph(name, nodes, edges)
+        lines = ["digraph \"#{name}\" {",
+                 "  graph [#{GRAPH_ATTRS}];",
+                 "  node  [#{NODE_ATTRS}];",
+                 "  edge  [#{EDGE_ATTRS}];"]
+        lines.concat(nodes.map { |n| "  #{n}" })
+        lines.concat(edges.map { |e| "  #{e}" })
+        (lines << '}').join("\n") + "\n"
+      end
+
+      # Renders DOT source to path with Graphviz
+      def render(source, path, format)
+        IO.popen(['dot', "-T#{format}", '-o', path], 'w') { |dot| dot.write(source) }
+        raise Error, "dot exited with #{Process.last_status.exitstatus} rendering #{path}" unless Process.last_status.success?
+      end
+    end
+
+    # models are the Models backed by this database; their has_one/has_many
+    # ... as: declarations become dashed PolymorphicKey edges. name_for maps a
+    # table name to the file stem its page and diagram share; when given, boxes
+    # and edges link to "<stem>.md"
+    def initialize(db, models: [], name_for: nil)
+      @db          = db
+      @tables      = db.tables.to_h { |t| [t.name, t] }
+      @name_for    = name_for
+      @polymorphic = polymorphic_keys(models)
+    end
+
+    # [[from_table, PolymorphicKey], ...] for every `has_one/has_many ..., as:`
+    # whose owner and target tables are both in this database. The association's
+    # class_name is the model holding the foreign key; the declaring model is
+    # the target the type column names.
+    def polymorphic_keys(models)
+      by_name = models.to_h { |m| [m.name, m] }
+      keys = models.flat_map do |target|
+        target.associations.filter_map { |a| polymorphic_key(target, a, by_name[a.class_name]) }
+      end
+      keys.uniq { |from, pk| [from, pk.column, pk.to_table] }
+    end
+
+    # [owner_table, PolymorphicKey] for one `has_one/has_many ..., as:` that
+    # target declares and owner holds the foreign key for; nil otherwise
+    def polymorphic_key(target, association, owner)
+      as = association.options[:as]
+      return nil unless as && association.foreign_key && %i[has_one has_many].include?(association.macro)
+      return nil unless owner && @tables[owner.table_name.to_s] && @tables[target.table_name.to_s]
+
+      [owner.table_name.to_s,
+       PolymorphicKey.new(name: as.to_s, column: association.foreign_key.to_s, type_column: "#{as}_type",
+                          to_table: target.table_name.to_s, primary_key: 'id',
+                          model: target.name, macro: association.macro)]
+    end
+
+    def stem(name)
+      @name_for ? @name_for.call(name) : name
+    end
+
+    def page_url(table_name)
+      "#{@name_for.call(table_name)}.md" if @name_for
+    end
+
+    def node(table, only: nil) = self.class.node(table, url: page_url(table.name), only: only)
+    def edge(from_table, fk) = self.class.edge(from_table, fk, url: page_url(from_table))
+
+    # The primary key plus every column that the given [[table_name, ForeignKey], ...]
+    # relations use on this table: enough to draw its edges without the full box
+    def key_columns(table, relations)
+      keys = Array(table.primary_key).map(&:to_s)
+      keys = ['id'] if keys.empty?
+      relations.each do |from, fk|
+        if from == table.name
+          keys.concat(Array(fk.column).map(&:to_s))
+          keys << fk.type_column if fk.is_a?(PolymorphicKey)
+        end
+        keys.concat(Array(fk.primary_key).map(&:to_s)) if fk.to_table == table.name
+      end
+      keys.uniq
+    end
+
+    # [[table_name, ForeignKey or PolymorphicKey], ...] for keys from and to this table
+    def relations(table)
+      parents  = table.foreign_keys.map { |fk| [table.name, fk] }
+      children = @db.tables.flat_map do |other|
+        other.foreign_keys.select { |fk| fk.to_table == table.name }.map { |fk| [other.name, fk] }
+      end
+      poly = @polymorphic.select { |from, pk| from == table.name || pk.to_table == table.name }
+      (parents + children + poly).uniq
+    end
+
+    # The table in full; its parents and children collapsed to their key columns
+    def table_dot(table)
+      edges = relations(table)
+      names = ([table.name] + edges.flat_map { |from, fk| [from, fk.to_table] }).uniq
+      nodes = names.filter_map { |n| @tables[n] }.map do |t|
+        t == table ? node(t) : node(t, only: key_columns(t, edges))
+      end
+      self.class.graph(table.name, nodes, edges.map { |from, fk| edge(from, fk) })
+    end
+
+    # Every table collapsed to its key columns
+    def schema_dot
+      edges = @db.tables.flat_map { |t| t.foreign_keys.map { |fk| [t.name, fk] } } + @polymorphic
+      nodes = @db.tables.map { |t| node(t, only: key_columns(t, edges)) }
+      self.class.graph('schema', nodes, edges.map { |from, fk| edge(from, fk) })
+    end
+
+    # { file stem => dot source } for every diagram
+    def diagrams
+      @db.tables.to_h { |t| [stem(t.name), table_dot(t)] }.merge(stem('schema') => schema_dot)
+    end
+
+    # Writes STEM.FORMAT for each diagram, through Graphviz unless FORMAT is dot
+    def write(dir, format: 'svg')
+      FileUtils.mkdir_p(dir)
+      diagrams.map do |name, source|
+        path = File.join(dir, "#{name}.#{format}")
+        format == 'dot' ? File.write(path, source) : self.class.render(source, path, format)
+        path
+      end
+    end
+  end
+end

data/lib/pgdd/migration_scanner.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Pgdd
+  # Reads migration files and works out which tables each one changes, from
+  # the schema DSL calls and from the SQL in execute strings and heredocs.
+  # Only the forward direction counts: `def down` and `dir.down` are skipped.
+  class MigrationScanner
+    TABLE_OPS = %w[create_table drop_table change_table add_column remove_column change_column
+                   change_column_null change_column_default change_column_comment rename_column
+                   add_index remove_index add_reference remove_reference add_belongs_to
+                   remove_belongs_to add_check_constraint remove_check_constraint
+                   add_unique_constraint remove_unique_constraint add_exclusion_constraint
+                   remove_exclusion_constraint add_timestamps remove_timestamps
+                   change_table_comment validate_foreign_key validate_check_constraint
+                   validate_constraint].freeze
+
+    # op :table[, :column | %i[a b] | [:a, :b] | "string"]
+    ARGUMENT    = /(?:\s*,\s*(?::(\w+)|%i\[([^\]]*)\]|\[([^\]]*)\]|"([^"]*)"|'([^']*)'))?/
+    # longest names first so change_column_null is not read as change_column
+    OPS         = TABLE_OPS.sort_by { |op| -op.size }.join('|')
+    DSL_CALL    = /\b(#{OPS})\b\s*\(?\s*:(\w+)#{ARGUMENT}/
+    # The same call with a variable for the table, as in `TABLES.each { |t| add_column t, ... }`;
+    # the change is attributed to every word in the file's %i[...] and %w[...] literals
+    DSL_VAR     = /\b(#{OPS})\b\s*\(?\s*([a-z_]\w*)#{ARGUMENT}/
+    WORD_LISTS  = /%[iw]\[([^\]]*)\]/m
+    RENAME      = /\brename_table\s*\(?\s*:(\w+)\s*,\s*:(\w+)/
+    JOIN_TABLE  = /\bcreate_join_table\s*\(?\s*:(\w+)\s*,\s*:(\w+)/
+    FOREIGN_KEY = /\b(add|remove)_foreign_key\s*\(?\s*:(\w+)\s*,\s*:(\w+)/
+    MODEL_TABLE = /self\.table_name\s*=\s*['"](\w+)['"]/
+    SQL         = /\b(?<verb>ALTER\s+TABLE|CREATE\s+TABLE|DROP\s+TABLE|TRUNCATE\s+TABLE|CREATE\s+(?:UNIQUE\s+)?INDEX\s+\S+\s+ON|UPDATE|INSERT\s+INTO|DELETE\s+FROM)\s+(?:IF\s+(?:NOT\s+)?EXISTS\s+)?(?:ONLY\s+)?"?(?<table>\w+)"?/i
+    HEREDOC     = /<<[~-]?(['"]?)([A-Z_]+)\1[^\n]*\n(.*?)^\s*\2\s*$/m
+    EXEC_STRING = /\bexecute\s*\(?\s*(['"])(.*?)\1/m
+    FILENAME    = /\A(\d+)_(.+)\.rb\z/
+
+    class << self
+      # The source with comment lines, `def down ... end`, `dir.down do ... end`
+      # and one-line `dir.down { ... }` removed. A block ends at the first line
+      # whose indentation matches the line that opened it.
+      def forward_source(source)
+        skip = nil
+        source.lines.filter_map do |line|
+          if skip
+            skip = nil if line.match?(/\A#{skip}end\b/)
+            next
+          end
+          next if line.match?(/\A\s*#/) || line.match?(/\bdir\.down\s*\{/)
+
+          if (m = line.match(/\A(\s*)(?:def down\b|dir\.down\s+do\b)/))
+            skip = m[1]
+            next
+          end
+          line
+        end.join
+      end
+
+      # SQL fragments in execute strings and heredocs
+      def sql_blocks(source)
+        source.scan(HEREDOC).map(&:last) + source.scan(EXEC_STRING).map(&:last)
+      end
+
+      # The ARGUMENT captures rendered as "col" or "[a, b]": one of a :symbol,
+      # a %i[...] list, a [...] list, a "string" or a 'string'
+      def argument(symbol, words, list, double_quoted, single_quoted)
+        return symbol if symbol
+        return "[#{words.split.join(', ')}]" if words
+        return "[#{list.delete(':').split(/\s*,\s*/).join(', ')}]" if list
+
+        double_quoted || single_quoted
+      end
+
+      def change(op, *argument_captures)
+        [op, argument(*argument_captures)].compact.join(' ')
+      end
+
+      # { table => [change, ...] } in file order, from the forward source
+      def tables(source)
+        src    = forward_source(source)
+        tables = Hash.new { |h, k| h[k] = [] }
+        dsl_changes(src, tables)
+        looped_changes(src, tables)
+        structural_changes(src, tables)
+        sql_changes(src, tables)
+        tables.transform_values(&:uniq)
+      end
+
+      # `op :table, ...` calls
+      def dsl_changes(src, tables)
+        src.scan(DSL_CALL) { |op, table, *args| tables[table] << change(op, *args) }
+      end
+
+      # `op variable, ...` calls, attributed to every word list in the file
+      def looped_changes(src, tables)
+        looped = src.scan(WORD_LISTS).flatten.flat_map(&:split).uniq
+        src.scan(DSL_VAR) do |op, _variable, *args|
+          described = change(op, *args)
+          looped.each { |table| tables[table] << described }
+        end
+      end
+
+      # Renames, join tables, foreign keys and data changes through a model
+      def structural_changes(src, tables)
+        src.scan(RENAME) do |old_name, new_name|
+          tables[old_name] << "rename_table to #{new_name}"
+          tables[new_name] << "rename_table from #{old_name}"
+        end
+        src.scan(JOIN_TABLE) { |left, right| tables[[left, right].sort.join('_')] << 'create_join_table' }
+        src.scan(FOREIGN_KEY) do |verb, from, to|
+          tables[from] << "#{verb}_foreign_key to #{to}"
+          tables[to] << "#{verb}_foreign_key from #{from}"
+        end
+        src.scan(MODEL_TABLE) { |(table)| tables[table] << 'data change through a model' }
+      end
+
+      # Statements inside execute strings and heredocs
+      def sql_changes(src, tables)
+        sql_blocks(src).each do |sql|
+          sql.scan(SQL) { |verb, table| tables[table] << "#{sql_verb(verb)} (SQL)" }
+        end
+      end
+
+      def sql_verb(verb)
+        verb.upcase.gsub(/\s+/, ' ').sub(/ (UNIQUE )?INDEX .*/, ' INDEX')
+      end
+
+      def renames(source)
+        forward_source(source).scan(RENAME)
+      end
+
+      def migration(path)
+        version, name = File.basename(path).match(FILENAME)&.captures
+        source = File.read(path)
+        Migration.new(version: version || '0', name: name || File.basename(path, '.rb'), path: path,
+                      tables: tables(source), renames: renames(source))
+      end
+    end
+
+    # paths are migration directories, absolute or relative to root
+    def initialize(paths, root: Dir.pwd)
+      @dirs = Array(paths).map { |path| File.expand_path(path.to_s, root) }
+    end
+
+    # [Migration, ...] oldest first; missing directories are skipped
+    def call
+      @dirs.flat_map { |dir| Dir[File.join(dir, '*.rb')] }.sort.map { |path| self.class.migration(path) }
+    end
+  end
+end