databasus_ruby 0.1.0 → 0.2.0

data/lib/databasus_ruby/objects/databases.rb

@@ -3,40 +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", as: Database)
+    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)}"), as: Database)
     end
     alias find get
 
-    # POST /databases/create
+    # POST /databases
     def create(**attributes)
-      object(http_post("databases/create", with_default_workspace(attributes)), as: Database)
+      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), as: Database)
+    # 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}
@@ -49,43 +68,17 @@ module DatabasusRuby
       object(http_post("databases/#{escape(id)}/copy"), as: Database)
     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))
-    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 by id. A database returned by this endpoint
     # answers the same two methods without the id — see Database.
-    #
-    #   client.databases.backups(database.id, status: "COMPLETED")
-    #   client.databases.backup(database.id)          # queue a run
-    #
-    # #backups takes the same filters as Backups#list.
     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

data/lib/databasus_ruby/objects/workspaces.rb

@@ -4,21 +4,18 @@ module DatabasusRuby
   # Workspaces, their members and their audit trail.
   #
   #   workspace = client.workspaces.create(name: "production")
-  #   client.workspaces.add_member(workspace.id, email: "ops@example.com",
-  #                                role: "WORKSPACE_ADMIN")
+  #   client.workspaces.add_member(workspace.id, email: "ops@example.com", role: "WORKSPACE_ADMIN")
   #
-  # Note that the membership endpoints live under /workspaces/memberships/{id},
-  # where {id} is still the workspace id.
+  # Members are addressed by their member id (from #members), not their user id.
   class Workspaces < Object
     include Endpoint
 
     MEMBER_ROLES = %w[WORKSPACE_OWNER WORKSPACE_ADMIN WORKSPACE_MEMBER WORKSPACE_VIEWER].freeze
 
     # GET /workspaces — the workspaces the current user belongs to.
-    def list
-      collection(http_get("workspaces"), key: "workspaces")
+    def list(limit: nil, after: nil)
+      collection(http_get("workspaces", { limit: limit, after: after }))
     end
-
     alias all list
 
     # POST /workspaces
@@ -33,8 +30,8 @@ module DatabasusRuby
     alias find get
 
     # PUT /workspaces/{id}
-    def update(id, **attributes)
-      object(http_put("workspaces/#{escape(id)}", attributes))
+    def update(id, name:)
+      object(http_put("workspaces/#{escape(id)}", { name: name }))
     end
 
     # DELETE /workspaces/{id}
@@ -42,40 +39,36 @@ module DatabasusRuby
       acknowledged(http_delete("workspaces/#{escape(id)}"))
     end
 
-    # GET /workspaces/{id}/audit-logs
-    def audit_logs(id, limit: nil, offset: nil, before_date: nil)
-      response = http_get("workspaces/#{escape(id)}/audit-logs",
-                          { limit: limit, offset: offset, beforeDate: before_date })
-      collection(response, key: "auditLogs")
+    # POST /workspaces/{id}/transfer-ownership
+    def transfer_ownership(id, new_owner_member_id:)
+      acknowledged(http_post("workspaces/#{escape(id)}/transfer-ownership", { newOwnerMemberId: new_owner_member_id }))
     end
 
-    # GET /workspaces/memberships/{id}/members
-    def members(id)
-      collection(http_get("workspaces/memberships/#{escape(id)}/members"), key: "members")
+    # GET /audit-events
+    def audit_events(id, author_user_id: nil, limit: nil, after: nil)
+      collection(http_get("audit-events", {
+                            workspaceId: require_id(id), authorUserId: author_user_id, limit: limit, after: after
+                          }))
     end
 
-    # POST /workspaces/memberships/{id}/members — adds an existing user or
-    # invites a new one; the response `status` says which happened
-    # (ADDED or INVITED). `role` is one of MEMBER_ROLES.
-    def add_member(id, email:, role:)
-      object(http_post("workspaces/memberships/#{escape(id)}/members", { email: email, role: role }))
+    # GET /workspace-members
+    def members(id, limit: nil, after: nil)
+      collection(http_get("workspace-members", { workspaceId: require_id(id), limit: limit, after: after }))
     end
 
-    # DELETE /workspaces/memberships/{id}/members/{userId}
-    def remove_member(id, user_id)
-      acknowledged(http_delete("workspaces/memberships/#{escape(id)}/members/#{escape(user_id)}"))
+    # POST /workspace-members — `role` is one of MEMBER_ROLES except the owner.
+    def add_member(id, email:, role:)
+      object(http_post("workspace-members", { workspaceId: require_id(id), email: email, role: role }))
     end
 
-    # PUT /workspaces/memberships/{id}/members/{userId}/role
-    def change_member_role(id, user_id, role:)
-      acknowledged(http_put("workspaces/memberships/#{escape(id)}/members/#{escape(user_id)}/role",
-                            { role: role }))
+    # DELETE /workspace-members/{memberId}
+    def remove_member(member_id)
+      acknowledged(http_delete("workspace-members/#{escape(member_id)}"))
     end
 
-    # POST /workspaces/memberships/{id}/transfer-ownership
-    def transfer_ownership(id, new_owner_email:)
-      acknowledged(http_post("workspaces/memberships/#{escape(id)}/transfer-ownership",
-                             { newOwnerEmail: new_owner_email }))
+    # PUT /workspace-members/{memberId}
+    def change_member_role(member_id, role:)
+      object(http_put("workspace-members/#{escape(member_id)}", { role: role }))
     end
   end
 end

data/lib/databasus_ruby/records/database.rb

@@ -6,6 +6,7 @@ module DatabasusRuby
   #   database = client.databases.get(id)
   #   database.backups(status: "COMPLETED")
   #   database.backup                       # queue a run
+  #   database.settings.database            # name of the database on its server (PostgreSQL)
   #
   # Both delegate to the Backups endpoint, which owns the requests.
   class Database < Record

data/lib/databasus_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DatabasusRuby
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/databasus_ruby.rb

@@ -6,10 +6,12 @@ require_relative "databasus_ruby/version"
 
 # Ruby client for the Databasus backup-management API.
 #
-#   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: ENV["DATABASUS_EMAIL"], password: ENV["DATABASUS_PASSWORD"])
 #   client.databases.list(workspace_id: workspace_id)
 #
+# Targets the Databasus API of 3.65 and later.
+#
 # See DatabasusRuby::Client for how the endpoint domains hang off the client.
 module DatabasusRuby
   autoload :Client, "databasus_ruby/client"
@@ -20,6 +22,7 @@ module DatabasusRuby
 
   autoload :Error, "databasus_ruby/error"
   autoload :ConfigurationError, "databasus_ruby/error"
+  autoload :SignInCodeRequiredError, "databasus_ruby/error"
   autoload :APIError, "databasus_ruby/error"
   autoload :BadRequestError, "databasus_ruby/error"
   autoload :AuthenticationError, "databasus_ruby/error"
@@ -33,6 +36,7 @@ module DatabasusRuby
   autoload :Backups, "databasus_ruby/objects/backups"
   autoload :Databases, "databasus_ruby/objects/databases"
   autoload :Notifiers, "databasus_ruby/objects/notifiers"
+  autoload :Restores, "databasus_ruby/objects/restores"
   autoload :Storages, "databasus_ruby/objects/storages"
   autoload :Users, "databasus_ruby/objects/users"
   autoload :Workspaces, "databasus_ruby/objects/workspaces"