renuo-cli 4.26.0 → 4.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a823ac452e481aaafeb80aa230d417055acf874c70a08afbd6d056f80aac1db4
-  data.tar.gz: fd9b71e0470b1ba2b482654c899b89534f413e53e37196592882294a2e5f8998
+  metadata.gz: 352c9cb95e2c7548026938080ff46625617536757aa4653aa3412ac35dead312
+  data.tar.gz: dc0de5b1c6781136fe7b13d441c823b648a5efa36c3d28c1cc74e1f8ed8c2e2b
 SHA512:
-  metadata.gz: 5e9a521994e153153c4c62f93cac995ac23566b7f6a6808d32dccb5429fe2d9b9e12c99c5530ac8f3fb2177c595f421b39b6d49f51ab9881d594879dad579a31
-  data.tar.gz: baafab1e50838ff227a8afa97b294f6989e9e252afade2965d46175e47dd4bbd122e1ecde139e3a3c23abce6be7f886aa0bd1714b58be490f4b1820c33f407f0
+  metadata.gz: fe555bad89b04add4100bb6eb259a0194b1f30cb7d245dcd02418a7d65b6b2117c8903a3379747eacee069355060aefe3fd62798b03254d97a885af2d1d24f62
+  data.tar.gz: e77579335bff65754f3871272a7df43eca8b9728c7f1c314b4c39665520bdb8347c5a184868fe81f33d1518d8b66a914fa74a83d50f1fe9bc46057705f0d8da0

data/lib/renuo/cli/commands/ci/check_deploio_status.rb

@@ -18,7 +18,8 @@ module Renuo::Cli::Commands::Ci
 
     def run
       puts "[RENUO-CLI] (1/2) Checking build status for revision #{@revision}..."
-      succeeded = with_streamed_build_logs { poll_build }
+      puts "[RENUO-CLI] Waiting for build to start..."
+      succeeded = poll { build } && with_streamed_build_logs { poll_build }
       abort "[RENUO-CLI] build check timed out after #{TIMEOUT_IN_SECONDS} seconds" unless succeeded
 
       puts "[RENUO-CLI] (2/2) Checking release status for build #{build_name}..."
@@ -51,7 +52,7 @@ module Renuo::Cli::Commands::Ci
 
     def with_streamed_build_logs
       pid = Process.spawn(
-        "nctl logs application #{@app} -p #{@project} --type=build -f --lines=100 --since 15m --no-labels",
+        "nctl logs build #{build_name} -a #{@app} -p #{@project} -f --lines=100 --no-labels",
         out: $stdout, err: $stdout
       )
       yield
@@ -119,7 +120,6 @@ module Renuo::Cli::Commands::Ci
 
     def poll_build
       poll do
-        next puts("[RENUO-CLI] no matching build found, waiting...") unless build
         next true if succeeded?("build", build_name, build_status)
 
         @build = nil

