InsForge SDK provides a type-safe, developer-friendly interface to your PostgreSQL database with full PostgREST compatibility. 
npm install @insforge/sdk

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

const insforge = createClient({
  baseUrl: 'https://your-app.us-east.insforge.app'
});

​
Basic Operations

The SDK uses a Supabase-like query builder that feels natural to JavaScript developers:

​
Querying Data

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

​
Inserting Data

const { data, error } = await insforge.database
  .from('products')
  .insert({ 
    name: 'Widget', 
    price: 19.99, 
    in_stock: true 
  })
  .select()

​
Updating Data

const { data, error } = await insforge.database
  .from('products')
  .update({ price: 24.99, on_sale: true })
  .eq('id', '123')
  .select()

​
Deleting Data

const { data, error } = await insforge.database
  .from('products')
  .delete()
  .eq('id', '123')
  .select()

​
Advanced Filtering

The SDK supports all PostgREST operators through chainable methods: 
// Comparison operators
.eq('column', value)        // Equals
.neq('column', value)       // Not equals
.gt('column', value)        // Greater than
.gte('column', value)       // Greater than or equal
.lt('column', value)        // Less than
.lte('column', value)       // Less than or equal

// Pattern matching
.like('name', '%Widget%')   // Case-sensitive pattern
.ilike('name', '%widget%')  // Case-insensitive pattern

// Array/NULL checks
.in('status', ['active', 'pending'])
.is('deleted_at', null)

// Logical operators
.or('status.eq.active,status.eq.pending')
.not('archived', 'is.true')

​
Complex Queries

// Products on sale OR highly rated
const { data, error } = await insforge.database
  .from('products')
  .select()
  .eq('category', 'electronics')
  .or('on_sale.eq.true,rating.gte.4.5')
  .order('price', { ascending: true })

​
Relationships & Joins

The SDK supports PostgREST’s powerful join syntax: 
// Join with related data
const { data, error } = await insforge.database
  .from('posts')
  .select('*, users(*)')  // Include all user data

​
Counting & Pagination

Get total counts alongside your data: 
// Get data with exact count
const { data, count, error } = await insforge.database
  .from('products')
  .select('*', { count: 'exact' })
  .eq('in_stock', true)
  .range(0, 9)  // First 10 items

console.log(`Showing ${data.length} of ${count} products`)

​
Error Handling

The SDK provides structured error responses: 
const { data, error } = await insforge.database
  .from('products')
  .insert({ name: 'Widget' })
  .select()

if (error) {
  console.error('Database error:', {
    code: error.code,      // PostgreSQL/PostgREST error code
    message: error.message,
    details: error.details,
    hint: error.hint
  })
}

​
Data Types

The SDK validates data types but does NOT automatically convert JavaScript types. You must provide correctly formatted values:
JavaScript InputPostgreSQL TypeRequired Format
stringTEXTAny string value
numberINTEGERWhole numbers only (-2147483648 to 2147483647)
numberDOUBLE PRECISIONFloating point numbers
booleanBOOLEANtrue or false
stringDATE'YYYY-MM-DD' format
stringTIMESTAMPTZISO 8601 format (e.g., '2024-01-15T10:30:00Z')
stringUUIDValid UUID format
object/arrayJSONBJSON-serializable objects/arrays
nullNULLnull value
Important:
  • Dates must be provided as ISO 8601 strings, not JavaScript Date objects
  • Empty strings are converted to null for non-text types
  • The backend uses TEXT (not VARCHAR) for all string columns
  • All timestamps are stored with timezone (TIMESTAMPTZ)

​
System Tables

Access system tables (read-only for user data): 
// Read user profiles
const { data: users, error } = await insforge.database
  .from('users')
  .select('id, nickname, avatar_url')

// Join with user data
const { data: posts, error } = await insforge.database
  .from('posts')
  .select('*, users(nickname, avatar_url)')
To modify user data, use the auth methods like insforge.auth.setProfile(). The system restricts each user to only update their own data - users cannot delete their own records or modify other users’ data.

​
Best Practices

Handle Errors

Always check the error object from every operation

Use Select

Add .select() to INSERT/UPDATE/DELETE to get affected records

Batch Operations

Insert multiple records in one call when possible

Optimize Queries

Select only needed columns to reduce payload size
The SDK handles authentication tokens, request formatting, and response parsing automatically.