Import and export a database

​

Goal

​

Prerequisites

• A running PostgreSQL or MySQL database on the qualified hosted V2 containerd runtime
• A transfer-capable digest-qualified hosted agent and stable-endpoint lineage
• Project mutation permission for a project database, or ownership of a standalone database

​

Workflow

​

Eligibility and exclusions

• Supported: complete hosted V2 PostgreSQL and MySQL logical databases.
• Not supported: Redis, connected-node databases, selective tables, server-global users/roles/grants, custom URL authentication headers, or automatic promotion.
• One nonterminal import and one nonterminal export may exist for the same stable database. A second active transfer in the same direction returns conflict.

​

Formats, compression, checksums, and limits

stored import limit = min(20 GiB, max(1 GiB, 2 × target disk))
expanded SQL limit = min(64 GiB, max(4 GiB, 4 × target disk))

plain export stored limit = expanded SQL limit
gzip export stored limit = 20 GiB
gzip export expanded dump must also remain within the expanded SQL limit

​

Export behavior

• PostgreSQL exports schema and data without ownership or privilege statements.
• MySQL exports use a consistent transaction and include routines, events, triggers, and binary-safe values; incompatible nontransactional behavior is rejected.
• Server-global roles, users, grants, and unrelated databases are excluded.
• Dump-client, compressor, object upload, multipart completion, byte totals, and checksums are verified independently before completion.
• Generated filenames are sanitized and include database name, engine, UTC timestamp, and .sql or .sql.gz.

​

Resumable browser upload

• Every non-final part is exactly 64 MiB; the last part may be smaller.
• The manifest contains 1–320 ordered parts with exact sizes and lowercase SHA-256 checksums.
• Signed part URLs last 15 minutes and are bound to the exact object, part number, size, and checksum.
• Recreating an identical session reconciles provider-reported parts and returns URLs only for missing parts.
• Starting import verifies every part, completes multipart upload, and verifies the final provider checksum before restore is queued.

​

Hardened HTTPS import

• At most five redirects; every destination is revalidated and authorization/cookie/proxy-authorization headers are stripped.
• TLS 1.2 or later with hostname verification, 10-second connect/TLS, 30-second response-header, 30-second no-progress, and six-hour overall limits.
• All DNS answers and the connected peer are checked; connections are pinned to an approved address to prevent DNS rebinding.
• Loopback, private, link-local, multicast, unspecified, metadata, carrier-grade NAT, benchmark, control-plane, and configured deployment networks are blocked.
• Stored-byte limits are enforced while streaming even when Content-Length is missing or misleading.

​

Restore isolation

• PostgreSQL restore receives no superuser capability; ownership is reassigned before the temporary role is removed.
• MySQL restore receives candidate-database privileges only and never FILE or global privileges.
• PostgreSQL shell, unsafe \copy, and include commands and MySQL system, source, tee, and pager commands are rejected outside strings/comments.
• Fetch, hash, decompression, SQL guard, SQL client, compression, upload, and multipart status are preserved separately.

​

Structural validation and candidate inspection

• Stored and expanded checksums and complete SQL-client success.
• Database health and PostgreSQL pg_amcheck or MySQL extended table checks.
• Schema/table/object counts, per-table row-count summary, total rows, and canonical schema manifest.
• An immutable evidence hash binding artifact, candidate, engine, clients, checksums, and manifest.
• Candidate workbench: schema browsing plus one read-only statement, no semicolon, at most 500 rows, 2 MiB of result data, and 10 seconds.

​

Promotion and rollback

• The active database stays unchanged when upload, fetch, provisioning, restore, or validation fails.
• The replaced generation remains read-only for exactly 24 hours after successful promotion.
• Manual rollback is allowed only while that promoted generation remains current and before rollback_deadline.
• A newer promotion supersedes an older rollback action even though cleanup still honors the original retention deadline.

​

Downloads, cancellation, expiry, and durable state

• Download appears only for a verified completed export. Each token is opaque, single-use, valid for 10 minutes, and rejects HTTP Range requests.
• Cancellation is cooperative and allowed only before promotion begins.
• Inactive failed, cancelled, expired, or rolled-back transfers can be purged early, but purge never shortens retained-generation rollback.
• The durable transfer states are uploading, fetching, queued, exporting, restoring, validating, ready_to_promote, promoting, active, rolling_back, rolled_back, failed, cancelled, expired, and purged.
• The UI polls about every two seconds while active, every ten seconds while rollback is available, refreshes on focus, and stops in terminal states.

​

API route families and idempotency

/api/v1/projects/{projectID}/databases/{databaseID}/transfers
/api/v1/databases/{databaseID}/transfers

GET    /
POST   /exports
POST   /upload-sessions
POST   /imports
GET    /{transferID}
POST   /{transferID}/download-url
POST   /{transferID}/cancel
POST   /{transferID}/promote
POST   /{transferID}/rollback
DELETE /{transferID}
GET    /{transferID}/candidate/schema
POST   /{transferID}/candidate/query

{
  "format": "sql",
  "compression": "gzip"
}

{
  "source": {
    "kind": "url",
    "url": "https://objects.example.com/database.sql.gz?signature=...",
    "expected_sha256": "<64 lowercase hexadecimal characters>"
  }
}

​

Expected result

​

Common failures

​

Related guides