data/lib/renuo/cli/commands/review_app/deploy.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Deploy < Actor
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+    include Contracts::Core
+
+    command "review-app:deploy" do |c|
+      c.syntax = "renuo review-app:deploy [options]"
+      c.summary = "Copies the origin Deploio app (matching the origin pattern) and its services " \
+                  "into a target review app for the current branch."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.option "--origin-pattern <pattern>", String, "Name pattern identifying the origin app to copy from"
+      c.option "--start", "Start the app right away instead of waiting for its env variables to be configured"
+      c.option "--keep-envs <categories>", Array,
+               "Copied env categories (build or runtime) to keep instead of dropping " \
+               "(comma-separated): #{Renuo::Cli::Services::Deploio::CopyApp::ENV_CATEGORIES.join(",")}"
+      c.example "renuo review-app:deploy -p renuo-acme --branch feature/42-migrate-to-deploio --origin-pattern develop",
+                "Creates a review app tracking feature/42-migrate-to-deploio, copied from the develop app"
+      c.example "renuo review-app:deploy -p renuo-acme -b fix/1337-we-can-fix-everything111 --origin-pattern develop " \
+                "--keep-envs=#{Renuo::Cli::Services::Deploio::CopyApp::ENV_CATEGORIES.join(",")} --start",
+                "Creates a review app reusing all the origin's env variables and starts it right away"
+      c.action do |_args, options|
+        call(project: options.project, branch: options.branch, origin_pattern: options.origin_pattern,
+             start: options.start, keep_envs: options.keep_envs || [])
+      end
+    end
+
+    input :project,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing project name" } } }
+    input :branch,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing branch name" } } }
+    input :origin_pattern,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing origin pattern name" } } }
+    input :start, default: false
+    input :keep_envs,
+          default: [],
+          must: {
+            be_known_categories: {
+              is: ->(value) { (value - Deploio::CopyApp::ENV_CATEGORIES).empty? },
+              message: (lambda do |value:, **|
+                "unknown env categories: #{(value - Deploio::CopyApp::ENV_CATEGORIES).join(", ")}"
+              end)
+            }
+          }
+
+    output :url
+
+    play :derive_target_app_name,
+         Deploio::InventorizeOriginResources,
+         :print_origin_resources,
+         Deploio::CopyApp
+
+    play Deploio::CreateDatabase,
+         Deploio::CopyDatabaseData,
+         if: ->(inventory) { inventory.origin_database_name }
+
+    play Deploio::CreateKvs,
+         if: ->(inventory) { inventory.origin_key_value_store_name }
+
+    play Deploio::CreateS3,
+         Deploio::CopyS3Data,
+         if: ->(inventory) { inventory.origin_bucket_name }
+
+    play :collect_target_envs,
+         Deploio::UpdateTargetAppEnv
+
+    play Deploio::StartTargetApp,
+         if: ->(result) { result.start }
+
+    play CmdTrail::Print,
+         :print_url
+
+    private
+
+    Contract Contracts::None => SafeReviewAppNameContract
+    def derive_target_app_name
+      result.target_app_name = review_app_name(branch).tap do |name|
+        abort "'#{name}' contains the origin pattern '#{origin_pattern}', aborting" if name.include?(origin_pattern)
+      end
+    end
+
+    def print_origin_resources
+      inventory_value = ->(key) { result.public_send(key) || "none" }
+
+      puts <<~INVENTORY
+        copying origin resources from project '#{result.project}':
+          app: #{result.origin_app_name}
+          database: #{inventory_value[:origin_database_name]}
+          database backup: #{inventory_value[:origin_backup_path]}
+          database backup bucket user: #{inventory_value[:origin_backup_bucket_user]}
+          key-value store: #{inventory_value[:origin_key_value_store_name]}
+          bucket: #{inventory_value[:origin_bucket_name]}
+          bucket user: #{inventory_value[:origin_bucket_user]}
+      INVENTORY
+    end
+
+    def collect_target_envs
+      result.envs = [result.database_env, result.kvs_env, result.s3_env].compact
+    end
+
+    def print_url
+      self.url = Deploio.fetch_resource("app", result.target_app_name, result.project)
+                        .dig("status", "atProvider", "defaultURLs", 0)
+      puts "\nthe review app will run at #{url || "<no URL assigned yet>"}"
+      puts "start it with: renuo review-app:start --project #{project} --branch #{branch}" unless start
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/name.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Name
+    include ReviewAppHelper
+    include Contracts::Core
+
+    command "review-app:name" do |c|
+      c.syntax = "renuo review-app:name [options]"
+      c.summary = "Prints the review app name derived from the branch."
+      c.description = c.summary
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "nctl update app $(renuo review-app:name -b add-s3-to-docs) -p renuo-acme --env KEY=value",
+                "Sets an env variable on the branch's review app"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      puts @name
+    end
+
+    private
+
+    def initialize(options)
+      branch = options.branch
+
+      abort "missing branch name" unless branch
+      @name = derive_name(branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_name(branch)
+      review_app_name(branch)
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/purge.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Purge
+    include ReviewAppHelper
+    include Contracts::Core
+    include Contracts::Invariants
+
+    RESOURCE_TYPES = %w[app postgresdatabase kvs bucket bucketuser].freeze
+
+    invariant(:name_pattern) { SafeReviewAppNameContract.valid?(@name_pattern) }
+
+    command "review-app:purge" do |c|
+      c.syntax = "renuo review-app:purge [options]"
+      c.summary = "Deletes all Deploio resources whose name contains the branch's review app name."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "renuo review-app:purge -p renuo-acme -b feature/42-migrate-to-deploio",
+                "Deletes all review app resources named after the branch"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      RESOURCE_TYPES.each { |type| purge_matching(type, @name_pattern) }
+      CmdTrail::Print.call
+    end
+
+    private
+
+    def initialize(options)
+      @project = options.project
+      branch = options.branch
+
+      abort "missing project name" unless @project
+      abort "missing branch name" unless branch
+      derive_name_pattern(branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_name_pattern(branch)
+      @name_pattern = review_app_name(branch)
+    end
+
+    Contract Contracts::Enum[*RESOURCE_TYPES], SafeReviewAppNameContract => Contracts::Any
+    def purge_matching(type, name_pattern)
+      names = matching_names(type, name_pattern)
+      return puts "no #{type} matching '#{name_pattern}' found, skipping" if names.empty?
+
+      names.each do |name|
+        puts "deleting #{type} #{name}..."
+        system! "nctl delete #{type} #{name} -p #{@project} --force --wait"
+      end
+    end
+
+    def matching_names(type, name_pattern)
+      nctl_resources("nctl get #{type} -p #{@project} -o yaml").filter_map do |resource|
+        next if resource.dig("metadata", "labels", "nine.ch/owned-by") == "nine"
+
+        name = resource.dig("metadata", "name")
+        name if name.include?(name_pattern)
+      end
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/setup_semaphoreci.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Renuo::Cli::Commands::ReviewApp
+  class SetupSemaphoreci
+    DEPLOY_PIPELINE_TEMPLATE_FILE = File.join(__dir__, "../../templates/semaphore/review-app-deploy.yml.erb")
+    PURGE_PIPELINE_TEMPLATE_FILE = File.join(__dir__, "../../templates/semaphore/review-app-purge.yml.erb")
+
+    DEPLOY_PIPELINE_TARGET_FILE = ".semaphore/review-app-deploy.yml"
+    PURGE_PIPELINE_TARGET_FILE = ".semaphore/review-app-purge.yml"
+
+    attr_reader :project, :origin_pattern
+
+    command "review-app:setup-semaphoreci" do |c|
+      c.syntax = "renuo review-app:setup-semaphoreci [options]"
+      c.summary = "Generates the pipeline files to deploy and purge Deploio review apps."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "--origin-pattern <pattern>", String, "Name pattern identifying the origin app to copy from"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      FileUtils.mkdir_p File.dirname(DEPLOY_PIPELINE_TARGET_FILE)
+      write_or_warn DEPLOY_PIPELINE_TARGET_FILE,
+                    render(DEPLOY_PIPELINE_TEMPLATE_FILE, { project:, origin_pattern:, secret_name: })
+      write_or_warn PURGE_PIPELINE_TARGET_FILE, render(PURGE_PIPELINE_TEMPLATE_FILE, { project:, secret_name: })
+      print_instructions
+    end
+
+    private
+
+    def initialize(options)
+      @project = options.project || abort("missing project name")
+      @origin_pattern = options.origin_pattern || abort("missing origin pattern")
+    end
+
+    def secret_name
+      "nctl-#{project}-review-apps"
+    end
+
+    # Deploio project names are prefixed with the name of their organization.
+    def organization
+      project.split("-").first
+    end
+
+    def print_instructions
+      service_account_name = "review-apps"
+      say <<~INSTRUCTIONS
+
+        Create a service account restricted to the Deploio project #{project}:
+
+          nctl create asa #{service_account_name} --project #{project}
+
+        Register its credentials as the Semaphore secret #{secret_name}, used by both pipelines:
+
+          sem create secret #{secret_name} \\
+            -e NCTL_API_CLIENT_ID="$(nctl get asa #{service_account_name} --project #{project} --print-client-id)" \\
+            -e NCTL_API_CLIENT_SECRET="$(nctl get asa #{service_account_name} --project #{project} --print-client-secret)" \\
+            -e NCTL_ORGANIZATION=#{organization}
+
+        Add these promotions to .semaphore/semaphore.yml (no auto_promote, so they only run on click):
+
+          - name: review-app-deploy
+            pipeline_file: review-app-deploy.yml
+
+          - name: review-app-purge
+            pipeline_file: review-app-purge.yml
+
+        Both buttons appear on every branch workflow in Semaphore. Deploy and purge the review app
+        of a branch by clicking the promotion on that branch's workflow.
+      INSTRUCTIONS
+    end
+
+    def render(template_file, variables)
+      ERB.new(File.read(template_file)).result_with_hash(variables)
+    end
+
+    def write_or_warn(file_path, content)
+      if File.exist?(file_path)
+        warn("#{file_path} exists already. I will not overwrite it.")
+      else
+        File.write(file_path, content)
+        say("#{file_path} added.")
+      end
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/start.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Start
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+    include Contracts::Core
+    include Contracts::Invariants
+
+    invariant(:target_app_name) { SafeReviewAppNameContract.valid?(@target_app_name) }
+
+    command "review-app:start" do |c|
+      c.syntax = "renuo review-app:start [options]"
+      c.summary = "Starts the branch's review app once its env variables are configured."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "renuo review-app:start -p renuo-acme -b feature/42-migrate-to-deploio",
+                "Builds and deploys the branch's review app"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      Deploio::StartTargetApp.call(project: @project, target_app_name: @target_app_name, branch: @branch)
+      CmdTrail::Print.call
+      print_url
+    end
+
+    private
+
+    def print_url
+      url = Deploio.fetch_resource("app", @target_app_name, @project)
+                   .dig("status", "atProvider", "defaultURLs", 0)
+      puts "\nthe review app will run at #{url || "<no URL assigned yet>"}"
+    end
+
+    def initialize(options)
+      @project = options.project
+      @branch = options.branch
+
+      abort "missing project name" unless @project
+      abort "missing branch name" unless @branch
+      derive_target_app_name(@branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_target_app_name(branch)
+      @target_app_name = review_app_name(branch)
+    end
+  end
+end

data/lib/renuo/cli/helpers/actor_contracts.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Lets service actors state contracts.ruby-style contracts (anything with .valid?) as must: checks.
+module ActorContracts
+  def satisfy(*contracts)
+    contracts.to_h do |contract|
+      raise ArgumentError, "#{contract.inspect} is not a contract (no .valid?)" unless contract.respond_to?(:valid?)
+
+      [:"satisfy_#{contract.name.demodulize.underscore}",
+       { is: ->(value) { contract.valid?(value) },
+         message: ->(value:, **) { "#{value.inspect} is not #{contract}" } }]
+    end
+  end
+end
+
+Actor.extend(ActorContracts)

data/lib/renuo/cli/helpers/cmd_trail.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Collects every CLI command a run executes so Print can show how to reproduce it.
+module CmdTrail
+  module_function
+
+  def record(command, env = {})
+    entries << { command: command, env: env }
+  end
+
+  def entries
+    @entries ||= []
+  end
+
+  def clear
+    entries.clear
+  end
+
+  class Print < Actor
+    SENSITIVE_KEY_PATTERN = /KEY|SECRET|TOKEN|PASSWORD/i
+    URL_PASSWORD_PATTERN = %r{(://[^:/@\s]*:)[^@\s]+@}
+
+    def call
+      return if CmdTrail.entries.empty?
+
+      puts "\nexecuted commands (rerun them to reproduce):"
+      CmdTrail.entries.each { |entry| puts "  #{line(entry)}" }
+    end
+
+    private
+
+    def line(entry)
+      [env_prefix(entry[:env]), redact(entry[:command])]
+        .reject(&:empty?).join(" ")
+    end
+
+    def redact(command)
+      command.sub(/--sensitive-env .*/, "--sensitive-env [redacted]").gsub(URL_PASSWORD_PATTERN, '\\1[redacted]@')
+    end
+
+    def env_prefix(env)
+      env.map { |key, value| "#{key}=#{SENSITIVE_KEY_PATTERN.match?(key) ? "[redacted]" : value}" }.join(" ")
+    end
+  end
+end

data/lib/renuo/cli/helpers/review_app_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ReviewAppHelper
+  HASH_LENGTH = 6
+  MAX_NUMBER_LENGTH = 10
+  NAME_PATTERN = /\Areview-app-(?:\d{1,#{MAX_NUMBER_LENGTH}}-)?\h{#{HASH_LENGTH}}\z/
+  MIN_PATTERN_LENGTH = 3
+
+  def review_app_name(branch)
+    number = branch[/\d+/]&.slice(0, MAX_NUMBER_LENGTH)
+    ["review-app", number, Digest::SHA256.hexdigest(branch)[0, HASH_LENGTH]].compact.join("-")
+  end
+
+  # nctl prints a YAML stream, a YAML list, "[]" or a plain-text banner, depending on version and match count
+  def nctl_resources(command)
+    stdout, = system!(command, quiet: true)
+    return [] if stdout.lines.first.to_s.match?(/No ".+" found/)
+
+    resources = Psych.load_stream(stdout).flatten.compact
+    return resources if resources.all?(Hash)
+
+    abort "'#{command}' printed no nctl resources:\n#{stdout}"
+  rescue Psych::SyntaxError
+    abort "'#{command}' printed no nctl resources:\n#{stdout}"
+  end
+
+  def system!(command, env = {}, quiet: false, abort_on_failure: true)
+    CmdTrail.record(command, env)
+    stdout, stderr, status = Open3.capture3(env, command)
+    puts stdout unless quiet || stdout.empty?
+    if !status.success? && abort_on_failure
+      abort "'#{command.split.first(2).join(" ")}' failed: #{stderr.presence || stdout}"
+    end
+    [stdout, stderr, status]
+  end
+
+  def aws_credentials(access_key, secret_key)
+    {
+      "AWS_ACCESS_KEY_ID" => access_key,
+      "AWS_SECRET_ACCESS_KEY" => secret_key,
+      "AWS_DEFAULT_REGION" => "us-east-1"
+    }
+  end
+end

data/lib/renuo/cli/helpers/safe_review_app_name_contract.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "contracts"
+
+# Module-wide contract: a name that may address review app resources on Deploio.
+# Commands establish it as a postcondition of name derivation and keep it as a
+# class invariant; the Deploio actors demand it as a precondition before touching
+# any resource. A violation always means a bug, never bad user input.
+class SafeReviewAppNameContract
+  def self.valid?(name)
+    name.is_a?(String) && name.match?(ReviewAppHelper::NAME_PATTERN)
+  end
+
+  def self.to_s
+    "a review app name matching #{ReviewAppHelper::NAME_PATTERN.inspect}"
+  end
+end

data/lib/renuo/cli/services/deploio/copy_app.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class Renuo::Cli::Services::Deploio
+  class CopyApp < Actor
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+
+    ENV_CATEGORIES = %w[build sensitive-build runtime sensitive-runtime].freeze
+
+    input :project
+    input :target_app_name, must: satisfy(SafeReviewAppNameContract)
+    input :origin_app_name
+    input :branch
+    input :keep_envs, default: []
+
+    def call
+      if Deploio.resource_exists?("app", target_app_name, project)
+        puts "app #{target_app_name} already exists, skipping copy"
+      else
+        puts "copying app #{origin_app_name} to #{target_app_name}..."
+        system! "nctl copy app #{origin_app_name} -p #{project} --target-name #{target_app_name}"
+        reconfigure_copy
+      end
+    end
+
+    private
+
+    def reconfigure_copy
+      Kernel.sleep(1) # Deploio usually needs a moment to finish reconciling the fresh copy
+      flags = [delete_flag("--delete-env", dropped_keys("config", "env", kind: "runtime")),
+               delete_flag("--delete-build-env", dropped_keys("buildEnv", kind: "build"))].compact
+      dropping = flags.empty? ? "" : " and dropping the copied env variables"
+      puts "pointing #{target_app_name} at branch #{branch}#{dropping}..."
+      system! ["nctl update app #{target_app_name} -p #{project}",
+               "--git-revision #{Shellwords.escape(branch)} --skip-repo-access-check",
+               *flags].join(" ")
+    end
+
+    def delete_flag(flag, keys)
+      "#{flag} #{Shellwords.escape(keys.join(";"))}" unless keys.empty?
+    end
+
+    def dropped_keys(*path, kind:)
+      env = copied_spec.dig(*path) || []
+      env.reject { |variable| keep_envs.include?(variable["sensitive"] ? "sensitive-#{kind}" : kind) }
+         .map { |variable| variable["name"] }
+    end
+
+    def copied_spec
+      @copied_spec ||= Deploio.fetch_resource("app", target_app_name, project).dig("spec", "forProvider") || {}
+    end
+  end
+end

data/lib/renuo/cli/services/deploio/copy_database_data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class Renuo::Cli::Services::Deploio
+  class CopyDatabaseData < Actor
+    include ReviewAppHelper
+
+    BACKUP_FILE = File.join(Dir.tmpdir, "review-app-backup.sql.zst")
+    USER_TABLES_QUERY = "SELECT count(*) FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema')"
+
+    input :target_app_name, must: satisfy(SafeReviewAppNameContract)
+    input :database_env
+    input :origin_backup_bucket
+    input :origin_backup_path
+    input :origin_backup_endpoint
+    input :origin_backup_access_key
+    input :origin_backup_secret_key
+
+    def call
+      return warn "no origin database backup found, leaving #{target_app_name} empty" unless origin_backup_path
+      return puts "database #{target_app_name} already holds tables, skipping backup restore" unless database_empty?
+
+      puts "restoring #{origin_backup_path} into #{target_app_name}..."
+      download_backup
+      system! "zstd -dfq #{BACKUP_FILE}"
+      restore_backup
+    ensure
+      FileUtils.rm_f([BACKUP_FILE, BACKUP_FILE.delete_suffix(".zst")])
+    end
+
+    private
+
+    def download_backup
+      system! "aws s3 cp s3://#{origin_backup_bucket}/#{origin_backup_path} #{BACKUP_FILE} " \
+              "--endpoint-url https://#{origin_backup_endpoint}",
+              aws_credentials(origin_backup_access_key, origin_backup_secret_key)
+    end
+
+    def database_empty?
+      stdout, = system!("psql #{database_url} -tAc #{Shellwords.escape(USER_TABLES_QUERY)}", quiet: true)
+      Integer(stdout.strip).zero?
+    end
+
+    # Despite their .sql.zst name, Deploio backups are pg_dump custom-format archives.
+    # A single transaction leaves the database empty on failure, so a rerun restores it again.
+    def restore_backup
+      system! "pg_restore --single-transaction --no-owner --no-privileges --no-comments " \
+              "-d #{database_url} " \
+              "#{BACKUP_FILE.delete_suffix(".zst")}"
+    end
+
+    def database_url
+      Shellwords.escape(database_env.fetch("DATABASE_URL"))
+    end
+  end
+end