trellis-pg 0.1.0-aarch64-linux

data/lib/trellis/metrics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Trellis
+  # The engine's metrics, in Prometheus text exposition format: the Rust
+  # crate's trellis::Metrics#render_prometheus
+  # (docs/decisions/0009-observability-decisions.md).
+  #
+  # The registry is process-wide: one body holds the series of every Trellis
+  # handle in this process, so it needs no handle and works before
+  # Trellis.connect and after Trellis.shutdown. Every series carries a
+  # trellis_instance="<database>/<catalog schema>" label, so instances in one
+  # process stay apart. trellis_instance_up is 1 while an instance has a
+  # running handle and 0 after its last one shuts down; the other gauges of a
+  # stopped instance disappear after 60 seconds. See docs/observability.md.
+  #
+  # The binding opens no port. Serve the text from a route the app already
+  # has, for example in Rails:
+  #
+  #   # config/routes.rb
+  #   get "/metrics", to: proc {
+  #     [200, { "content-type" => "text/plain; version=0.0.4" }, [Trellis::Metrics.render_prometheus]]
+  #   }
+  #
+  # In a forking server each worker process has its own registry, holding
+  # only its own handles' series, so scrape every worker (or run the worker
+  # handle, staging: true, in a process of its own and scrape that).
+  #
+  # A process forked while its parent had an engine running may have
+  # inherited the registry's lock held, so rendering there raises
+  # Trellis::ForkedHandleError, as Trellis.connect does.
+  module Metrics
+    # Renders the registry's current contents: # HELP and # TYPE lines, then
+    # each series' samples.
+    def self.render_prometheus
+      Native.render_prometheus
+    end
+  end
+end

