Skip to main content
npm install @insforge/sdk@latest

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.us-east.insforge.app',
  anonKey: 'your-anon-key'  // Optional: for public/unauthenticated requests
});

​
insert()

Insert new records into a table.

​
Parameters

  • values (object | Array, required) - Data to insert. Single object or array for bulk insert
  • options.count (‘exact’ | ‘planned’ | ‘estimated’, optional) - Include count of inserted rows

​
Returns

{
  data: Array<object> | null,
  error: Error | null,
  count?: number
}
Chain .select() after .insert() to return the inserted data

​
Examples

const { data, error } = await insforge.database
  .from('users')
  .insert({ name: 'John', email: 'john@example.com' })
  .select()

​
Output Example

{
  "data": [
    { "id": "789", "name": "John", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z" }
  ],
  "error": null
}

​
update()

Update existing records in a table. Must use filters to target specific rows.

​
Parameters

  • values (object, required) - Fields to update
  • options.count (‘exact’ | ‘planned’ | ‘estimated’, optional) - Include count of updated rows

​
Returns

{
  data: Array<object> | null,
  error: Error | null,
  count?: number
}
Always use filters like .eq() or .in() to specify which rows to update

​
Examples

const { data, error } = await insforge.database
  .from('users')
  .update({ name: 'Jane Doe' })
  .eq('id', userId)
  .select()

​
Output Example

{
  "data": [
    { "id": "123", "name": "Jane Doe", "email": "john@example.com", "updated_at": "2024-01-15T11:00:00Z" }
  ],
  "error": null
}

​
delete()

Delete records from a table. Must use filters to target specific rows.

​
Parameters

  • options.count (‘exact’ | ‘planned’ | ‘estimated’, optional) - Include count of deleted rows

​
Returns

{
  data: Array<object> | null,
  error: Error | null,
  count?: number
}
Always use filters to specify which rows to delete

​
Examples

const { error } = await insforge.database
  .from('posts')
  .delete()
  .eq('id', postId)

​
Output Example

{
  "data": null,
  "error": null
}

​
select()

Query records from a table or view.

​
Parameters

  • columns (string, optional) - Comma-separated column names. Use * for all columns
  • options.count (‘exact’ | ‘planned’ | ‘estimated’, optional) - Include total row count
  • options.head (boolean, optional) - Return only count, no data

​
Returns

{
  data: Array<object> | null,
  error: Error | null,
  count?: number
}

​
Examples

const { data, error } = await insforge.database
  .from('users')
  .select()

​
Output Example

{
  "data": [
    { "id": "123", "name": "John", "email": "john@example.com" },
    { "id": "456", "name": "Jane", "email": "jane@example.com" }
  ],
  "error": null
}

​
Filters

Chain filters to narrow down query results. All filters take (column, value) as parameters.
FilterDescriptionExample
.eq(column, value)Equals.eq('status', 'active')
.neq(column, value)Not equals.neq('status', 'banned')
.gt(column, value)Greater than.gt('age', 18)
.gte(column, value)Greater than or equal.gte('price', 100)
.lt(column, value)Less than.lt('stock', 10)
.lte(column, value)Less than or equal.lte('priority', 3)
.like(column, pattern)Case-sensitive pattern (use % wildcard).like('name', '%Widget%')
.ilike(column, pattern)Case-insensitive pattern (use % wildcard).ilike('email', '%@gmail.com')
.in(column, array)Value in array.in('status', ['pending', 'active'])
.is(column, value)Exactly equals (for null checks).is('deleted_at', null)
// Example: Chain multiple filters
const { data } = await insforge.database
  .from('products')
  .select()
  .eq('category', 'electronics')
  .gte('price', 50)
  .lte('price', 500)
  .is('in_stock', true)

​
Modifiers

Control how query results are returned.
ModifierDescriptionExample
.order(column, options)Sort results. Options: { ascending: true/false, nullsFirst: true/false }.order('created_at', { ascending: false })
.limit(count)Limit number of rows.limit(10)
.range(from, to)Get rows between indices (pagination).range(0, 9)
.single()Return object instead of array (throws if multiple).single()
.maybeSingle()Return object or null (no error).maybeSingle()
// Example: Pagination with sorting
const { data } = await insforge.database
  .from('posts')
  .select()
  .order('created_at', { ascending: false })
  .range(0, 9)
  .limit(10)

​
Common Patterns

​
Pagination with Count

const page = 1;
const pageSize = 10;
const from = (page - 1) * pageSize;
const to = from + pageSize - 1;

const { data, count } = await insforge.database
  .from('posts')
  .select('*', { count: 'exact' })
  .range(from, to)
  .order('created_at', { ascending: false })

console.log(`Page ${page}: ${data.length} of ${count} total`)
Output: 
{
  "data": [
    { "id": "1", "title": "Post 1", "created_at": "2024-01-15T10:00:00Z" },
    { "id": "2", "title": "Post 2", "created_at": "2024-01-14T10:00:00Z" }
  ],
  "count": 50,
  "error": null
}

const { data } = await insforge.database
  .from('products')
  .select('id, name, price, category')
  .eq('category', 'electronics')
  .gte('price', 50)
  .lte('price', 500)
  .order('price', { ascending: true })
  .limit(20)
Output: 
{
  "data": [
    { "id": "101", "name": "USB Cable", "price": 59.99, "category": "electronics" },
    { "id": "102", "name": "Keyboard", "price": 89.99, "category": "electronics" }
  ],
  "error": null
}

​
Using with Authentication Hooks

Combine database queries with useUser() or useAuth() hooks to fetch user-specific data: 
import { useUser } from '@insforge/react'; // or '@insforge/react-router'
import { insforge } from './lib/insforge';
import { useEffect, useState } from 'react';

function MyProfile() {
  const { user, isLoaded } = useUser();
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    if (user) {
      // Fetch user's posts from database
      insforge.database
        .from('posts')
        .select('*')
        .eq('user_id', user.id)
        .then(({ data }) => setPosts(data));
    }
  }, [user]);

  if (!isLoaded) return <div>Loading...</div>;
  if (!user) return <div>Not signed in</div>;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <h2>My Posts: {posts.length}</h2>
      {posts.map(post => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  );
}
Key points:
  • Use user.id to filter data for the authenticated user
  • Check isLoaded before accessing user to avoid race conditions
  • Check !user to handle unauthenticated state