RageDB - Titan ORM Extension

RageDB is the Most Secure & Fast Database Extension for TitanPl servers. It bridges the gap between Titan's synchronous runtime and asynchronous database drivers, providing a seamless "synchronous-like" developer experience using Titan's internal drift mechanism.

Features

• Most Secure: Built-in parameterization and strict path validation for queries.
• Fastest Performance: Leverages native Rust bindings and zero-cost abstractions.
• Multi-Driver Support: Compatible with PostgreSQL, MySQL, SQLite, and MongoDB.
• Titan-Native DX: Methods block the current fiber but not the server thread, enabling await-free syntax.
• Type-Safe: Complete TypeScript definitions.
• Scaffold Ready: Pre-configured structure for immediate use.

Installation

Ensure you have the Titan runtime installed. This extension is typically part of a Titan project workspace.

npm install @titanpl/ragedb

Quick Start

RageDB connects to your database and executes queries synchronously from your perspective, handling the async complexity internally.

1. Connecting to the Database

Initialize the connection at the start of your action or in a global initialization script.

import { rageDb } from "@titanpl/ragedb";

export default function (req) {
    // Establish connection (blocks fiber until connected)
    rageDb.connect({
        type: "postgres",
        url: process.env.DB_URI || "postgresql://user:pass@localhost:5432/db",
        poolSize: 10
    });
    
    t.log("Connected to database!");

    // Your app logic...
}

2. Executing Queries

Execute SQL queries directly. The result is returned as a plain JavaScript array (or object for single row logic if you implement it), ready to use.

/* eslint-disable no-undef */
// Simple Query
const users = rageDb.query("SELECT * FROM users LIMIT 5");
t.log("Users:", users); // [{ id: 1, name: "Alice" }, ...]

// Parameterized Query (prevents SQL injection)
const user = rageDb.query("SELECT * FROM users WHERE id = $1", [1]);

3. Running Query Files

Keep your code clean by storing complex SQL in .sql files.

// Executes content of /queries/get_active_users.sql
const activeUsers = rageDb.query("queries/get_active_users.sql");

How It Works (The "Magic")

You might wonder why you don't need await or drift() despite database operations being asynchronous.

RageDB uses Titan's Fiber System. When you call rageDb.query(...):

1. The request is sent to the native Rust layer.
2. The JS execution checks the task status.
3. If pending, it calls drift({ type: 'sleep', ... }) internally.
4. This suspends the current request fiber, allowing the Titan server to handle other requests.
5. Once the database responds, the fiber resumes exactly where it left off.

This gives you the simplicity of synchronous code (PHP/Python style) with the performance of asynchronous Node.js.

Configuration

| Option | Type | Description | |--------|------|-------------| | type | string | Database type: postgres, mysql, sqlite, mongo | | url | string | Connection string URL | | poolSize | number | (Optional) Max connections in pool. Default: cpu * 2 | | ssl | boolean | (Optional) Enable SSL. Default: false | | logQueries | boolean | (Optional) Log all SQL to stdout. Default: false |

API Reference

rageDb.connect(config)

Initializes the global connection pool. Blocks until connection is established.

rageDb.query(sql, params?)

Executes a query and returns the rows/documents. Blocks until result is ready.

• Returns: Array<any> (default)

rageDb.collection(name)

Returns a MongoDB-style collection helper for find, insert, update, delete.