databasus_ruby 0.0.1 → 0.2.0

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

data/lib/databasus_ruby/objects/databases.rb

@@ -3,39 +3,59 @@
 module DatabasusRuby
   # Databases under backup.
   #
-  #   client.databases.list(workspace_id: id)
-  #   client.databases.create(name: "primary", type: "POSTGRES_LOGICAL",
-  #                           workspaceId: id, postgresqlLogical: { ... })
+  #   client.databases.list(workspace_id: id).each { |database| database.name }
+  #   client.databases.create(name: "primary", workspaceId: id, notifierIds: [],
+  #                           settings: { type: "POSTGRES_LOGICAL", ... })
   #
-  # The create/update bodies are the full databases.Database payload, whose
-  # engine-specific half lives under one of `postgresqlLogical`,
-  # `postgresqlPhysical`, `mysql`, `mariadb` or `mongodb`.
+  # `settings` is the engine-specific half, discriminated by its `type`
+  # (POSTGRES_LOGICAL, POSTGRES_PHYSICAL, MYSQL, MARIADB, MONGODB).
   class Databases < Object
     include Endpoint
 
     TYPES = %w[POSTGRES_LOGICAL POSTGRES_PHYSICAL MYSQL MARIADB MONGODB].freeze
-    HEALTH_STATUSES = %w[AVAILABLE UNAVAILABLE].freeze
 
     # GET /databases
-    def list(workspace_id: nil)
-      collection(http_get("databases", { workspace_id: workspace_id || client.workspace_id! }), key: "databases")
+    def list(workspace_id: nil, notifier_id: nil, limit: nil, after: nil)
+      response = http_get("databases", {
+                            workspaceId: workspace_id || client.workspace_id!,
+                            notifierId: notifier_id,
+                            limit: limit,
+                            after: after
+                          })
+      collection(response, as: Database)
     end
     alias all list
 
+    # Every database of the workspace, following the cursor across pages.
+    #
+    # @return [Array<DatabasusRuby::Database>]
+    def list_all(workspace_id: nil, limit: 100)
+      databases = []
+      after = nil
+      loop do
+        page = list(workspace_id: workspace_id, limit: limit, after: after)
+        databases.concat(page.data)
+        break if page.last_page?
+
+        after = page.next_cursor
+      end
+      databases
+    end
+
     # GET /databases/{id}
     def get(id)
-      object(http_get("databases/#{escape(id)}"))
+      object(http_get("databases/#{escape(id)}"), as: Database)
     end
     alias find get
 
-    # POST /databases/create
+    # POST /databases
     def create(**attributes)
-      object(http_post("databases/create", with_default_workspace(attributes)))
+      object(http_post("databases", with_default_workspace(attributes)), as: Database)
     end
 
-    # POST /databases/update — the id travels in the body, not the path.
-    def update(**attributes)
-      object(http_post("databases/update", attributes))
+    # PUT /databases/{id} — the body is the full DatabaseUpdate payload.
+    def update(id, **attributes)
+      object(http_put("databases/#{escape(id)}", attributes), as: Database)
     end
 
     # DELETE /databases/{id}
@@ -45,47 +65,20 @@ module DatabasusRuby
 
     # POST /databases/{id}/copy
     def copy(id)
-      object(http_post("databases/#{escape(id)}/copy"))
-    end
-
-    # POST /databases/{id}/test-connection — true when the database answers.
-    def test_connection(id)
-      acknowledged(http_post("databases/#{escape(id)}/test-connection"))
-    end
-
-    # POST /databases/test-connection-direct — tests a payload that has not
-    # been saved yet.
-    def test_connection_direct(**attributes)
-      acknowledged(http_post("databases/test-connection-direct", attributes))
-    end
-
-    # POST /databases/create-readonly-user -> { username, password }
-    def create_readonly_user(**attributes)
-      object(http_post("databases/create-readonly-user", attributes))
-    end
-
-    # POST /databases/create-replication-only-user (PostgreSQL physical only)
-    def create_replication_only_user(**attributes)
-      object(http_post("databases/create-replication-only-user", attributes))
+      object(http_post("databases/#{escape(id)}/copy"), as: Database)
     end
 
-    # POST /databases/is-readonly -> { isReadOnly, privileges }
-    def readonly(**attributes)
-      object(http_post("databases/is-readonly", attributes))
+    # POST /databases/{id}/test -> { isConnected, reason, error }
+    def test(id)
+      object(http_post("databases/#{escape(id)}/test"))
     end
 
