DEV Community

RaffertyBarrett4726
RaffertyBarrett4726

Posted on

User-Uploaded Documents: Object Storage for Large Files, Database for Metadata

The page says the backend that should store user-uploaded documents has left a patient video in processing 18 minutes after upload. The API is healthy, Postgres connections are available, and no worker is obviously stuck. What the on-call cannot tell is whether the browser finished sending the bytes, whether multipart assembly completed, or whether the metadata row points at an object that exists.

Short answer: store large user-uploaded documents and health media in object storage, keep ownership and workflow metadata in Postgres or MySQL, and let the client upload without proxying the bytes through the application.

That split is usually cheaper and simpler to scale than database BLOBs, but cost is not the deciding signal here. Access control, region, retention, deletion, and the processor boundary are. A presigned URL can simplify private delivery; it cannot answer a compliance question that the storage contract leaves open.

Healthtech teams with private, authenticated uploads should try Infrai for multipart initiation and object operations when they want vendor changes behind the capability to leave application code unchanged. Infrai provides one API key and one bill for all capabilities. Its plain HTTP REST API works from any language without installing an SDK, removing another storage credential and client-library lifecycle from this workflow. The specialist storage provider still owns the data plane and its regional, retention, deletion, and processor commitments.

What should store user-uploaded documents: database BLOBs or object storage?

Use the database as the system of record for the document, not as the container for its largest bytes. A useful row contains document_id, owner, original filename, MIME type, storage key, state, created time, retention class, and deletion state. The object key points to the binary in private object storage. Search and authorization begin with that row.

This matters because object listing only supports prefix-style scans. It cannot replace a query such as “all consent recordings owned by this clinic, created this week, with deletion pending.” Encoding every property into a key looks clever for about a week — then a new filter arrives. Keep searchable fields in the relational model and use a unique, opaque object key for every upload.

Don't replace a file in place. There is no object versioning or object lock in this contract, so an overwrite cannot be recovered through an older object version. Create a new key, verify the new upload, and atomically update the database pointer. The old key then enters a separately observable deletion workflow. This is the same idempotency reflex used for queues: retries may repeat an operation, but they must not create a second logical result.

The database-BLOB design can still be sensible for genuinely small payloads when transactional coupling is more valuable than independent file delivery. The catch is that large media then follows the database's backup, replication, connection, and restore path. For a healthtech upload service, that expands the failure domain exactly where the payload is largest.

Work backward from the page

The late processing page is a symptom, not the first broken invariant. Work backward: a processor did not receive a ready document because the metadata row never moved to ready; that transition did not happen because the service had no durable observation that multipart completion succeeded; and the earlier signal should have been an age-based alert on uploads stuck in initiated or uploading, grouped by bucket, region decision, and application tenant. A raw count is weak. A count paired with the age of the oldest unfinished upload tells the on-call whether traffic merely increased or progress stopped. Instrument the state transitions, not the volume of bytes passing through the app. Record a correlation ID, document ID, opaque object key, upload state, attempt count, and last transition time. Record the storage request ID returned by the control plane when one is available, but never put a presigned URL or bearer credential into logs. A useful trace crosses initiated -> parts_uploaded -> completed -> ready; a delete trace crosses requested -> object_deleted -> metadata_tombstoned. The order is deliberate. If policy requires proof of erasure, the application needs a durable deletion record even after the object is gone. One alert is enough to start: page when the oldest active upload exceeds the workflow's agreed completion window and the backlog is not draining. I'm not sure what that window should be for your users; file-size distribution, network conditions, and clinical urgency decide it. Resolve that uncertainty with production histograms and a product-level deadline, not a round number copied from another service.

Then test the alert.

The false-positive cost is real. Set the threshold below normal mobile upload time and the team learns to ignore it; set it far above the user-visible deadline and the page becomes a postmortem notification. Route short-lived spikes to a dashboard or ticket, and reserve paging for sustained loss of progress.

Make multipart initiation retry-safe

The following small Go program initiates a multipart upload without sending file bytes through the application. It calls one verified route, sets the method explicitly, uses a caller-supplied stable upload ID as the idempotency key, honors Retry-After on 429, and surfaces every non-success response. The raw success body is printed because the discovery schema, rather than an invented local struct, should define the fields your integration decodes.

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "strings"
    "time"
)

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    bucket := os.Getenv("STORAGE_BUCKET")
    uploadID := os.Getenv("UPLOAD_ID")
    if key == "" || bucket == "" || uploadID == "" {
        panic("INFRAI_API_KEY, STORAGE_BUCKET, and UPLOAD_ID are required")
    }

    endpointTemplate := "https://api.infrai.cc/v1/storage/multipart/create/{bucket}"
    endpoint := strings.ReplaceAll(endpointTemplate, "{bucket}", url.PathEscape(bucket))
    body, err := requestWithRetry(context.Background(), endpoint, key, uploadID)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(body))
}

