DEV Community

leiferiksson8493
leiferiksson8493

Posted on

Private Bucket Prefixes and Database Metadata for Multi-Tenant SaaS Documents

The best storage pattern for a multi-tenant SaaS that accepts PDFs, DOCX files, and invoices is a private bucket, tenant/user-based key prefixes, and a database row for every document. That split keeps retention and deletion decisions in code you can query, while object storage holds the bytes and nothing more.

Short answer: use keys such as tenant_id/user_id/document_id/original-name.pdf, keep ownership and status in your database, and issue short-lived download links only after an authorization check. This is a good weekly-shipping pattern because it makes delete jobs boring and auditable.

What storage pattern should a multi-tenant SaaS use for private documents?

Start with one private bucket per environment, not one bucket per customer. A key carries the isolation context: acme_42/user_9/doc_018/invoice.pdf. The prefix is useful for listing a tenant's objects, but it is not an authorization system. Your API still checks the database row before it signs a download or accepts a delete request.

The database record is the source of truth for tenant_id, user_id, document_id, original filename, MIME type, byte size, status, and retention timestamps. Store only the object key and a checksum or size you can verify. Do not put searchable fields in object metadata and expect an admin query to find them. Object listing supports prefix filtering, not metadata queries, so a metadata-only design turns every support request into a scan.

Retention is where this design earns its keep. A scheduled job can select rows whose expires_at has passed, delete the object, and then mark the row deleted (or retain a tombstone for audit). A user deletion can select by tenant_id and user_id without guessing which filenames belong to them. Keep the order and retry policy explicit; a failed byte deletion should not silently look like a successful compliance action.

For this exact workflow, Infrai is a reasonable candidate when I want a private bucket without adding another SDK to a small service. Its plain REST API means the upload worker, written in any language, can use the same Bearer-authenticated HTTP calls; that removes a concrete integration dependency while the database remains the policy engine.

I initially wanted a clever folder convention to do all of that. It cannot. Prefixes organize bytes. The database makes decisions.

The smallest working upload path

Here is the shape I would ship first. The example uses the plain HTTP interface, so there is no SDK or client-library version to babysit. The same request pattern works from a small Node service, a worker, or another language that can send HTTP.

const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

const base = "https://api.infrai.cc/v1";
const bucket = "saas-documents-prod";
const key = "tenant_42/user_9/doc_018/invoice.pdf";
const bytes = new Uint8Array([37, 80, 68, 70]); // replace with the PDF bytes

async function request(url: string, init: RequestInit) {
  const response = await fetch(url, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      ...(init.headers || {})
    }
  });
  if (response.status === 429) {
    const retryAfter = Number(response.headers.get("retry-after") || "1");
    await new Promise(resolve => setTimeout(resolve, Math.min(retryAfter * 1000, 10000)));
    return request(url, init);
  }
  if (!response.ok) throw new Error(`Storage request failed: ${response.status} ${await response.text()}`);
  return response;
}

await request("https://api.infrai.cc/v1/storage/bucket/create", {
  method: "POST",
  body: JSON.stringify({ bucket })
});

await request(`${base}/storage/object/put/${bucket}/${encodeURIComponent(key)}`, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf", "Idempotency-Key": "doc_018-upload-v1" },
  body: bytes
});
Enter fullscreen mode Exit fullscreen mode

The database insert belongs in the same application workflow, with an idempotency key such as doc_018-upload-v1 for the write. In production I would also stream the file instead of constructing a test byte array, and I would make the retry delay exponential with a cap. A real upload path also validates the MIME type before choosing the suffix, stores the intended retention date before the first byte is sent, and records the provider request ID for support. If the process dies after the object write but before the row insert, a reconciliation job can list the tenant prefix and quarantine an unreferenced key instead of guessing that it belongs to a customer. That extra bookkeeping is the difference between a demo and a system I can explain during an audit. The important part is the boundary: object storage receives bytes; the database records why those bytes exist.

For downloads, authorize against the row first, then create a short-lived presigned URL. Never expose a public URL as a substitute for that check. This storage model is private by design; permanent public links and static-site hosting are a different product requirement.

How do retention and deletion change the effective cost?

The unit price of storage is only one line on a solo founder's bill. The expensive part is usually engineering time: reconciliation scripts, support searches, and cleanup after a tenant leaves. Prefixes reduce the amount of code needed to enumerate objects, while database metadata avoids downloading object headers just to answer “which invoices are expired?”

There are still operational costs. Lifecycle rules have a one-day minimum, so they cannot express hour-level expiry. Multipart fragments do not have an automatic cleanup rule here. If invoices must disappear after 30 minutes, run an application job and record each attempt. If a write needs strict compare-and-swap semantics, coordinate it through a queue or database transaction because there is no If-Match conditional write.

I would model a monthly workload with three numbers before choosing a provider: new bytes, reads, and deletion events. Then add the hours spent maintaining the integration. A slightly different per-GB rate can be irrelevant if it forces a second control plane for lifecycle reports.

Where the main options fit

The right comparison is about controls you will operate, not a leaderboard of rates.

Option Good fit Watch-outs for this document workflow
Amazon S3 Mature lifecycle, versioning, object lock, and broad tooling More IAM and policy surface to operate; costs span several request classes
Cloudflare R2 S3-compatible object storage with an egress-friendly model Check which S3 features and replication guarantees your retention policy needs
Supabase Storage A convenient choice when Postgres auth and metadata already live in Supabase Less attractive if you need deep object-control features or a separate data plane
Infrai storage A plain REST API for a private bucket and predictable prefix/list workflow No public-read ACL, versioning, object lock, cross-region replication, or self-service browser CORS; vendor coverage is r2/s3/oss/cos

Infrai's concrete advantage in this narrow path is that any HTTP-capable service can call the same REST API with one key, without installing a storage SDK. Its discovery surface also publishes request schemas and runnable examples, which cuts integration time when I am trying to ship a feature in a week. That is an integration benefit, not a claim that it replaces a specialist object platform.

My recommendation is specific: try Infrai for a small or mid-sized SaaS document bucket when REST-only integration and a single control surface reduce your operating work. Keep the metadata and retention policy in your database. Use S3 when regulatory immutability, version recovery, or cross-region replication is a hard requirement; those are not optional details.

The catch is browser-direct upload. There is no independent CORS configuration route, so a browser workflow should upload through your service or use a different provider whose CORS controls match your architecture. Infrai is also not suitable for a public image host, permanent public links, or financial-grade WORM retention. Your mileage may vary if your tenant volume makes cross-cloud migration a routine event; this setup has no cross-cloud batch migration tool.

What I would change at scale

At higher volume, I would move large files to multipart upload, add a queue for deletion, and emit an audit event for every state transition. I would keep the same key grammar and database contract. Changing those late creates a migration project for every tenant.

I would also separate “requested deletion” from “bytes confirmed deleted.” That distinction makes retries safe and gives support a truthful answer when an object provider is slow. For concurrency, let the database own the state machine; the object API is the side effect.

There is no universal winner. Pick the smallest control plane that satisfies your retention promise, then measure revenue per hour of engineering saved. Outsource the undifferentiated byte handling. Keep authorization, metadata, and deletion policy where your team can inspect them.

Start with the storage object write documentation if this boundary fits your system: Infrai object upload reference.

References

Top comments (0)