Merge pull request #98 from InsForge/feat/database-schema-selection

feat(database): custom schema selection via .schema()

Author: Fermionic-Lyu

README.md

@@ -185,6 +185,31 @@ const { data, error } = await insforge.database
   .eq("id", postId);
 ```
 
+#### Selecting a schema
+
+Queries hit the `public` schema by default. Target a custom schema by chaining `.schema()` — the table name stays bare (it maps to PostgREST's `Accept-Profile`/`Content-Profile` header):
+
+```javascript
+const { data } = await insforge.database
+  .schema("analytics")
+  .from("events")
+  .select("*");
+
+await insforge.database.schema("analytics").rpc("rollup", { day: "2026-01-01" });
+```
+
+Or set a default schema for every query when creating the client:
+
+```javascript
+const insforge = createClient({
+  baseUrl: "...",
+  anonKey: "...",
+  db: { schema: "analytics" },
+});
+```
+
+The schema must be exposed by the backend, and access is still gated by grants + RLS like `public`. Older backends that don't expose the schema return PostgREST `PGRST106` rather than silently falling back.
+
 ### File Storage
 
 ```javascript

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@insforge/sdk",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Official JavaScript/TypeScript client for InsForge Backend-as-a-Service platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package.json

@@ -83,7 +83,7 @@ export class InsForgeClient {
       isServerMode: config.isServerMode ?? !!accessToken,
       detectOAuthCallback: config.auth?.detectOAuthCallback,
     });
-    this.database = new Database(this.http);
+    this.database = new Database(this.http, config.db?.schema);
     this.storage = new Storage(this.http);
     this.ai = new AI(this.http);
     this.functions = new Functions(this.http, config.functionsUrl);

src/client.ts

@@ -15,6 +15,7 @@ function makeDatabase(
   fetchFn: ReturnType<typeof vi.fn>,
   overrides: Record<string, unknown> = {},
   accessToken: string | null = 'old-token',
+  defaultSchema?: string,
 ) {
   const tokenManager = new TokenManager();
   if (accessToken) {
@@ -34,7 +35,7 @@ function makeDatabase(
   http.setAuthToken(accessToken);
 
   return {
-    database: new Database(http),
+    database: new Database(http, defaultSchema),
     tokenManager,
   };
 }
@@ -147,6 +148,48 @@ describe('Database PostgREST auth refresh', () => {
     expect(fetchFn).toHaveBeenCalledOnce();
   });
 
+  it('sends Accept-Profile when a schema is selected on a read', async () => {
+    const fetchFn = vi.fn().mockResolvedValueOnce(jsonResponse(200, [{ id: 1 }]));
+    const { database } = makeDatabase(fetchFn);
+
+    await database.schema('analytics').from('events').select('id');
+
+    const [url, init] = fetchFn.mock.calls[0];
+    expect(url).toBe('http://localhost:7130/api/database/records/events?select=id');
+    expect(new Headers(init.headers).get('Accept-Profile')).toBe('analytics');
+  });
+
+  it('sends Content-Profile when a schema is selected on a write', async () => {
+    const fetchFn = vi.fn().mockResolvedValueOnce(jsonResponse(201, [{ id: 1 }]));
+    const { database } = makeDatabase(fetchFn);
+
+    await database.schema('analytics').from('events').insert({ name: 'signup' });
+
+    const [, init] = fetchFn.mock.calls[0];
+    expect(new Headers(init.headers).get('Content-Profile')).toBe('analytics');
+  });
+
+  it('sends the schema profile header for rpc calls', async () => {
+    const fetchFn = vi.fn().mockResolvedValueOnce(jsonResponse(200, [{ ok: true }]));
+    const { database } = makeDatabase(fetchFn);
+
+    await database.schema('analytics').rpc('rollup', { day: '2026-01-01' });
+
+    const [url, init] = fetchFn.mock.calls[0];
+    expect(url).toBe('http://localhost:7130/api/database/rpc/rollup');
+    expect(new Headers(init.headers).get('Content-Profile')).toBe('analytics');
+  });
+
+  it('applies a default schema from config to every query', async () => {
+    const fetchFn = vi.fn().mockResolvedValueOnce(jsonResponse(200, [{ id: 1 }]));
+    const { database } = makeDatabase(fetchFn, {}, 'old-token', 'analytics');
+
+    await database.from('events').select('id');
+
+    const [, init] = fetchFn.mock.calls[0];
+    expect(new Headers(init.headers).get('Accept-Profile')).toBe('analytics');
+  });
+
   it('does not refresh database requests in server mode', async () => {
     const fetchFn = vi.fn().mockResolvedValueOnce(
       jsonResponse(

src/modules/__tests__/database-postgrest.test.ts

@@ -51,14 +51,35 @@ function createInsForgePostgrestFetch(httpClient: HttpClient): typeof fetch {
 export class Database {
   private postgrest: PostgrestClient<any, any, any>;
 
-  constructor(httpClient: HttpClient) {
-    // Create postgrest client with custom fetch
+  constructor(httpClient: HttpClient, defaultSchema?: string) {
+    // Create postgrest client with custom fetch. `schema` sets the default
+    // profile; postgrest-js attaches Accept-Profile/Content-Profile headers,
+    // which the InsForge data API resolves to the target schema.
     this.postgrest = new PostgrestClient<any, any, any>('http://dummy', {
       fetch: createInsForgePostgrestFetch(httpClient),
       headers: {},
+      ...(defaultSchema ? { schema: defaultSchema } : {}),
     });
   }
 
+  /**
+   * Select a non-default Postgres schema for the chained query. Maps to
+   * PostgREST's `Accept-Profile` (reads) / `Content-Profile` (writes) header.
+   * The schema must be exposed by the backend.
+   *
+   * @example
+   * const { data } = await client.database
+   *   .schema('analytics')
+   *   .from('events')
+   *   .select('*');
+   *
+   * @example
+   * await client.database.schema('analytics').rpc('rollup', { day: '2026-01-01' });
+   */
+  schema(schemaName: string) {
+    return this.postgrest.schema(schemaName);
+  }
+
   /**
    * Create a query builder for a table
    *

src/modules/database-postgrest.ts

@@ -71,6 +71,19 @@ export interface InsForgeConfig {
     detectOAuthCallback?: boolean;
   };
 
+  /**
+   * Database module options.
+   */
+  db?: {
+    /**
+     * Default Postgres schema for database queries. Maps to PostgREST's
+     * `Accept-Profile`/`Content-Profile` headers. Override per-query with
+     * `client.database.schema('other')`.
+     * @default "public"
+     */
+    schema?: string;
+  };
+
   /**
    * Custom headers to include with every request
    */