data/lib/trellis/migration.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "trellis/pg"
+
+module Trellis
+  # Trellis statements in an ActiveRecord migration, so a transform is
+  # defined, and dropped, the way the tables it reads are created.
+  #
+  #   class DefineWidgetPrices < ActiveRecord::Migration[8.1]
+  #     include Trellis::Migration
+  #
+  #     # Required: see "Transactions" below.
+  #     disable_ddl_transaction!
+  #
+  #     def up
+  #       create_table :widgets do |t|
+  #         t.integer :price
+  #       end
+  #
+  #       define "TRANSFORM widget_prices FROM widgets SELECT price AS price"
+  #     end
+  #
+  #     def down
+  #       apply "PAUSE TRANSFORM widget_prices"
+  #       apply "DROP TRANSFORM widget_prices"
+  #       drop_table :widgets
+  #     end
+  #   end
+  #
+  # Three helpers, each a thin call through to the Trellis method of the
+  # same name:
+  #
+  # - define: a `TRANSFORM` statement, and nothing else (Trellis.define).
+  # - apply: any statement of the grammar (Trellis.apply), such as the
+  #   `PAUSE TRANSFORM` and `DROP TRANSFORM` a `down` undoes a define with.
+  #   (`DROP` refuses a transform that isn't paused, and drops its target
+  #   table.)
+  # - status: the Status of the transform writing a target, or nil
+  #   (Trellis.status).
+  #
+  # Each runs as it's called, in order with the migration's own statements,
+  # so a transform can read a table created earlier in the same migration.
+  # Each raises the Trellis::Error if its call fails, which fails the
+  # migration. (ActiveRecord's migrator re-raises it as a StandardError
+  # naming the migration, with the Trellis::Error as its cause.)
+  #
+  # == Transactions
+  #
+  # Trellis doesn't join the migration's transaction. It runs every call on
+  # connections of its own, and each call commits before it returns. If the
+  # migration's transaction rolled back after a define, the host's changes
+  # would be undone and the definition and its target table would not.
+  #
+  # So a migration that includes this module has to turn its transaction off
+  # with `disable_ddl_transaction!`. define and apply check, as they run,
+  # that the migration's connection has no transaction open (a `transaction
+  # do` block inside the migration opens one too), and raise
+  # ActiveRecord::MigrationError before applying anything if it does. In a
+  # migration that forgot `disable_ddl_transaction!`, the migration's
+  # transaction then rolls back with nothing applied on either side.
+  #
+  # Without the transaction, a migration that fails partway leaves whatever
+  # ran before the failure in place, on both sides. Give a migration that
+  # defines transforms little else to do.
+  #
+  # == up and down, not change
+  #
+  # ActiveRecord can reverse `create_table` on its own, but not a Trellis
+  # statement: the reverse of a define is a pause and a drop of a target
+  # that only the statement names. So a migration that includes this module
+  # must define `up` and `down`. One that defines a public `change` raises
+  # ActiveRecord::MigrationError before running anything, in either
+  # direction, rather than roll back partway. define and apply inside a
+  # `revert` block raise ActiveRecord::IrreversibleMigration.
+  #
+  # == Which Trellis
+  #
+  # If this process's handle is connected, the helpers use it. Otherwise
+  # (the usual case: `rails db:migrate` gets no boot handle, see
+  # Trellis::Railtie) each call connects a handle of its own from
+  # config.trellis.connect, runs Trellis.migrate on it (creating Trellis's
+  # own tables the first time), makes its one call, and shuts the handle
+  # down. A migration's own handle never runs background work: staging and
+  # drain_threads are always the defaults, whatever the configuration says.
+  #
+  # The helpers run on the default instance. A migration for an instance
+  # named in config.trellis.instances runs its statements on that instance
+  # itself, in the same transaction-free way:
+  #
+  #   Trellis::Railtie.with_handle(:reports) do |reports|
+  #     reports.define "TRANSFORM monthly_totals FROM orders SELECT total AS total"
+  #   end
+  #
+  # == Running a migration once
+  #
+  # A define isn't idempotent: a second define of a target that exists
+  # raises ConflictError. ActiveRecord's schema_migrations already records
+  # which migrations have run, so a migration's define runs once per
+  # database, and these helpers add no guard of their own. A migration that
+  # has to tolerate a transform defined some other way (by hand, or by a
+  # deploy step) can guard the define itself:
+  #
+  #   def up
+  #     define "TRANSFORM widget_prices FROM widgets SELECT price AS price" if status("widget_prices").nil?
+  #   end
+  #
+  # The guard checks the target's name, not its definition: a changed
+  # statement for a target that exists is an `ALTER TRANSFORM`.
+  module Migration
+    # The helpers' Trellis::Railtie.with_handle: runs the block with this
+    # process's handle, or one connected from config.trellis.connect for the
+    # length of the block, running Trellis.migrate first either way, and
+    # returns the block's value. Without Rails, it uses this process's
+    # handle. Raises ActiveRecord::MigrationError if there's neither.
+    def self.with_handle(&)
+      if Trellis.connected?
+        Trellis.migrate
+        return yield
+      end
+
+      unless defined?(Trellis::Railtie) && Trellis::Railtie.connect_options
+        raise ActiveRecord::MigrationError,
+              "there's no Trellis to run this against: set config.trellis.connect to " \
+              "Trellis.connect's options (config.trellis.connect = { url: ENV.fetch(\"DATABASE_URL\") }), " \
+              "or call Trellis.connect before migrating"
+      end
+
+      Trellis::Railtie.with_handle(&)
+    end
+
+    # Registers a transform from a `TRANSFORM` statement and returns its
+    # target table: Trellis.define, run as the migration reaches it.
+    def define(statement)
+      trellis_statement("define", statement) { Trellis.define(statement) }
+    end
+
+    # Runs any statement of Trellis's grammar and returns its Applied:
+    # Trellis.apply, run as the migration reaches it.
+    def apply(statement)
+      trellis_statement("apply", statement) { Trellis.apply(statement) }
+    end
+
+    # The Status of the transform writing target_table, or nil when none
+    # does: Trellis.status. A read, so it runs whether or not a transaction
+    # is open.
+    def status(target_table)
+      Migration.with_handle { Trellis.status(target_table) }
+    end
+
+    # ActiveRecord's entry point for running this migration in a direction:
+    # refuses a change method before anything runs.
+    def exec_migration(conn, direction)
+      if respond_to?(:change)
+        raise ActiveRecord::MigrationError,
+              "#{self.class.name} includes Trellis::Migration, so it must define up and down " \
+              "rather than change: ActiveRecord can't reverse a Trellis statement. Undo a " \
+              "define in down with apply \"PAUSE TRANSFORM <target>\" and " \
+              "apply \"DROP TRANSFORM <target>\"."
+      end
+      super
+    end
+
+    private
+
+    def trellis_statement(helper, statement)
+      if reverting?
+        raise ActiveRecord::IrreversibleMigration,
+              "cannot reverse a Trellis statement: #{statement}. Undo a define in down with " \
+              "PAUSE TRANSFORM and DROP TRANSFORM statements."
+      end
+      refuse_open_transaction!("this statement wasn't applied: #{statement}")
+
+      say_with_time("#{helper}(#{statement.inspect})") { Migration.with_handle { yield } }
+    end
+
+    def refuse_open_transaction!(what)
+      return unless connection.transaction_open?
+
+      raise ActiveRecord::MigrationError,
+            "Trellis doesn't join the migration's transaction, so #{what}: if the " \
+            "transaction rolled back, a definition would stay. Add `disable_ddl_transaction!` " \
+            "to the migration, and keep Trellis statements out of `transaction` blocks."
+    end
+  end
+end

