Storage

PaperDB storage lets you upload, manage, and serve files from your database. Files are accessible via public URLs or time-limited signed URLs for private access.

Uploading Files

Upload a single file from a browser input or Node.js Blob.

const file = document.getElementById('file-input').files[0];

const result = await db.storage.upload(file, {
  folder: "avatars",
  isPublic: true,
  metadata: { userId: "user_123" }
});

console.log("File uploaded to:", result.url);

Upload Multiple Files

const results = await db.storage.uploadMany([file1, file2, file3], {
  folder: "gallery",
  isPublic: true
});

Upload From URL

Fetch a remote file and store it directly in PaperDB.

const file = await db.storage.uploadFromUrl(
  "https://example.com/sample-image.png",
  { folder: "imports" }
);

Listing Files

const { files, total, hasMore } = await db.storage.list({
  folder: "avatars",
  limit: 10,
  offset: 0,
  sortBy: "createdAt",   // "createdAt" | "name" | "size"
  sortOrder: "desc"      // "asc" | "desc"
});

Get File Metadata

// By ID
const file = await db.storage.get("file_123");

// By storage path
const fileByPath = await db.storage.getByPath("avatars/abc123.png");

Move and Copy Files

Move a file to a different folder or rename it. Copy creates a new file record at the destination path.

// Move to a different folder
const moved = await db.storage.move("file_123", {
  folder: "archive",
  name: "old-avatar.png"   // optional rename
});

// Copy to a new location
const copy = await db.storage.copy("file_123", {
  folder: "backups"
});

Delete Files

// Delete single file
await db.storage.delete("file_123");

// Delete multiple files
await db.storage.deleteMany(["file_123", "file_456"]);

Signed URLs

Generate a temporary signed URL for private file access. The URL expires after the specified duration.

const { url, expiresAt } = await db.storage.getSignedUrl("file_123", {
  expiresIn: 3600 // seconds — default 1 hour
});

Image URL with Transform Parameters

getImageUrl() appends resize and format parameters to the file URL. Image transformation is handled by your CDN — PaperDB passes the parameters through.

const url = db.storage.getImageUrl(file, {
  width: 400,
  height: 400,
  fit: "cover",
  format: "webp"
});
// → https://your-cdn.com/path/to/file?w=400&h=400&fit=cover&f=webp

Folders

Folders are virtual — they are derived from the folder field on each file. You can create, list, and delete them.

// Create a folder (idempotent — safe to call multiple times)
await db.storage.createFolder("invoices/2024");

// List folders under a parent path
const folders = await db.storage.listFolders("invoices");

// Delete a folder and all files within it
const { deleted } = await db.storage.deleteFolder("invoices/old");

deleteFolder() permanently deletes all files inside the folder from both the database and the storage backend. This cannot be undone.

← Cron Jobs Search →