Storage

What it is

nodabase.storage is object storage for your application: upload a file, download it, check whether it exists, delete it. Nodabase uses S3-compatible object storage backed by MinIO underneath, and the client speaks the standard S3 protocol to it.

Files live under keys in one configured bucket — avatars/me.png, reports/2026.csv — so a whole application's objects are organized by key inside that bucket.

How it works

Node.js application
       |
       v
nodabase.storage
       |
       v
     MinIO
(S3-compatible)

Every call goes to the configured S3 endpoint with the configured credentials. Because the protocol is standard S3, the same bucket can be reached with any S3-compatible tool, not just this client.

Configuration

Five variables configure the module:

env
NODABASE_STORAGE_ENDPOINT=http://localhost:9000
NODABASE_STORAGE_REGION=us-east-1
NODABASE_STORAGE_ACCESS_KEY=your-access-key
NODABASE_STORAGE_SECRET_KEY=your-secret-key
NODABASE_STORAGE_BUCKET=my-app

NODABASE_STORAGE_ENDPOINT and NODABASE_STORAGE_BUCKET are required — without an endpoint, nodabase.storage is not created. The region defaults to us-east-1. When your application runs inside the Nodabase platform, all five bindings are provided for you.

Basic usage

js
import { nodabase } from "nodabase";
 
await nodabase.storage.createBucket(); // ignore the error if it already exists
 
const result = await nodabase.storage.upload("avatars/me.png", buffer, {
contentType: "image/png",
});
 
// { key: "avatars/me.png", bucket: "my-app" }

The body is a Buffer, string or readable stream — anything an S3 put accepts. upload resolves to the key and bucket it wrote to.

Common operations

The whole surface at a glance:

MethodReturnsNotes
createBucket()truecreates the configured bucket; errors if it exists
upload(key, body, { contentType }){ key, bucket }contentType is optional
download(key)readable streampipe it — not a Buffer
exists(key)true / false
delete(key)true

Downloading

js
const body = await nodabase.storage.download("avatars/me.png");
 
body.pipe(res);

download resolves to a readable stream, not a buffer. Pipe it to a response or a file, or consume it with your stream tooling of choice.

Checking and deleting

js
await nodabase.storage.exists("avatars/me.png"); // true or false
 
await nodabase.storage.delete("avatars/me.png"); // true

exists answers with a head request, so a false means no object under that key — there are no folders, only keys.

Important notes

  • createBucket() fails if the bucket already exists — that is normal; call it once during setup and ignore the error if it comes back.
  • The client exposes these five operations and no more. There is no presigned-URL API, no object listing and no copy in the client — S3-compatible tooling can talk to the same bucket directly when you need more.
  • download returning a stream is the part people trip on: awaiting a Buffer does not happen automatically.
  • Without NODABASE_STORAGE_ENDPOINT, nodabase.storage is absent from the client — the same pattern as db and cache.

Next steps

  • Cache — Redis-compatible caching through Dragonfly
  • Queues — publishing and consuming through NATS
  • Overview — how the client and the services fit together
  • Quickstart — run the platform