@kokolabs-io/db

Pod-scoped SQLite database API for Koko with a Supabase-style query builder interface.

Features

• Fluent Query Builder: Chainable API for building SQL queries
• CRUD Operations: Full support for select, insert, update, and delete
• Filter Operators: eq, ne, gt, gte, lt, lte, like
• Pagination: limit, offset, and range methods
• Database Management: attach/detach databases
• Type-Safe: Full TypeScript support with generic types
• Dual Mode: Works in both native and remote environments

Installation

pnpm add @kokolabs-io/db

Usage

Basic Queries

import { db } from '@kokolabs-io/db';

// Select all records
const { data, error } = await db.from('users').select('*');

// Select with filter
const result = await db.from('users')
  .select('id, name, email')
  .eq('status', 'active')
  .limit(10);

// Single record
const user = await db.from('users')
  .select('*')
  .eq('id', 123)
  .single();

Insert

// Insert single record
const { data, error } = await db.from('users').insert({
  name: 'John Doe',
  email: '[email protected]'
});

// Insert multiple records
await db.from('users').insert([
  { name: 'Alice', email: '[email protected]' },
  { name: 'Bob', email: '[email protected]' }
]);

Update

const { data, error } = await db.from('users')
  .update({ status: 'inactive' })
  .eq('last_login', null);

Delete

await db.from('users')
  .delete()
  .lt('created_at', '2025-01-01');

Filter Operators

// Equality
.eq('status', 'active')
.ne('role', 'guest')

// Comparison
.gt('age', 18)
.gte('score', 100)
.lt('price', 50)
.lte('quantity', 10)

// Pattern matching
.like('email', '%@example.com')

Pagination

// Limit and offset
await db.from('posts')
  .select('*')
  .limit(20)
  .offset(40);

// Range (inclusive)
await db.from('posts')
  .select('*')
  .range(0, 19); // First 20 records

Raw SQL

// Execute raw SQL
const result = await db.sql(
  'SELECT * FROM users WHERE age > ?',
  [18]
);

Database Attachment

// Attach another database
await db.attach('/path/to/other.db', 'other_db');

// Query from attached database
await db.from('other_db.table_name').select('*');

// Detach database
await db.detach('other_db');

Custom Client

import { createClient } from '@kokolabs-io/db';

const customDb = createClient({
  apiUrl: 'https://api.example.com',
  apiKey: 'your-api-key',
  dbId: 'your-db-id',
  preferRecords: true
});

API Reference

QueryBuilder Methods

• select(columns?: string) - Select columns
• insert(data) - Insert records
• update(data) - Update records
• delete() - Delete records
• eq(col, value) - Equal to
• ne(col, value) - Not equal to
• gt(col, value) - Greater than
• gte(col, value) - Greater than or equal
• lt(col, value) - Less than
• lte(col, value) - Less than or equal
• like(col, value) - Pattern match
• limit(n) - Limit results
• offset(n) - Skip results
• range(from, to) - Paginate with range
• single() - Return single record
• maybeSingle() - Return single or null

Result Format

interface DbResult<T> {
  data: T | null;
  error: unknown | null;
  count?: number | null;
  meta?: unknown;
}

Build

Build from root:

pnpm -C .. build

Build this package only:

pnpm --filter @kokolabs-io/db build

License

MIT - Copyright (c) 2026 KokoLabs.io