Merge branch 'main' of https://github.com/objectstack-ai/framework

Author: hotlong

content/docs/guides/driver-configuration.mdx

@@ -182,6 +182,33 @@ new InMemoryDriver();
 Use the memory driver for unit tests. It requires no setup and runs instantly.
 </Callout>
 
+## `apps/objectos` and Single-Project Local Mode
+
+When running `apps/objectos` (or any boot stack with `runtime: { cloudUrl: 'local' }`),
+two databases are involved:
+
+| DB           | Purpose                                                   | Env var                         |
+|--------------|-----------------------------------------------------------|---------------------------------|
+| Project DB   | Your business data (the records served at `/api/v1/data/*`) | `OS_DATABASE_URL` / `OS_DATABASE_DRIVER` |
+| Control DB   | Framework bookkeeping (`sys_organization`, `sys_project`, …) | `OS_CONTROL_DATABASE_URL`       |
+
+Both honor the same URL-scheme inference described above. If
+`OS_CONTROL_DATABASE_URL` is unset, the control DB defaults to a local
+SQLite file (`<dataDir>/control.db`); for backward compatibility
+`OS_DATABASE_URL` is also accepted as a fallback for the control DB
+when no explicit `OS_CONTROL_DATABASE_URL` is provided **and** no project DB
+URL has consumed it.
+
+```bash
+# Run apps/objectos with MongoDB as the project DB (control DB stays sqlite):
+OS_DATABASE_URL=mongodb://localhost:27017/objectos pnpm dev
+
+# Pin both DBs explicitly:
+OS_DATABASE_URL=mongodb://localhost:27017/objectos \
+OS_CONTROL_DATABASE_URL=postgres://user:pass@host/control \
+pnpm dev
+```
+
 ## Multi-Datasource
 
 ObjectStack supports multiple data sources. Objects can target specific datasources:

packages/services/service-cloud/src/cloud-stack.ts

@@ -81,9 +81,20 @@ export async function createCloudStack(config: CloudStackConfig): Promise<{
         apiPrefix,
     } = config;
 
+    // Resolve the control-plane DB URL.
+    // Priority:
+    //   1. OS_CONTROL_DATABASE_URL  (explicit, dedicated to the control plane)
+    //   2. controlDriverUrl         (explicit param from the calling stack)
+    //   3. OS_DATABASE_URL          (legacy alias — only used here when no
+    //                                higher-priority source is set; reserved
+    //                                going forward for the project's data DB)
+    //   4. TURSO_DATABASE_URL       (legacy alias)
+    //   5. file:./.objectstack/data/control.db (default)
+    const explicitControlUrl = process.env.OS_CONTROL_DATABASE_URL?.trim();
+    const legacyControlUrl = (process.env.OS_DATABASE_URL || process.env.TURSO_DATABASE_URL)?.trim();
     const controlDriverPromise = buildControlDriver(
-        (process.env.OS_DATABASE_URL || process.env.TURSO_DATABASE_URL)?.trim() || controlDriverUrl,
-        process.env.OS_DATABASE_AUTH_TOKEN || process.env.TURSO_AUTH_TOKEN || controlDriverAuthToken,
+        explicitControlUrl || controlDriverUrl || legacyControlUrl || `file:${resolvePath(process.cwd(), '.objectstack/data/control.db')}`,
+        process.env.OS_CONTROL_DATABASE_AUTH_TOKEN || process.env.OS_DATABASE_AUTH_TOKEN || process.env.TURSO_AUTH_TOKEN || controlDriverAuthToken,
     );
 
     // Default base plugins (per-project kernel — business data only).

packages/services/service-cloud/src/runtime-stack.ts

@@ -34,6 +34,29 @@ import { resolveAuthSecret, resolveBaseUrl } from './boot-env.js';
 import type { AppBundleResolver } from './project-kernel-factory.js';
 import { createObjectOSStack } from './objectos-stack.js';
 
+/**
+ * Infer the storage driver type from a database connection-URL scheme.
+ * Returns `''` if the URL is empty or the scheme is unrecognised.
+ *
+ *   mongodb://, mongodb+srv://         → 'mongodb'
+ *   postgres://, postgresql://         → 'postgres'
+ *   mysql://, mysql2://                → 'mysql'
+ *   libsql://, https://*.turso.*       → 'turso'
+ *   file:, sqlite:, :memory:, *.db,
+ *   *.sqlite, *.sqlite3                → 'sqlite'
+ */
+function inferDriverFromUrl(url: string | undefined): string {
+    if (!url) return '';
+    const u = url.trim();
+    if (/^mongodb(\+srv)?:\/\//i.test(u)) return 'mongodb';
+    if (/^postgres(ql)?:\/\//i.test(u)) return 'postgres';
+    if (/^mysql2?:\/\//i.test(u)) return 'mysql';
+    if (/^libsql:\/\//i.test(u)) return 'turso';
+    if (/^https?:\/\//i.test(u) && /\.turso\./i.test(u)) return 'turso';
+    if (/^file:/i.test(u) || /^sqlite:/i.test(u) || u === ':memory:' || /\.(db|sqlite|sqlite3)$/i.test(u)) return 'sqlite';
+    return '';
+}
+
 /**
  * Default ObjectStack Cloud base URL — the local `apps/cloud` instance
  * running on port 4000. Override via `OS_CLOUD_URL` (or
@@ -124,8 +147,22 @@ export async function createRuntimeStack(config?: RuntimeStackConfig): Promise<R
     const dataDir = cfg.dataDir ?? resolvePath(cwd, '.objectstack/data');
     mkdirSync(dataDir, { recursive: true });
 
-    const controlDbUrl = `file:${resolvePath(dataDir, 'control.db')}`;
-    const projectDbUrl = `file:${resolvePath(dataDir, `${projectId}.db`)}`;
+    // Control-plane DB. In single-project local mode this is the framework's
+    // bookkeeping DB (sys_organization / sys_project / …). It defaults to a
+    // local SQLite file. Users can override with `OS_CONTROL_DATABASE_URL`
+    // (preferred); `OS_DATABASE_URL` is reserved for the *project's* data.
+    const controlDbUrl = process.env.OS_CONTROL_DATABASE_URL?.trim()
+        || `file:${resolvePath(dataDir, 'control.db')}`;
+
+    // Project DB. This is the user's business-data DB. When `OS_DATABASE_URL`
+    // is set, honour it (and infer the driver from its scheme unless
+    // `OS_DATABASE_DRIVER` overrides). Otherwise fall back to a local
+    // SQLite file beside `control.db`.
+    const envProjectDbUrl = process.env.OS_DATABASE_URL?.trim();
+    const projectDbUrl = envProjectDbUrl || `file:${resolvePath(dataDir, `${projectId}.db`)}`;
+    const projectDbDriver = (process.env.OS_DATABASE_DRIVER?.trim().toLowerCase())
+        || inferDriverFromUrl(projectDbUrl)
+        || 'sqlite';
 
     const authSecret = cfg.authSecret ?? resolveAuthSecret();
     const baseUrl = cfg.baseUrl ?? resolveBaseUrl();
@@ -176,7 +213,7 @@ export async function createRuntimeStack(config?: RuntimeStackConfig): Promise<R
         createSingleProjectPlugin({
             projectId,
             projectDatabaseUrl: projectDbUrl,
-            projectDatabaseDriver: 'sqlite',
+            projectDatabaseDriver: projectDbDriver,
             apiPrefix: cfg.apiPrefix,
         }),
     );