8000 GitHub - janwilmake/dorm: Unlimited SQLite DBs Directly In Your Worker - OSS Turso Alternative
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

janwilmake/dorm

Repository files navigation

πŸ›οΈ DORM - Unlimited SQLite DBs Directly In Your Worker

janwilmake/dorm context

DORM makes building multi-tenant applications on Cloudflare ridiculously easy by letting you:

  1. Create unlimited SQLite DBs on the fly (up to 10GB each)
  2. Query them directly from anywhere in your worker (not just inside DOs)
  3. Explore and manage your data with built-in Outerbase integration
  4. Migrate once, everywhere with built-in JIT migration-support

Perfect for SaaS applications, user profiles, rate limiting, or any case where you need isolated data stores that are lightning fast at the edge.

Demo app: https://dorm.wilmake.com | Give me a like/share on X

⚑ Key Benefits vs Alternatives

Feature Vanilla DOs DORM πŸ›οΈ D1 Turso
Multi-tenant βœ… Unlimited βœ… Unlimited ❌ One DB Pricey
Run code where your DB is
(Never >1 round-trip)
βœ… βœ… ❌ ❌
Query from worker ❌ Only in DO βœ… βœ… βœ…
Data Explorer ❌ βœ… Outerbase βœ… βœ…
Migrations ❌ βœ… βœ… βœ…
Edge Performance Closest to user Closest to user Global edge Global edge
Developer Experience ❌ Verbose, complex βœ… Clean, low verbosity βœ… Good Good, not CF native

See Turso vs DORM and DORM vs D1 for a more in-depth comparison with these alternatives. Also, see the pricing comparison here

πŸš€ Quick Start

Check out the live demo showing multi-tenant capabilities.

npm i dormroom@next

DORM is built atop of modular primitives called 'Power Objects'. Check https://itscooldo.com for more information!

Summary Prompt it
Working example/template on how to use this
Entire implementation of the package
Create a customized guide for a particular usecase
General information

View your data with Outerbase Studio:

Local Development:

  1. Install: https://github.com/outerbase/studio
  2. Create starbase connecting to: http://localhost:8787/{tenant}/api/db (or your port, your prefix)

Production: Use https://studio.outerbase.com

πŸ”₯ Top Use Cases

1. Multi-tenant SaaS applications

Create a separate database for each customer/organization:

const client = createClient({
  doNamespace: env.DORM_NAMESPACE,
  ctx: ctx,
  configs: [
    { name: `tenant:${tenantId}` }, // One DB per tenant
    { name: "aggregate" }, // Optional: Mirror to aggregate DB
  ],
});

2. Global user profiles with edge latency

Store user data closest to where they access it:

const client = createClient({
  doNamespace: env.DORM_NAMESPACE,
  ctx: ctx,
  configs: [
    { name: `user:${userId}` }, // One DB per user
  ],
});

3. Data aggregation with mirroring

Mirror tenant operations to a central database for analytics:

const client = createClient({
  doNamespace: env.DORM_NAMESPACE,
  ctx: ctx,
  configs: [
    { name: `tenant:${tenantId}` }, // Main DB
    { name: "aggregate" }, // Mirror operations to aggregate DB
  ],
});

When creating mirrors, be wary of naming collisions and database size:

  • Auto increment drift: when you use auto-increment and unique IDs (or columns in general), you may run into the issue that the value will be different in the aggregate DB. This causes things to drift apart! To prevent this issue I recommend not using auto increment or random in the query, and generate unique IDs beforehand when doing a query, so the data remains the same.

  • Size: You have max 10GB. When you chose to use an aggregate DB of some sort, ensure to keep this in mind.

✨ Key Features

  • Direct SQL anywhere: No need to write DO handler code - query from your worker
  • Outerbase integration: Explore and manage your data with built-in tools
  • JSON Schema support: Define tables using JSON Schema with automatic SQL translation
  • Streaming queries: Efficient cursor implementation for large result sets
  • JIT Migrations: Migrations are applied when needed, just once, right before a DO gets accessed (via @Migratable)
  • Data mirroring: Mirror operations to aggregate databases for analytics
  • Low verbosity: Clean API that hides Durable Object complexity

πŸ› οΈ Advanced Features

Setting up your Durable Object with Migrations

import { Migratable } from "migratable-object";
import { Streamable } from "remote-sql-cursor";

@Migratable({
  migrations: {
    1: [`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`],
    2: [`ALTER TABLE users ADD COLUMN email TEXT`],
  },
})
@Streamable()
export class DORM extends DurableObject {
  sql: SqlStorage;

  constructor(state: DurableObjectState, env: any) {
    super(state, env);
    this.sql = state.storage.sql;
  }

  getDatabaseSize() {
    return this.sql.databaseSize;
  }
}

JSONSchema to SQL Conversion

import { jsonSchemaToSql, TableSchema } from "dormroom";

const userSchema: TableSchema = {
  $id: "users",
  properties: {
    id: { type: "string", "x-dorm-primary-key": true },
    name: { type: "string", maxLength: 100 },
    email: { type: "string", "x-dorm-unique": true },
  },
  required: ["id", "name"],
};

const sqlStatements = jsonSchemaToSql(userSchema);

Streaming Query Results

// Get a cursor for working with large datasets
const cursor = client.exec<UserRecord>("SELECT * FROM users");

// Stream results without loading everything into memory
for await (const user of cursor) {
  // Process each user individually
}

// Or get all results at once
const allUsers = await cursor.toArray();

REST API for Data Access

// Access your database via REST API
const middlewareResponse = await client.middleware(request, {
  prefix: "/api/db",
  secret: "my-secret-key",
});

if (middlewareResponse) {
  return middlewareResponse;
}

Extending DORM

You can extend DORM with your own DO implementation to circumvent limitations doing single queries remotely gives you.

@Migratable({
  migrations: {
    1: [`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`],
  },
})
@Streamable()
export class YourDO extends DurableObject {
  sql: SqlStorage;

  constructor(state: DurableObjectState, env: any) {
    super(state, env);
    this.sql = state.storage.sql;
  }

  async myExtendedFunction() {
    // Multiple queries in one transaction
    const users = await this.sql.exec("SELECT * FROM users").toArray();
    const count = await this.sql
      .exec("SELECT COUNT(*) as count FROM users")
      .one();
    return { users, count };
  }

  getDatabaseSize() {
    return this.sql.databaseSize;
  }
}

This allows:

  • Doing a multitude of SQL queries inside of your DO from a single API call
  • Using alarms and other features
  • Complex transactions

πŸ“Š Performance & Limitations

  • βœ… Nearly zero overhead: Thin abstraction over DO's SQLite
  • βœ… Edge-localized: Data stored closest to where it's accessed
  • βœ… Up to 10GB per DB: Sufficient for most application needs
  • ❓ Localhost isn't easily accessible YET in https://studio.outerbase.com so you need to deploy first, use a tunnel, or run the outerbase client on localhost.

πŸ”— Links & Resources

🚧 Status: Beta

DORM is currently in beta. API may change!

Deploy to Cloudflare Workers

About

Unlimited SQLite DBs Directly In Your Worker - OSS Turso Alternative

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published
0