databasus_ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad2c73042db7ba0a3f3ee861359422ee14dc8a842250138e7320fe0c1f40b57
-  data.tar.gz: 963517d89578177d4f48e06e3be5c146ee973c0ca2a9163cda80bd2262d0d630
+  metadata.gz: c06a2f99b31ebac53becd79a06a01790a65e106890f2275f0645548197c33611
+  data.tar.gz: 14433d80684697a781025fb4dce7f0839fe5448dbc6cbef9f7c52e257b52c8b9
 SHA512:
-  metadata.gz: 990c3c288bce649ac4f8ca2db43b90197bdaeb0e0e3ad34b71aadfc71db58099d1c534fcdd82c2167b1f5b6d6f3b44f1077378447f8611e37faa0d22ddcbfd17
-  data.tar.gz: e405fe4b643aceec693cdc9b6a1a8f3261a94022271428b3aaa660ae8cb5bcf1a9aa3e4fc726570edd7fd489d64c1671bd7256c198cd6060f400dbccddf6fbdb
+  metadata.gz: 25a821696e164674b457941926ae8940ac8656af9106409fe9d63c7c2bb2f429805e52ab057725876f8e57697566d6327a4fe0b55604342cd9ac3793939953c1
+  data.tar.gz: a2b67bc8e87d04c3306b4c1198f4352f7cdd2f5af7177c456df0e5c23c46d808a38f17aa35ab1875b2cd5db281c4c4718193f14225ed4265347b6189cc4fcf06

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-13
+
+Targets the REST API of Databasus 3.65 and later. Databasus 3.65 replaced its
+API (new paths, cursor pagination, RFC 9457 problem responses), so this release
+does not talk to 3.64 or earlier: pin `~> 0.1.0` for those.
+
+### Added
+
+- `Restores` endpoint (`start`, `get`, `list`, `cancel`) and
+  `Restores.postgresql_target`, which restores without ownership and
+  privileges by default.
+- `Backups#download_to(id, io)` and `Client#stream`: backups stream to an IO
+  instead of being read into memory.
+- `Backups#get`; `Databases#list_all`, which follows the cursor; `Databases#test`
+  / `#connected?`; `Storages#backup_usage`; `Auth#verify_sign_in_code`.
+- `APIError#code` (the problem's `code`); validation field errors are appended
+  to the message.
+- `SignInCodeRequiredError`, raised by `Auth#signin` when the account needs an
+  emailed sign-in code.
+- `Collection#next_cursor`, `#last_page?` and `#extras` (page-level fields such
+  as the backups page's `totalUsageMb`).
+
+### Changed
+
+- Every path follows the 3.65 API: `POST /sessions`, `/logical-backups`,
+  `POST /download-tokens`, `PUT /databases/{id}`, `/workspace-members`,
+  `/audit-events`, `/instance-settings`, `/password-resets`.
+- List methods take `limit:` / `after:` instead of `limit:` / `offset:`.
+- Array query parameters repeat the key (`status=A&status=B`).
+- `Notifiers` and `Storages` split `save` into `create` and `update(id, ...)`.
+- Renamed: `Auth#send_reset_password_code` → `#request_password_reset`,
+  `Databases#test_connection` → `#test`, `Workspaces#audit_logs` → `#audit_events` (filter with `author_user_id:`).
+- Methods now take the target id positionally: `Databases#update(id, ...)`,
+  `Users#update(id, name:, email:)`, `Users#change_password(id, new_password:)`,
+  `Workspaces#update(id, name:)`.
+- Workspace membership is addressed by member id: `remove_member(member_id)`,
+  `change_member_role(member_id, role:)`, and
+  `transfer_ownership(id, new_owner_member_id:)` replaces `new_owner_email:`.
+- `Backups#list` filters with `created_before:` (was `before_date:`);
+  `Databases#list` accepts `notifier_id:`.
+- `APIError` messages come from the problem's `detail` / `title`;
+  `APIError.from_response` accepts a `body:` override for streamed responses.
+- JSON responses are parsed for any `*json*` content type
+  (e.g. `application/problem+json`).
+
+### Removed
+
+- Offset pagination (`Collection#total`, `#limit`, `#offset`, `#next_offset`).
+- Endpoints the API dropped: OAuth callbacks (`Auth#github_callback`,
+  `#google_callback`), `Users#me`, `#update_me`, `#invite`, readonly and
+  replication users (`Databases#create_readonly_user`,
+  `#create_replication_only_user`, `#readonly`, `#readonly?`), `Databases#test_connection_direct`,
+  notifier usage counts (`Databases#notifier_databases_count`,
+  `#notifier_using?`), and the `direct_test` methods of `Notifiers` and
+  `Storages`.
+
+## [0.1.0]
+
 ### Added
 
 - `DatabasusRuby::Client` with bearer authentication, an optional default

data/lib/databasus_ruby/client.rb

@@ -4,16 +4,14 @@ module DatabasusRuby
   # Entry point for the gem. Holds the connection and hands out one endpoint
   # object per API domain.
   #
-  #   client = DatabasusRuby::Client.new(
-  #     api_key: ENV["DATABASUS_API_KEY"],
-  #     url: "https://databasus.example.com/api/v1/"
-  #   )
+  #   client = DatabasusRuby::Client.new(url: "https://databasus.example.com/api/v1/")
+  #   client.auth.signin(email: "ops@example.com", password: "secret")
   #   client.databases.list(workspace_id: id)
   #
-  # `api_key` is sent as `Authorization: Bearer <api_key>`. Databasus accepts
-  # two kinds of bearer token there: a user JWT (from Auth#signin, used by
-  # every regular endpoint) and a verification-agent token (used by the
-  # /agent/* endpoints, which also need `agent_id`).
+  # Targets the Databasus REST API introduced in 3.65 (OpenAPI, cursor
+  # pagination, RFC 9457 problem responses). `api_key` is sent as
+  # `Authorization: Bearer <api_key>`; Auth#signin installs the session token
+  # there.
   class Client
     attr_reader :adapter, :url
     attr_accessor :api_key, :workspace_id
@@ -30,8 +28,11 @@ module DatabasusRuby
     def connection
       @connection ||= Faraday.new do |conn|
         conn.url_prefix = url
+        # Array filters (`status=A&status=B`) are form-style with explode,
+        # which the nested encoder would send as `status[]=`.
+        conn.options.params_encoder = Faraday::FlatParamsEncoder
         conn.request :json
-        conn.response :json, content_type: "application/json"
+        conn.response :json, content_type: /\bjson\b/
         conn.adapter adapter
       end
     end
@@ -52,6 +53,10 @@ module DatabasusRuby
       @notifiers ||= Notifiers.new(self)
     end
 
+    def restores
+      @restores ||= Restores.new(self)
+    end
+
     def storages
       @storages ||= Storages.new(self)
     end
@@ -64,8 +69,8 @@ module DatabasusRuby
       @workspaces ||= Workspaces.new(self)
     end
 
-    # The workspace-scoped list endpoints all require a workspace id; callers
-    # can either pass one per call or set a default on the client.
+    # The workspace-scoped list endpoints filter by workspace; callers can
+    # either pass one per call or set a default on the client.
     def workspace_id!
       return workspace_id unless workspace_id.nil? || workspace_id.to_s.empty?
 
@@ -78,9 +83,8 @@ module DatabasusRuby
     # decide how to interpret the body.
     def request(method, path, params: nil, body: nil, headers: nil)
       response = connection.public_send(method, path) do |req|
-        req.params.update(stringify(params)) if params
+        prepare(req, params: params, headers: headers)
         req.body = body unless body.nil?
-        req.headers.update(request_headers(headers))
       end
 
       raise APIError.from_response(response) unless response.success?
@@ -88,15 +92,67 @@ module DatabasusRuby
       response
     end
 
+    # GETs `path` and writes the body to `io` chunk by chunk, so a multi-GB
+    # backup never sits in memory. An error answer is collected instead and
+    # raised as the matching APIError. Returns the number of bytes written.
+    def stream(path, io:, params: nil)
+      sink = StreamSink.new(io)
+      response = connection.get(path) do |req|
+        prepare(req, params: params)
+        # Faraday streams only when on_data is a Proc (RequestOptions#stream_response?).
+        req.options.on_data = sink.to_proc
+      end
+      return sink.written if response.success?
+
+      raise APIError.from_response(response, body: sink.decoded_error_body)
+    end
+
+    # Routes streamed chunks: a 2xx body goes to the caller's io, anything else
+    # is kept so it can be raised as an APIError.
+    class StreamSink
+      attr_reader :written, :error_body
+
+      def initialize(io)
+        @io = io
+        @written = 0
+        @error_body = +""
+      end
+
+      def to_proc
+        proc { |chunk, _received, env| write(chunk, env) }
+      end
+
+      def decoded_error_body
+        return nil if error_body.empty?
+
+        JSON.parse(error_body)
+      rescue JSON::ParserError
+        error_body
+      end
+
+      private
+
+      def write(chunk, env)
+        return @error_body << chunk unless env.nil? || (200..299).cover?(env.status)
+
+        @io.write(chunk)
+        @written += chunk.bytesize
+      end
+    end
+    private_constant :StreamSink
+
     def inspect
-      "#<#{self.class.name} url=#{url.inspect} workspace_id=#{workspace_id.inspect}\
-      api_key=#{api_key.nil? ? "nil" : "[FILTERED]"}>"
+      "#<#{self.class.name} url=#{url.inspect} workspace_id=#{workspace_id.inspect} " \
+        "api_key=#{api_key.nil? ? "nil" : "[FILTERED]"}>"
     end
 
     private
 
-    # Databasus takes the token as a bearer credential; both a user JWT and a
-    # verification-agent token go in the same header.
+    def prepare(req, params: nil, headers: nil)
+      req.params.update(stringify(params)) if params
+      req.headers.update(request_headers(headers))
+    end
+
     def request_headers(extra)
       headers = {}
       headers["Authorization"] = "Bearer #{api_key}" unless api_key.nil? || api_key.to_s.empty?
@@ -110,13 +166,12 @@ module DatabasusRuby
       url.to_s.end_with?("/") ? url.to_s : "#{url}/"
     end
 
+    # Drops nils; arrays stay arrays so FlatParamsEncoder repeats the key.
     def stringify(params)
       params.each_with_object({}) do |(key, value), acc|
         next if value.nil?
 
-        # The only array-valued query parameter in the API (backups status)
-        # is declared as collectionFormat: csv.
-        acc[key.to_s] = value.is_a?(::Array) ? value.join(",") : value
+        acc[key.to_s] = value.is_a?(::Array) ? value.map(&:to_s) : value
       end
     end
   end

data/lib/databasus_ruby/collection.rb

@@ -3,40 +3,44 @@
 module DatabasusRuby
   # Uniform return value for every list endpoint.
   #
-  # Databasus answers lists in three different shapes: a bare array
-  # (GET /databases), a paginated envelope (GET /backups) and an unpaginated
-  # envelope (GET /workspaces). Collection flattens all three into an
-  # Enumerable that always answers #total, and answers #limit / #offset when
-  # the endpoint actually paginates.
+  # Databasus answers every list as a cursor page: `{ items: [...],
+  # nextCursor: "..." }`, plus page-level extras on some endpoints (the logical
+  # backups page carries `totalUsageMb`). Pass #next_cursor back as `after:` to
+  # read the next page; it is nil on the last one.
+  #
+  #   page = client.backups.list(database_id: id, limit: 50)
+  #   page.extras.total_usage_mb
+  #   page.next_cursor
   class Collection
     include Enumerable
 
-    attr_reader :data, :total, :limit, :offset
+    attr_reader :data, :next_cursor, :extras
 
     # `wrap` builds one entry from its raw hash; it defaults to a plain Object
     # and endpoints pass a Record builder instead.
-    def initialize(data: [], total: nil, limit: nil, offset: nil, wrap: nil)
+    def initialize(data: [], next_cursor: nil, extras: {}, wrap: nil)
       @data = data.map { |item| item.is_a?(Object) ? item : (wrap || Object.method(:new)).call(item) }
-      @total = total || @data.size
-      @limit = limit
-      @offset = offset
+      @next_cursor = next_cursor
+      @extras = extras.is_a?(Object) ? extras : Object.new(extras)
     end
 
-    # `key` names the array inside an envelope response and is ignored for
-    # bare-array responses.
-    def self.from(body, key:, wrap: nil)
+    PAGE_KEYS = %w[items nextCursor].freeze
+
+    def self.from(body, wrap: nil)
       case body
-      when ::Array
-        new(data: body, wrap: wrap)
-      when Hash
-        new(data: body[key] || [], total: body["total"], limit: body["limit"], offset: body["offset"], wrap: wrap)
-      when nil
-        new
-      else
-        raise Error, "unexpected list payload: #{body.class}"
+      when Hash then from_page(body, wrap)
+      when ::Array then new(data: body, wrap: wrap)
+      when nil, "" then new
+      else raise Error, "unexpected list payload: #{body.class}"
       end
     end
 
+    def self.from_page(page, wrap)
+      extras = page.reject { |key, _| PAGE_KEYS.include?(key.to_s) }
+      new(data: page["items"] || [], next_cursor: page["nextCursor"], extras: extras, wrap: wrap)
+    end
+    private_class_method :from_page
+
     def each(&block)
       return data.each unless block
 
@@ -61,25 +65,12 @@ module DatabasusRuby
       data.last
     end
 
-    def paginated?
-      !limit.nil?
-    end
-
-    # Offset to pass to the next call, or nil when this is the last page (or
-    # the endpoint does not paginate at all).
-    def next_offset
-      return nil unless paginated?
-
-      following = (offset || 0) + data.size
-      following < total ? following : nil
-    end
-
     def last_page?
-      next_offset.nil?
+      next_cursor.nil? || next_cursor.to_s.empty?
     end
 
     def inspect
-      "#<#{self.class.name} size=#{size} total=#{total} limit=#{limit.inspect} offset=#{offset.inspect}>"
+      "#<#{self.class.name} size=#{size} next_cursor=#{next_cursor.inspect}>"
     end
   end
 end

data/lib/databasus_ruby/endpoint.rb

@@ -49,9 +49,9 @@ module DatabasusRuby
       build(as, response.body.is_a?(Hash) ? response.body : {})
     end
 
-    # Wraps a list response; `key` names the array inside an envelope payload.
-    def collection(response, key:, as: Object)
-      Collection.from(response.body, key: key, wrap: ->(item) { build(as, item) })
+    # Wraps a cursor-page list response.
+    def collection(response, as: Object)
+      Collection.from(response.body, wrap: ->(item) { build(as, item) })
     end
 
     # Records need the client to reach their related endpoints; plain payload
@@ -65,13 +65,6 @@ module DatabasusRuby
       true
     end
 
-    # Endpoints answering a single-entry map whose key is not documented in the
-    # swagger schema, e.g. GET /databases/notifier/{id}/is-using.
-    def single_value(response)
-      body = response.body
-      body.is_a?(Hash) ? body.values.first : body
-    end
-
     # Request bodies are built from keyword arguments, and the API distinguishes
     # an absent key from a null one in a few places, so nils are dropped.
     def compact(body)

data/lib/databasus_ruby/error.rb

@@ -5,24 +5,44 @@ module DatabasusRuby
   class Error < StandardError; end
 
   # Raised when the client is missing something it needs before it can talk to
-  # the API at all (an agent id, a workspace id, ...).
+  # the API at all (a workspace id, a url, ...).
   class ConfigurationError < Error; end
 
+  # Raised by Auth#signin when the account requires an emailed sign-in code
+  # (two-factor). An unattended client cannot answer it; use an account
+  # without 2FA or finish with Auth#verify_sign_in_code.
+  class SignInCodeRequiredError < Error
+    attr_reader :pending_sign_in_id, :email
+
+    def initialize(pending_sign_in_id:, email:)
+      @pending_sign_in_id = pending_sign_in_id
+      @email = email
+      super("sign-in for #{email} needs the emailed code (pending sign-in #{pending_sign_in_id})")
+    end
+  end
+
   # Raised when Databasus answers with a non-successful status code.
+  #
+  # Databasus answers errors as RFC 9457 problems:
+  # `{ type, title, status, detail, code, errors }`. `code` is the stable
+  # machine-readable reason (`database_connection_failed`,
+  # `insufficient_disk_space`, `already_running`, ...).
   class APIError < Error
-    attr_reader :status, :body, :response
+    attr_reader :status, :body, :response, :code
 
-    def initialize(message = nil, status: nil, body: nil, response: nil)
+    def initialize(message = nil, status: nil, body: nil, response: nil, code: nil)
       @status = status
       @body = body
       @response = response
+      @code = code
       super(message || "Databasus API returned #{status}")
     end
 
     # Maps a Faraday response onto the most specific error class available.
-    def self.from_response(response)
+    # `body` overrides the response body (streamed responses carry none).
+    def self.from_response(response, body: response.body)
       klass = for_status(response.status)
-      klass.new(message_from(response.body), status: response.status, body: response.body, response: response)
+      klass.new(message_from(body), status: response.status, body: body, response: response, code: code_from(body))
     end
 
     def self.for_status(status)
@@ -31,15 +51,25 @@ module DatabasusRuby
       STATUS_ERRORS.fetch(status, APIError)
     end
 
-    # Every handler in the Go backend answers errors as {"error": "..."}, but
-    # streaming endpoints can still fail with a plain-text body.
+    # A validation problem's `detail` is generic ("the request breaks a
+    # validation rule"); the field errors are what say which rule.
     def self.message_from(body)
       case body
-      when Hash then body["error"] || body["message"] || body[:error]
+      when Hash then problem_message(body)
       when String then body.empty? ? nil : body[0, 500]
       end
     end
-    private_class_method :message_from
+
+    def self.problem_message(problem)
+      message = problem["detail"] || problem["title"] || problem["error"] || problem["message"]
+      fields = Array(problem["errors"]).filter_map { |e| "#{e["field"]}: #{e["detail"]}" if e.is_a?(Hash) }
+      fields.empty? ? message : [message, fields.join("; ")].compact.join(" — ")
+    end
+
+    def self.code_from(body)
+      body["code"] if body.is_a?(Hash)
+    end
+    private_class_method :message_from, :problem_message, :code_from
   end
 
   class BadRequestError < APIError; end

data/lib/databasus_ruby/objects/auth.rb

@@ -1,28 +1,46 @@
 # frozen_string_literal: true
 
 module DatabasusRuby
-  # Obtaining a token. Every other endpoint needs the JWT these methods
-  # return, so #signin and #signup install it on the client as `api_key`.
+  # Obtaining a session token. Every other endpoint needs the token these
+  # methods return, so a completed sign-in installs it on the client as
+  # `api_key`.
   #
   #   client.auth.signin(email: "me@example.com", password: "secret")
-  #   client.users.me.name
+  #   client.databases.list(workspace_id: id)
   #
-  # Read the token off the result if you want to keep it for a later client.
+  # An account with two-factor sign-in answers CODE_REQUIRED: #signin raises
+  # SignInCodeRequiredError and #verify_sign_in_code finishes it.
   class Auth < Object
     include Endpoint
 
-    # POST /users/signin
+    # POST /sessions
+    #
+    # @return [DatabasusRuby::Object] the completed sign-in (`token`, `userId`, `email`)
+    # @raise [DatabasusRuby::SignInCodeRequiredError] when the account needs the emailed code
     def signin(email:, password:, cloudflare_turnstile_token: nil)
-      authorize object(http_post("users/signin", {
+      outcome = object(http_post("sessions", {
                                    email: email,
                                    password: password,
                                    cloudflareTurnstileToken: cloudflare_turnstile_token
                                  }))
+      if outcome.outcome == "CODE_REQUIRED"
+        raise SignInCodeRequiredError.new(pending_sign_in_id: outcome.pending_sign_in_id, email: outcome.email)
+      end
+
+      authorize outcome
+    end
+
+    # POST /pending-sign-ins/{id}/verify
+    def verify_sign_in_code(pending_sign_in_id, code:, cloudflare_turnstile_token: nil)
+      authorize object(http_post("pending-sign-ins/#{escape(pending_sign_in_id)}/verify", {
+                                   code: code,
+                                   cloudflareTurnstileToken: cloudflare_turnstile_token
+                                 }))
     end
 
-    # POST /users/signup
+    # POST /users — self-registration, when the instance allows it.
     def signup(email:, name:, password:, cloudflare_turnstile_token: nil)
-      authorize object(http_post("users/signup", {
+      authorize object(http_post("users", {
                                    email: email,
                                    name: name,
                                    password: password,
@@ -30,27 +48,14 @@ module DatabasusRuby
                                  }))
     end
 
-    # POST /auth/github/callback
-    def github_callback(code:, redirect_uri:)
-      object(http_post("auth/github/callback", { code: code, redirectUri: redirect_uri }))
-    end
-
-    # POST /auth/google/callback
-    def google_callback(code:, redirect_uri:)
-      object(http_post("auth/google/callback", { code: code, redirectUri: redirect_uri }))
-    end
-
-    # POST /users/send-reset-password-code
-    def send_reset_password_code(email:, cloudflare_turnstile_token: nil)
-      object(http_post("users/send-reset-password-code", {
-                         email: email,
-                         cloudflareTurnstileToken: cloudflare_turnstile_token
-                       }))
+    # POST /password-resets — emails a reset code.
+    def request_password_reset(email:, cloudflare_turnstile_token: nil)
+      acknowledged(http_post("password-resets", { email: email, cloudflareTurnstileToken: cloudflare_turnstile_token }))
     end
 
-    # POST /users/reset-password
+    # POST /password-reset-completions
     def reset_password(email:, code:, new_password:)
-      object(http_post("users/reset-password", { email: email, code: code, newPassword: new_password }))
+      acknowledged(http_post("password-reset-completions", { email: email, code: code, newPassword: new_password }))
     end
 
     private

data/lib/databasus_ruby/objects/backups.rb

@@ -3,65 +3,90 @@
 module DatabasusRuby
   # Logical backups.
   #
-  #   backups = client.backups.list(database_id: id, status: %w[COMPLETED FAILED])
-  #   backups.total
-  #   backups.first.fileName
+  #   page = client.backups.list(database_id: id, status: "COMPLETED", limit: 20)
+  #   page.extras.total_usage_mb          # storage used by all of the database's backups
+  #   page.first.raw_database_size_mb     # size of the database when it was dumped
   #
-  # Downloads are a two-step flow: mint a short-lived token, then stream the
-  # file with it. #download does both.
+  #   File.open("dump", "wb") { |io| client.backups.download_to(backup.id, io) }
+  #
+  # A download is a single-use token (POST /download-tokens, valid five
+  # minutes) spent on GET /logical-backups/{id}/file. #download_to streams the
+  # file; #download reads it into memory and is only fit for small dumps.
   class Backups < Object
     include Endpoint
 
     STATUSES = %w[IN_PROGRESS COMPLETED FAILED CANCELED].freeze
-    ENCRYPTIONS = %w[NONE ENCRYPTED].freeze
     VERIFICATION_STATUSES = %w[NOT_VERIFIED VERIFIED_SUCCESSFUL VERIFICATION_FAILED].freeze
 
-    # GET /backups — `status` accepts a single value or an array.
-    def list(database_id:, limit: nil, offset: nil, status: nil, before_date: nil, pg_wal_backup_type: nil)
-      response = http_get("backups", {
-                            database_id: database_id,
-                            limit: limit,
-                            offset: offset,
+    # GET /logical-backups — newest first. `status` takes one value or an array.
+    def list(database_id:, status: nil, created_before: nil, limit: nil, after: nil)
+      response = http_get("logical-backups", {
+                            databaseId: require_id(database_id),
                             status: status,
-                            beforeDate: before_date,
-                            pgWalBackupType: pg_wal_backup_type
+                            createdBefore: created_before,
+                            limit: limit,
+                            after: after
                           })
-      collection(response, key: "backups")
+      collection(response)
     end
     alias all list
 
-    # POST /backups — queues a backup run for the database.
+    # GET /logical-backups/{id}
+    def get(id)
+      object(http_get("logical-backups/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /logical-backups — queues a backup run for the database.
     def create(database_id:)
-      object(http_post("backups", { database_id: database_id }))
+      object(http_post("logical-backups", { databaseId: require_id(database_id) }))
     end
     alias trigger create
 
-    # DELETE /backups/{id}
+    # DELETE /logical-backups/{id}
     def delete(id)
-      acknowledged(http_delete("backups/#{escape(id)}"))
+      acknowledged(http_delete("logical-backups/#{escape(id)}"))
     end
 
-    # POST /backups/{id}/cancel
+    # POST /logical-backups/{id}/cancel
     def cancel(id)
-      acknowledged(http_post("backups/#{escape(id)}/cancel"))
+      object(http_post("logical-backups/#{escape(id)}/cancel"))
     end
 
-    # POST /backups/{id}/download-token -> { token, filename, backupId }
+    # POST /download-tokens -> { token, fileName, expiresAt }
     def download_token(id)
-      object(http_post("backups/#{escape(id)}/download-token"))
+      object(http_post("download-tokens", { backupId: require_id(id) }))
     end
 
-    # GET /backups/{id}/file — returns the raw body; pass a token from
-    # #download_token.
+    # GET /logical-backups/{id}/file — the raw body, in memory.
     def file(id, token:)
-      http_get("backups/#{escape(id)}/file", { token: token }).body
+      http_get("logical-backups/#{escape(id)}/file", { token: token }).body
+    end
+
+    # Mints a token and streams the file into `io`.
+    #
+    # @return [DatabasusRuby::Object] the token grant (`file_name`, `expires_at`)
+    #   plus `bytes`, the number of bytes written
+    def download_to(id, io)
+      grant = download_token(id)
+      bytes = file_to(id, io, token: grant.token)
+      Object.new(grant.to_h.except("token").merge("bytes" => bytes))
+    end
+
+    # Streams the file into `io` with a token from #download_token. Mint the
+    # token first when the caller must fail before it starts answering (an
+    # HTTP response whose headers are already sent cannot turn into an error).
+    #
+    # @return [Integer] bytes written
+    def file_to(id, io, token:)
+      client.stream("logical-backups/#{escape(id)}/file", io: io, params: { token: token })
     end
 
-    # Mints a token and fetches the file in one call. Returns
-    # [filename, contents].
+    # Mints a token and fetches the file in one call, in memory. Returns
+    # [file_name, contents]. Prefer #download_to for real dumps.
     def download(id)
       grant = download_token(id)
-      [grant.filename, file(id, token: grant.token)]
+      [grant.file_name, file(id, token: grant.token)]
     end
   end
 end