SoliDB Docs

Lua Scripting

Build server-side logic, real-time apps, and secure APIs directly within SoliDB.

Overview

SoliDB embeds a high-performance Lua 5.1 (LuaJIT) engine, allowing you to run custom code closer to your data. Scripts are stored in the database, can be updated at runtime, and serve as custom HTTP endpoints or background workers.

Use Cases

  • ✓ Custom REST APIs & Webhooks
  • ✓ Complex Transactional Logic
  • ✓ Real-time WebSocket Apps
  • ✓ Data Validation & Triggers

Key Features

  • ⚡ Zero-latency database access
  • 🔐 Sandboxed & Secure execution
  • 📦 Built-in crypto, json, and http libs
  • 🔄 ACID Transactions support
Explore the Documentation: Use the sidebar to navigate through the different sections of the Lua Scripting API, from Core functions to Database access and WebSockets.

Security Model

Your scripts run in a restricted sandbox.

Allowed

  • ✓ Standard Lua 5.1 Libraries (string, table, math, etc)
  • ✓ SoliDB APIs (db, solidb, request, response)
  • ✓ Safe helpers (json, crypto, time)

Blocked

  • ✕ OS access (os.*, io.*, debug.*)
  • ✕ File system access (except via solidb APIs)
  • ✕ Creating excessive threads or consuming all memory

Scripts are subject to execution time limits (default 5s) and memory limits (default 64MB) to prevent destabilizing the server.

Authentication & Authorization

Scripts have access to the current authenticated user via the solidb.auth namespace. Use these functions to implement role-based access control.

  • solidb.auth.user() -> table
    Returns current user info: { username, roles, authenticated, scoped_databases, exp }
  • solidb.auth.require_role(role) -> true | error
    Guard that throws 401/403 error if user doesn't have the role.

Example: Protected Endpoint

-- 1. Ensure caller is authenticated
solidb.auth.require_auth() 

-- 2. Check for specific role
solidb.auth.require_role("editor")

local user = solidb.auth.user()
return { status = "authorized", user = user.username }