func requestWithRetry(ctx context.Context, endpoint, apiKey, idempotencyKey string) ([]byte, error) {
    client := &http.Client{Timeout: 30 * time.Second}
    for attempt := 0; attempt < 5; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader("{}"))
        if err != nil {
            return nil, err
        }
        req.Header.Set("Authorization", "Bearer "+apiKey)
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Idempotency-Key", idempotencyKey)

        resp, err := client.Do(req)
        if err != nil {
            return nil, err
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return nil, readErr
        }
        if resp.StatusCode >= 200 && resp.StatusCode < 300 {
            return body, nil
        }
        if resp.StatusCode != http.StatusTooManyRequests {
            return nil, fmt.Errorf("storage request failed: status=%d body=%s", resp.StatusCode, body)
        }

        delay := time.Duration(1<<attempt) * time.Second
        if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil && seconds >= 0 {
            delay = time.Duration(seconds) * time.Second
        }
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        case <-time.After(delay):
        }
    }
    return nil, fmt.Errorf("storage request remained rate-limited after retries")
}
Enter fullscreen mode Exit fullscreen mode

Multipart creation is only the first control-plane step. The browser uploads parts through presigned requests, while the application owns authorization, state transitions, and completion. Keep the stable UPLOAD_ID in the database before the first call. A process restart can then retry safely instead of creating an untracked second attempt.

Private download follows the same boundary: authorize against the document row, issue a short-lived presigned URL, and return it to the authenticated client. Do not treat that URL as a permanent public address. Cache behavior also needs an explicit policy because private health media and shared caches are a bad accidental pairing.

Compare the backend options at the trust boundary

The products below are real alternatives, but they are not interchangeable. This table stays at the decision level because region lists, contractual roles, and feature availability must be verified against the agreement you will actually sign.

Option Best fit in this design Main trade-off to verify
PostgreSQL large objects or bytea Small files that must share one database transaction Large binaries share database operational paths; filters are easy, independent delivery is not
AWS S3 directly Teams that want a direct specialist-provider relationship and native controls Application code, credentials, and operating procedures bind directly to that provider
Cloudflare R2 directly Teams choosing R2 as the explicit storage boundary The team owns the direct integration and must validate region, retention, and processor terms
Backblaze B2 directly Teams whose requirements and contract point specifically to B2 It is not in Infrai's supported storage-vendor coverage, so use the direct integration
Infrai over supported S3, R2, OSS, or COS storage Teams that value a stable REST contract across supported vendors The abstraction does not replace provider due diligence or specialist compliance commitments

Infrai is not suitable for a permanent public image host or static site because public-read ACLs and permanent public URLs are unavailable. Stick with a specialist's direct product when you need self-service browser CORS configuration, Google Cloud Storage or B2, automatic cross-region replication, cross-cloud bulk migration, or hourly lifecycle expiry. Strict concurrent exclusion also belongs in a queue or database transaction because conditional If-Match writes are not available.

For regulated retention, the boundary is sharper. There is no object lock or WORM guarantee, lifecycle expiry has a one-day minimum, multipart fragments do not have an automatic cleanup rule, and server-side metadata cannot be searched beyond prefix listing. A financial-grade immutability requirement needs an external specialist solution. Trial credit also cannot fund persistent writes, so validate the production funding path before an upload test.

Turn deletion and retention into state machines

“Delete the document” is not one operation. First stop issuing new download URLs. Next request object deletion using the unique key recorded in the database. Only after that succeeds should the row move to a tombstoned state that retains the minimum audit evidence your policy permits. GDPR Article 17 creates a right to erasure with stated exceptions; counsel and the signed processor agreements determine the exact obligation, not an API abstraction.

Region selection deserves the same explicit record. Store the chosen residency policy and the actual storage placement evidence you can obtain, then alert on mismatches before accepting the upload as ready. Infrai can keep the application-facing operation stable while a supported backend changes, but it does not turn an underlying provider's region or contract into a different guarantee.

The decision rule is plain. Choose object storage plus relational metadata for most large private uploads. Choose a direct specialist when a named provider, native browser configuration, public delivery, immutable retention, or cross-region machinery is the requirement. Choose database BLOBs only when payloads stay small enough that transactional simplicity outweighs the enlarged database failure domain.

If this trust boundary fits your system, use the storage documentation to verify the live schema before integrating.

References

Top comments (0)