Managed databases

Managed databases give your app a private place to store structured records, such as customers, tasks, inventory, or saved results. The data belongs to the authenticated account and project.

Use a key with:

• hivemind-database in its service boundary;
• databases:read for account status, structure, records, and transfer status; and
• databases:write for provisioning, changes, uploads, downloads, and cancellation.

Use the dedicated database methods in the SDK. They keep access, confirmation, file-size, and workspace rules consistent.

Read account status and usage

const account = await hive.databases.account();
if (!account.ok) throw new Error(account.error);

console.log(account.active, account.tier, account.limits, account.usage);

The response reports whether managed database access is active, the eligible plan tier, current limits, current-month usage, and portability support. Treat all returned limits as authoritative for that account.

Provision the database workspace

Provisioning is an explicit, idempotent action:

import { HIVEMINDOS_DATABASE_CONFIRMATIONS } from "@hivemindos/sdk";

const provisioned = await hive.databases.provision(
  { confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.provision },
  { idempotencyKey: "customer-database-provision-v1" },
);

If the account is not eligible or has reached a plan boundary, show the returned next action to the account owner. Do not ask the caller to submit a plan name or quota override.

Query structure and records

Queries use POST /databases/query with databases:read. Query requests are read-only and do not require an idempotency key.

const records = await hive.databases.query({
  action: "list-records",
  tableId: 42,
  page: 1,
  pageSize: 50,
  orderBy: "created_at desc",
});

if (!records.ok) throw new Error(records.error);

Change structure and records

Writes use POST /databases/actions, require databases:write, and require both an idempotency key and the exact SDK confirmation for the action.

Supported field types are text, long_text, number, boolean, date, url, email, phone_number, and file.

const database = await hive.databases.mutate(
  {
    action: "create-database",
    workspaceId: 7,
    name: "Customers",
    confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.createDatabase,
  },
  { idempotencyKey: "customers-database-v1" },
);

const record = await hive.databases.mutate(
  {
    action: "create-record",
    tableId: 42,
    fields: {
      company: "Example Co",
      active: true,
      score: 91,
    },
    confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.createRecord,
  },
  { idempotencyKey: "customer-record-example-co-v1" },
);

Use a unique business identifier in the idempotency key so a retried write returns the original result instead of creating a duplicate.

Delete the managed workspace

Deleting the account workspace permanently removes its managed databases, records, usage history, and unfinished transfer files. Export anything you need first, then use the exact confirmation and an idempotency key:

const deleted = await hive.databases.deprovision(
  { confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.deprovision },
  { idempotencyKey: "customer-database-delete-v1" },
);

Repeating the same confirmed request is safe and returns active: false.

const started = await hive.databases.beginUpload(
  {
    fileName: "customer-workspace.zip",
    expectedBytes: archive.byteLength,
    sha256: archiveSha256,
    confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.migrateToCloud,
  },
  { idempotencyKey: "workspace-upload-2026-08-24" },
);

if (!started.ok) throw new Error(started.error);

const { migration, partSize } = started;
let partNumber = 1;

for (let offset = 0; offset < archive.byteLength; offset += partSize) {
  const part = archive.slice(offset, offset + partSize);
  const uploaded = await hive.databases.uploadPart(
    migration.id,
    partNumber,
    part,
    { idempotencyKey: `workspace-upload-part-${partNumber}` },
  );
  if (!uploaded.ok) throw new Error(uploaded.error);
  partNumber += 1;
}

await hive.databases.completeUpload(
  migration.id,
  { idempotencyKey: "workspace-upload-complete-2026-08-24" },
);

const started = await hive.databases.beginDownload(
  { confirmation: HIVEMINDOS_DATABASE_CONFIRMATIONS.migrateToLocal },
  { idempotencyKey: "workspace-download-2026-08-24" },
);

if (!started.ok) throw new Error(started.error);

const response = await hive.databases.downloadArchive(started.migration.id);
if (!response.ok) throw new Error(`Archive download failed: ${response.status}`);

const bytes = new Uint8Array(await response.arrayBuffer());
const expectedSha256 = response.headers.get("X-Content-Sha256");

Database errors

• HTTP 402 means the account needs an eligible subscription or is outside its included plan allowance.
• HTTP 409 means the requested confirmation, transfer state, or idempotency state does not permit the action.
• HTTP 410 means a requested archive has expired.
• HTTP 413 means the JSON request or archive part is too large.
• HTTP 424 means required managed-service setup is incomplete.

Next: review the endpoint reference or add runs and webhooks around the rest of your managed work.