Files & Media

Upload files, store blobs, and process images directly in Lua.

File Handling

Files are stored using SoliDB's blob storage in the _files collection, providing durability, replication, and easy backup.

File Operations

Upload, read, and manage files. Files are identified by their unique key (UUID).

solidb.upload(data, options?) -> table
Upload file from base64 data. Options: { filename, directory }
Returns: { key, path, filename, size, mime_type, chunks, width?, height? }
solidb.file_info(key) -> table
Get file metadata by key: { _key, _id, path, size, filename, mime_type, created_at, chunks, width?, height? }
solidb.file_read(key) -> string (base64)
Read file contents as base64-encoded string by file key.
solidb.file_delete(key) -> boolean
Delete a file and its blob chunks. Returns true if deleted, false if not found.
solidb.file_list(options?) -> array
List files. Options: { directory, limit, offset }
Returns array of { _key, _id, path, filename, size, mime_type, chunks, directory? }

Image Processing

Transform images with resize, crop, rotate, and more.

solidb.image_process(data, operations) -> table
Process an image with the specified operations. Input can be base64 string or file key (UUID).

Operations:
- resize: { width, height } - Resize image (aspect ratio preserved if only one dimension)
- thumbnail: { width, height } - Create thumbnail fitting within bounds
- crop: { x, y, width, height } - Crop region
- rotate: 90 | 180 | 270 - Rotate clockwise
- flip: "horizontal" | "vertical" - Flip image
- grayscale: true - Convert to grayscale
- blur: float - Apply Gaussian blur (sigma value)
- brightness: -100 to 100 - Adjust brightness
- contrast: -100 to 100 - Adjust contrast
- format: "jpeg" | "png" | "webp" - Output format
- quality: 1-100 - JPEG quality (default: 85)
Returns: { data (base64), size, width, height, format, mime_type }

Examples

Example: File Upload Endpoint

-- Upload file from request body (stored in _files blob collection)
local file_data = request.body.file -- base64 encoded
local filename = request.body.filename

local result = solidb.upload(file_data, {
  filename = filename,
  directory = "user_uploads"
})

-- Store file reference in your collection (key is stored in _files)
db:insert("user_files", {
  file_key = result.key, -- UUID key for blob storage
  path = result.path,
  size = result.size,
  mime_type = result.mime_type,
  uploaded_at = solidb.now()
})

return result

Example: Image Thumbnail Generation

-- Create thumbnail from uploaded image
local image_data = request.body.image

local thumb = solidb.image_process(image_data, {
  thumbnail = { width = 200, height = 200 },
  format = "webp",
  quality = 80
})

-- Save thumbnail
local saved = solidb.upload(thumb.data, {
  filename = "thumb_" .. request.body.name .. ".webp",
  directory = "thumbnails"
})

return {
  thumbnail = saved.path,
  width = thumb.width,
  height = thumb.height,
  size = thumb.size
}