data/lib/trellis/pg.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "values"
+require_relative "version"
+require "rbconfig"
+
+# The native extension (ext/trellis_ruby). Installing the source gem, or
+# `rake compile`, builds the one this Ruby needs into lib/trellis/. A platform
+# gem instead carries one build per Ruby minor version, each in
+# lib/trellis/<major.minor>/, and none in lib/trellis/ itself.
+#
+# A lib/trellis/ build wins when both are there: in a checkout, a
+# per-version directory is only ever left over from building a platform gem
+# (it's ignored by git, so nothing shows it), and `rake test` must load the
+# extension it just compiled, not that one.
+dlext = RbConfig::CONFIG.fetch("DLEXT")
+per_version = "#{RUBY_VERSION[/\A\d+\.\d+/]}/trellis_ruby"
+if !File.exist?(File.join(__dir__, "trellis_ruby.#{dlext}")) &&
+   File.exist?(File.join(__dir__, "#{per_version}.#{dlext}"))
+  require_relative per_version
+else
+  require_relative "trellis_ruby"
+end
+
+require_relative "instance"
+require_relative "metrics"
+
+# Embedded Trellis for Ruby apps: a native extension over the `trellis`
+# crate's BlockingTrellis, so a Rails app can define and run streaming
+# transforms without deploying a separate service
+# (docs/decisions/0010-embeddable-clients.md).
+#
+# A Trellis::Instance is one catalog schema's handle, and a process holds as
+# many as it has schemas (Trellis::Instance.connect). This module is the
+# common case's shortcut: Trellis.connect opens the process's default
+# instance, every other method here is that instance's, and Trellis.shutdown
+# closes it. An at_exit hook shuts down every instance the process still
+# holds, the default included.
+#
+# The surface mirrors the Rust crate's BlockingTrellis, and is documented on
+# Trellis::Instance:
+#
+# - Lifecycle: connect, connected?, migrate, config, shutdown.
+# - Every statement form: apply, and define for a TRANSFORM statement alone.
+# - Reads: status, definitions, dump_definitions_sql.
+# - Quarantine: quarantined, quarantine_status, sample_quarantined,
+#   poisoned_since, release_key.
+# - Operations: request_backfill, detect_capture_disruptions, has_live_drain_workers?,
+#   has_live_staging_worker?, watermark_token, await_converged, self_check,
+#   self_check_job.
+# - Metrics: Trellis::Metrics.render_prometheus, which needs no handle.
+#
+#   # A deploy's migration step: the defaults run nothing in the background.
+#   Trellis.connect(url: "host=localhost dbname=app")
+#   Trellis.migrate
+#   Trellis.shutdown
+#
+#   # The app, once migrated.
+#   Trellis.connect(url: "host=localhost dbname=app", staging: true, drain_threads: 2)
+#   Trellis.define("TRANSFORM widget_prices FROM widgets SELECT price AS price")
+#   Trellis.status("widget_prices").status # => :live, once it has backfilled
+#
+#   # A second instance, in a schema of its own.
+#   reports = Trellis::Instance.connect(url: "host=localhost dbname=app", schema: "reports")
+#   reports.status("monthly_totals")
+#   reports.shutdown # the default instance keeps running
+#
+# A handle doesn't survive `fork`. Shut down before forking
+# (Trellis::Instance.shutdown_all; Puma's before_fork) and connect after
+# (Puma's before_worker_boot, Passenger's starting_worker_process); in a
+# Rails app, Trellis::Railtie.connect does the connecting. A forked child's
+# calls on a handle it inherited raise Trellis::ForkedHandleError, except
+# Trellis.shutdown, which leaves the parent's handle alone and does nothing.
+# So does Trellis.connect in a child forked while its parent's handle was
+# running.
+module Trellis
+  @default = nil
+  @lock = Mutex.new
+
+  class << self
+    # Connects this process's default instance, with the options
+    # Trellis::Instance.connect takes. Raises ValidationError if the default
+    # instance is already connected: shut it down first. A second instance
+    # is Trellis::Instance.connect's. Raises ForkedHandleError in a process
+    # forked while its parent had an instance running.
+    def connect(**options)
+      @lock.synchronize do
+        if connected?
+          raise ValidationError,
+                "this process's default instance is already connected: call Trellis.shutdown " \
+                "first (Trellis::Instance.connect opens another instance)"
+        end
+        @default = Instance.connect(**options)
+      end
+      nil
+    end
+
+    # Whether this process's default instance is connected. False before
+    # connect, after shutdown, and in a forked child that hasn't connected
+    # its own.
+    def connected?
+      default = @default
+      !default.nil? && default.connected?
+    end
+
+    # The default instance Trellis.connect opened, for code that takes an
+    # Instance. Raises ValidationError if there is none.
+    def default_instance
+      @default or raise ValidationError, "Trellis is not connected: call Trellis.connect first"
+    end
+
+    # Stops the default instance (see Trellis::Instance#shutdown). Does
+    # nothing if it is not connected, which includes a forked child holding
+    # only the one it inherited.
+    def shutdown
+      @lock.synchronize do
+        return nil unless connected?
+
+        begin
+          @default.shutdown
+        ensure
+          @default = nil
+        end
+      end
+      nil
+    end
+
+    # Trellis::Instance's calls, on the default instance.
+    Instance.public_instance_methods(false).each do |name|
+      next if %i[connected? shutdown inspect to_s].include?(name)
+
+      define_method(name) { |*args, **options, &block| default_instance.public_send(name, *args, **options, &block) }
+    end
+  end
+end
+
+# The Rails integration, only when Rails is loaded first (Bundler.require in
+# config/application.rb). Without Rails, nothing here requires a gem.
+# Trellis::Migration (lib/trellis/migration.rb) needs ActiveRecord: the
+# Railtie loads it with ActiveRecord, and an app without Rails requires it.
+require_relative "railtie" if defined?(::Rails::Railtie)