-    def readonly?(**attributes)
-      readonly(**attributes).isReadOnly == true
+    def connected?(id)
+      test(id).is_connected == true
     end
 
-    # The backups of one database, so a caller holding a database does not have
-    # to reach back for the other endpoint. Both delegate to Backups, which
-    # owns the requests.
-    #
-    #   client.databases.backups(database.id, status: "COMPLETED")
-    #   client.databases.backup(database.id)          # queue a run
-    #
-    # #backups takes the same filters as Backups#list.
+    # The backups of one database by id. A database returned by this endpoint
+    # answers the same two methods without the id — see Database.
     def backups(id, **filters)
       client.backups.list(database_id: require_id(id), **filters)
     end
@@ -93,15 +86,5 @@ module DatabasusRuby
     def backup(id)
       client.backups.create(database_id: require_id(id))
     end
-
-    # GET /databases/notifier/{id}/databases-count
-    def notifier_databases_count(notifier_id)
-      single_value(http_get("databases/notifier/#{escape(notifier_id)}/databases-count"))
-    end
-
-    # GET /databases/notifier/{id}/is-using
-    def notifier_using?(notifier_id)
-      single_value(http_get("databases/notifier/#{escape(notifier_id)}/is-using")) == true
-    end
   end
 end

data/lib/databasus_ruby/objects/notifiers.rb

@@ -3,23 +3,17 @@
 module DatabasusRuby
   # Notification channels.
   #
-  #   client.notifiers.save(name: "ops", notifierType: "SLACK",
-  #                         workspaceId: id, slackNotifier: { ... })
-  #
-  # POST /notifiers both creates and updates: include `id` in the payload to
-  # update an existing notifier.
+  #   client.notifiers.create(workspaceId: id, name: "ops", settings: { type: "SLACK", ... })
+  #   client.notifiers.update(notifier.id, name: "ops", settings: { type: "SLACK", ... })
   class Notifiers < Object
     include Endpoint
 
     TYPES = %w[EMAIL TELEGRAM WEBHOOK SLACK DISCORD TEAMS].freeze
-    NOTIFICATION_TYPES = %w[
-      ALL BACKUP_SUCCESS BACKUP_FAILED HEALTHCHECK_SUCCESS HEALTHCHECK_FAILED
-      VERIFICATION_SUCCESS VERIFICATION_FAILED
-    ].freeze
 
     # GET /notifiers
-    def list(workspace_id: nil)
-      collection(http_get("notifiers", { workspace_id: workspace_id || client.workspace_id! }), key: "notifiers")
+    def list(workspace_id: nil, limit: nil, after: nil)
+      collection(http_get("notifiers",
+                          { workspaceId: workspace_id || client.workspace_id!, limit: limit, after: after }))
     end
     alias all list
 
@@ -29,12 +23,15 @@ module DatabasusRuby
     end
     alias find get
 
-    # POST /notifiers
-    def save(**attributes)
+    # POST /notifiers — `workspaceId`, `name` and the type-specific `settings`.
+    def create(**attributes)
       object(http_post("notifiers", with_default_workspace(attributes)))
     end
-    alias create save
-    alias update save
+
+    # PUT /notifiers/{id} — `name` and `settings`.
+    def update(id, **attributes)
+      object(http_put("notifiers/#{escape(id)}", attributes))
+    end
 
     # DELETE /notifiers/{id}
     def delete(id)
@@ -43,17 +40,12 @@ module DatabasusRuby
 
     # POST /notifiers/{id}/test — sends a test notification.
     def test(id)
-      acknowledged(http_post("notifiers/#{escape(id)}/test"))
-    end
-
-    # POST /notifiers/direct-test — tests a payload that has not been saved yet.
-    def direct_test(**attributes)
-      acknowledged(http_post("notifiers/direct-test", attributes))
+      object(http_post("notifiers/#{escape(id)}/test"))
     end
 
     # POST /notifiers/{id}/transfer
     def transfer(id, target_workspace_id:)
-      acknowledged(http_post("notifiers/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
+      object(http_post("notifiers/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
     end
   end
 end

data/lib/databasus_ruby/objects/restores.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Restores of a logical backup into a target database.
+  #
+  #   target = DatabasusRuby::Restores.postgresql_target(
+  #     host: "db.internal", port: 5432, username: "app", password: "secret",
+  #     database: "copy_of_prod"
+  #   )
+  #   restore = client.restores.start(backup_id: backup.id, target: target)
+  #   client.restores.get(restore.id).status   # IN_PROGRESS -> COMPLETED | FAILED | CANCELED
+  #
+  # The target's secrets are used only by the running restore; Databasus does
+  # not store them.
+  class Restores < Object
+    include Endpoint
+
+    STATUSES = %w[IN_PROGRESS COMPLETED FAILED CANCELED].freeze
+    SSL_MODES = %w[disable require verify-ca verify-full].freeze
+
+    # Builds a PostgreSQL logical restore target.
+    #
+    # Ownership and privileges are off by default: restoring them needs the
+    # source cluster's roles on the target, and their absence is the usual
+    # cause of a restore that loads every row and still fails.
+    #
+    # @param cpu_count [Integer] parallel pg_restore jobs (Databasus caps it at 8)
+    # @param exclude_extensions [Boolean] skip CREATE EXTENSION entries
+    # @return [Hash] the `target` body of #start
+    def self.postgresql_target(host:, port:, username:, password:, database:, ssl_mode: "disable", cpu_count: 1,
+                               exclude_extensions: false, restore_ownership: false, restore_privileges: false,
+                               ssh_tunnel: nil)
+      {
+        type: "POSTGRES_LOGICAL",
+        host: host,
+        port: port,
+        username: username,
+        password: password,
+        database: database,
+        sslMode: ssl_mode,
+        sshTunnel: ssh_tunnel || { isEnabled: false },
+        cpuCount: cpu_count,
+        isExcludeExtensions: exclude_extensions,
+        isRestoreOwnership: restore_ownership,
+        isRestorePrivileges: restore_privileges
+      }
+    end
+
+    # GET /restores — the restores of one backup, newest first.
+    def list(backup_id:, limit: nil, after: nil)
+      collection(http_get("restores", { backupId: require_id(backup_id), limit: limit, after: after }))
+    end
+    alias all list
+
+    # POST /restores — answers at once with the restore IN_PROGRESS.
+    def start(backup_id:, target:)
+      object(http_post("restores", { backupId: require_id(backup_id), target: target }))
+    end
+    alias create start
+
+    # GET /restores/{id}
+    def get(id)
+      object(http_get("restores/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /restores/{id}/cancel
+    def cancel(id)
+      object(http_post("restores/#{escape(id)}/cancel"))
+    end
+  end
+end

data/lib/databasus_ruby/objects/storages.rb

@@ -3,19 +3,17 @@
 module DatabasusRuby
   # Backup destinations.
   #
-  #   client.storages.save(name: "offsite", type: "S3",
-  #                        workspaceId: id, s3Storage: { ... })
-  #
-  # POST /storages both creates and updates: include `id` in the payload to
-  # update an existing storage.
+  #   client.storages.create(workspaceId: id, name: "offsite", settings: { type: "S3", ... })
+  #   client.storages.backup_usage(storage.id)
   class Storages < Object
     include Endpoint
 
     TYPES = %w[LOCAL S3 GOOGLE_DRIVE NAS AZURE_BLOB FTP SFTP RCLONE].freeze
 
     # GET /storages
-    def list(workspace_id: nil)
-      collection(http_get("storages", { workspace_id: workspace_id || client.workspace_id! }), key: "storages")
+    def list(workspace_id: nil, limit: nil, after: nil)
+      collection(http_get("storages",
+                          { workspaceId: workspace_id || client.workspace_id!, limit: limit, after: after }))
     end
     alias all list
 
@@ -25,31 +23,34 @@ module DatabasusRuby
     end
     alias find get
 
-    # POST /storages
-    def save(**attributes)
+    # POST /storages — `workspaceId`, `name` and the type-specific `settings`.
+    def create(**attributes)
       object(http_post("storages", with_default_workspace(attributes)))
     end
-    alias create save
-    alias update save
+
+    # PUT /storages/{id} — `name` and `settings`.
+    def update(id, **attributes)
+      object(http_put("storages/#{escape(id)}", attributes))
+    end
 
     # DELETE /storages/{id}
     def delete(id)
       acknowledged(http_delete("storages/#{escape(id)}"))
     end
 
-    # POST /storages/{id}/test
-    def test(id)
-      acknowledged(http_post("storages/#{escape(id)}/test"))
+    # GET /storages/{id}/backup-usage — the catalog-recorded usage of the storage.
+    def backup_usage(id)
+      object(http_get("storages/#{escape(id)}/backup-usage"))
     end
 
-    # POST /storages/direct-test — tests a payload that has not been saved yet.
-    def direct_test(**attributes)
-      acknowledged(http_post("storages/direct-test", attributes))
+    # POST /storages/{id}/test
+    def test(id)
+      object(http_post("storages/#{escape(id)}/test"))
     end
 
     # POST /storages/{id}/transfer
     def transfer(id, target_workspace_id:)
-      acknowledged(http_post("storages/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
+      object(http_post("storages/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
     end
   end
 end

data/lib/databasus_ruby/objects/users.rb

@@ -1,79 +1,62 @@
 # frozen_string_literal: true
 
 module DatabasusRuby
-  # The signed-in user, instance-wide user administration and instance
-  # settings.
+  # Instance-wide user administration and instance settings.
   #
-  #   client.users.me.email
   #   client.users.list(query: "ops", limit: 25).each { |user| ... }
   #
-  # The #list / #get / #activate / #deactivate / #change_role and settings
-  # methods are ADMIN-only and answer 403 for a MEMBER token.
+  # Everything here except #update and #change_password on your own user is
+  # ADMIN-only and answers 403 for a MEMBER token.
   class Users < Object
     include Endpoint
 
     ROLES = %w[ADMIN MEMBER].freeze
 
-    # GET /users/me
-    def me
-      object(http_get("users/me"))
-    end
-
-    # PUT /users/me
-    def update_me(name: nil, email: nil)
-      object(http_put("users/me", { name: name, email: email }))
-    end
-
-    # PUT /users/change-password
-    def change_password(new_password:)
-      object(http_put("users/change-password", { newPassword: new_password }))
-    end
-
-    # POST /users/invite
-    def invite(email:, intended_workspace_id: nil, intended_workspace_role: nil)
-      object(http_post("users/invite", {
-                         email: email,
-                         intendedWorkspaceId: intended_workspace_id,
-                         intendedWorkspaceRole: intended_workspace_role
-                       }))
-    end
-
-    # GET /users (ADMIN)
-    def list(limit: nil, offset: nil, before_date: nil, query: nil)
-      response = http_get("users", { limit: limit, offset: offset, beforeDate: before_date, query: query })
-      collection(response, key: "users")
+    # GET /users
+    def list(query: nil, limit: nil, after: nil)
+      collection(http_get("users", { query: query, limit: limit, after: after }))
     end
     alias all list
 
-    # GET /users/{id} (ADMIN)
+    # GET /users/{id}
     def get(id)
       object(http_get("users/#{escape(id)}"))
     end
     alias find get
 
-    # POST /users/{id}/activate (ADMIN)
+    # PUT /users/{id}
+    def update(id, name:, email:)
+      object(http_put("users/#{escape(id)}", { name: name, email: email }))
+    end
+
+    # PUT /users/{id}/password
+    def change_password(id, new_password:)
+      acknowledged(http_put("users/#{escape(id)}/password", { newPassword: new_password }))
+    end
+
+    # POST /users/{id}/activate
     def activate(id)
       acknowledged(http_post("users/#{escape(id)}/activate"))
     end
 
-    # POST /users/{id}/deactivate (ADMIN)
+    # POST /users/{id}/deactivate
     def deactivate(id)
       acknowledged(http_post("users/#{escape(id)}/deactivate"))
     end
 
-    # PUT /users/{id}/role (ADMIN) — role is one of ROLES.
+    # PUT /users/{id}/role — role is one of ROLES.
     def change_role(id, role:)
       acknowledged(http_put("users/#{escape(id)}/role", { role: role }))
     end
 
-    # GET /users/settings (ADMIN) — instance-wide registration settings.
+    # GET /instance-settings
     def settings
-      object(http_get("users/settings"))
+      object(http_get("instance-settings"))
     end
 
-    # PUT /users/settings (ADMIN)
+    # PUT /instance-settings
     def update_settings(**attributes)
-      object(http_put("users/settings", attributes))
+      object(http_put("instance-settings", attributes))
     end
   end
 end