data/lib/trellis/railtie.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Trellis
+  # Connects this process's handle as a Rails app boots, from the app's
+  # `config.trellis`. `require "trellis/pg"` loads it when Rails is loaded
+  # first, which is what Bundler.require in config/application.rb does.
+  #
+  #   # config/application.rb, or config/environments/*.rb
+  #   config.trellis.connect = {
+  #     url: ENV.fetch("DATABASE_URL"),
+  #     staging: ENV["TRELLIS_WORKER"] == "1",
+  #     drain_threads: ENV["TRELLIS_WORKER"] == "1" ? 2 : 0
+  #   }
+  #
+  # config.trellis.connect takes Trellis.connect's options, and is the one
+  # place the Rails integration reads the default instance's from: the boot
+  # connect, the migration helpers (Trellis::Migration) and `rails
+  # trellis:migrate` all use it. Leave it nil (the default) and the Railtie
+  # does nothing for the default instance.
+  #
+  # An app that runs more instances (a second catalog schema, or another
+  # database) names the extras in config.trellis.instances, each with
+  # Trellis::Instance.connect's options. The Railtie connects them with the
+  # default instance, `rails trellis:migrate` migrates them, and
+  # Trellis::Railtie.named_instance(:reports) returns one:
+  #
+  #   config.trellis.instances = {
+  #     reports: { url: ENV.fetch("REPORTS_DATABASE_URL"), schema: "reports" }
+  #   }
+  #
+  # With `config.active_record.schema_format = :sql`, the same config puts
+  # the definitions in `structure.sql` (Trellis::SchemaDump). The database
+  # they dump into is config.trellis.dump_database, "primary" by default.
+  #
+  # When either is set, the app's handles connect in an after_initialize hook,
+  # except in these two cases:
+  #
+  # - An app booted by a rake task (`rails db:migrate`, `rails db:create`,
+  #   ...): like Ecto, which migrates without starting the app, those get no
+  #   boot handle. The database may not exist yet, and a migration run must
+  #   not start the worker's background work. The migration helpers connect
+  #   a handle of their own; a task of your own that calls Trellis calls
+  #   Trellis::Railtie.connect. It's the task that counts, not the command:
+  #   `rails test` loads the tasks to run test:prepare, then boots the app
+  #   outside any task, so it gets its handle (but `bin/rails db:test:prepare
+  #   test` boots it inside the first task, so it doesn't).
+  # - config.trellis.connect_on_boot = false, for a server that forks with
+  #   no hook to shut the handle down first (see below).
+  #
+  # A handle doesn't survive fork. A preforking server that
+  # loads the app before forking (Puma's preload_app!, on by default with
+  # more than one worker) must shut the boot handle down before it forks,
+  # and connect one in each worker:
+  #
+  #   # config/puma.rb
+  #   before_fork { Trellis::Instance.shutdown_all }
+  #   before_worker_boot { Trellis::Railtie.connect } # on_worker_boot before Puma 7
+  #
+  # With Puma's fork_worker, worker 0 forks the others, so it needs
+  # before_worker_fork and after_worker_fork hooks as well: see "Forking
+  # servers" in the README.
+  class Railtie < ::Rails::Railtie
+    config.trellis = ActiveSupport::OrderedOptions.new
+    config.trellis.connect = nil
+    config.trellis.instances = {}
+    config.trellis.connect_on_boot = true
+    config.trellis.dump_database = "primary"
+
+    rake_tasks do
+      namespace :trellis do
+        desc "Create or upgrade Trellis's own tables, for config.trellis.connect and config.trellis.instances"
+        task migrate: :environment do
+          Trellis::Railtie.migrate_all
+        end
+      end
+    end
+
+    initializer "trellis.migration" do
+      ActiveSupport.on_load(:active_record) do
+        require "trellis/migration"
+        require "trellis/schema_dump"
+      end
+    end
+
+    config.after_initialize { Trellis::Railtie.instance.send(:boot) }
+
+    # The instances Railtie.connect opened for config.trellis.instances,
+    # by name.
+    @instances = {}
+
+    class << self
+      # Connects this process's instances from the config: the default
+      # instance from config.trellis.connect (when set), and each of
+      # config.trellis.instances. In a forked worker (Puma's
+      # before_worker_boot, Unicorn's after_fork, Passenger's
+      # starting_worker_process), or a rake task of your own. Raises
+      # ValidationError if neither is set, or if a named instance is already
+      # connected (as Trellis.connect does for the default one), and whatever
+      # Trellis.connect and Trellis::Instance.connect raise; the instances
+      # this call had connected are shut down first, so a failure leaves
+      # nothing half connected.
+      def connect
+        default = connect_options
+        named = instance_options
+        if default.nil? && named.empty?
+          raise ValidationError,
+                "config.trellis.connect is not set: give it Trellis.connect's options"
+        end
+        named.each_key do |name|
+          next unless @instances[name]&.connected?
+
+          raise ValidationError,
+                "the instance named #{name.inspect} is already connected: call " \
+                "Trellis::Instance.shutdown_all first"
+        end
+
+        opened = []
+        begin
+          if default
+            Trellis.connect(**default)
+            opened << -> { Trellis.shutdown }
+          end
+          named.each do |name, options|
+            instance = Trellis::Instance.connect(**options)
+            @instances[name] = instance
+            opened << -> { @instances.delete(name)&.shutdown }
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          opened.reverse_each { |undo| ignoring_errors(&undo) }
+          raise
+        end
+        nil
+      end
+
+      # The instance config.trellis.instances names `name`, connected by
+      # Railtie.connect. Raises ValidationError if there is none.
+      def named_instance(name)
+        instance = @instances[name.to_sym]
+        return instance if instance&.connected?
+
+        raise ValidationError,
+              "no connected instance named #{name.inspect}: name it in config.trellis.instances " \
+              "and call Trellis::Railtie.connect"
+      end
+
+      # Runs the block with an instance, running its migrate first, and
+      # returns the block's value. With no name, the default instance,
+      # yielded as well as reachable as the Trellis module; with a name, that
+      # instance of config.trellis.instances. If the instance isn't connected
+      # (a rake task gets no boot handle), connects one for the length of
+      # the block from its config, with staging: false and drain_threads: 0 so
+      # it starts no background work, and shuts it down after. What `rails
+      # trellis:migrate` and Trellis::Migration's helpers run on, for a script
+      # or rake task of your own that needs Trellis the way a migration does.
+      # Needs no ActiveRecord.
+      #
+      # Raises what the block raises. If the shutdown fails too, that's a
+      # warning, so it doesn't hide the block's error; after a block that
+      # returned, the shutdown's error is raised. Raises ValidationError if
+      # the instance isn't connected and its options aren't configured.
+      def with_handle(name = nil)
+        instance = name ? @instances[name.to_sym] : (Trellis.default_instance if Trellis.connected?)
+        if instance&.connected?
+          instance.migrate
+          return yield(instance)
+        end
+
+        options = name ? named_options(name) : required_connect_options
+        options = options.merge(staging: false, drain_threads: 0)
+        instance = name ? Trellis::Instance.connect(**options) : connect_default(options)
+        primary = nil
+        begin
+          instance.migrate
+          yield instance
+        rescue Exception => e # any exception, Interrupt too: it's re-raised
+          primary = e
+          raise
+        ensure
+          shutdown_after(name, instance, primary)
+        end
+      end
+
+      # Runs Trellis.migrate on the default instance (when
+      # config.trellis.connect is set) and on each of
+      # config.trellis.instances, each as with_handle does. Raises
+      # ValidationError if neither is set.
+      def migrate_all
+        default = connect_options
+        named = instance_options
+        if default.nil? && named.empty?
+          raise ValidationError,
+                "config.trellis.connect is not set: give it Trellis.connect's options"
+        end
+
+        with_handle { nil } if default
+        named.each_key { |name| with_handle(name) { nil } }
+        nil
+      end
+
+      # config.trellis.connect, as Trellis.connect's keyword options, or nil
+      # when it isn't set (or there's no Rails app).
+      def connect_options
+        app = ::Rails.respond_to?(:application) && ::Rails.application or return nil
+        options = app.config.trellis.connect or return nil
+
+        keyword_options("config.trellis.connect", options)
+      end
+
+      # config.trellis.instances, as each name's Trellis::Instance.connect
+      # keyword options; empty when it isn't set (or there's no Rails app).
+      def instance_options
+        app = ::Rails.respond_to?(:application) && ::Rails.application or return {}
+        instances = app.config.trellis.instances
+        return {} if instances.nil? || instances.empty?
+
+        unless instances.respond_to?(:to_h)
+          raise ValidationError,
+                "config.trellis.instances must be a Hash of names to Trellis::Instance.connect's " \
+                "options, got: #{instances.inspect}"
+        end
+
+        instances.to_h.to_h do |name, options|
+          [name.to_sym, keyword_options("config.trellis.instances[#{name.inspect}]", options)]
+        end
+      end
+
+      private
+
+      def keyword_options(what, options)
+        unless options.respond_to?(:to_h)
+          raise ValidationError,
+                "#{what} must be a Hash of Trellis.connect's options, got: #{options.inspect}"
+        end
+
+        options.to_h.transform_keys(&:to_sym)
+      end
+
+      def required_connect_options
+        connect_options or
+          raise ValidationError, "config.trellis.connect is not set: give it Trellis.connect's options"
+      end
+
+      def named_options(name)
+        instance_options.fetch(name.to_sym) do
+          raise ValidationError, "config.trellis.instances has no #{name.inspect}"
+        end
+      end
+
+      def connect_default(options)
+        Trellis.connect(**options)
+        Trellis.default_instance
+      end
+
+      def ignoring_errors
+        yield
+      rescue StandardError => e
+        warn "trellis: shutting down after a failed connect failed: #{e.class}: #{e.message}"
+      end
+
+      # Shuts with_handle's own instance down. With a primary error on its
+      # way out, a failed shutdown is only a warning: raising would replace
+      # it.
+      def shutdown_after(name, instance, primary)
+        name ? instance.shutdown : Trellis.shutdown
+      rescue StandardError => e
+        raise unless primary
+
+        warn "trellis: shutting down after #{primary.class} failed: #{e.class}: #{e.message}"
+      end
+    end
+
+    private
+
+    def boot
+      return if rake_running?
+
+      settings = ::Rails.application.config.trellis
+      return unless settings.connect_on_boot && (settings.connect || !self.class.instance_options.empty?)
+
+      self.class.connect
+    end
+
+    # Whether the app is booting inside a rake run (`rails db:migrate`,
+    # `rake db:create`), not just in a process that loaded the tasks:
+    # `rails test` loads them to run test:prepare, and only then, outside
+    # any task, boots the app.
+    def rake_running?
+      defined?(::Rake.application) && ::Rake.application.top_level_tasks.any?
+    end
+  end
+end