Best Practices

Authentication

Use App Key Auth

Use appKey for writes. Use agentKey for autonomous agent operations. Never expose keys in client-side code.

// Server-side
const client = createClient({
  endpoint: process.env.ONDB_ENDPOINT,
  appId: process.env.ONDB_APP_ID,
  appKey: process.env.ONDB_APP_KEY
});

Indexes

Create Indexes FirstYou MUST create at least one index per collection. Without indexes, queries perform full collection scans and the dashboard cannot display collections. Create indexes BEFORE storing data.

// Always create indexes before storing data
const db = client.database('my-app');

await db.createIndex({
  name: 'idx_users_email',
  collection: 'users',
  field_name: 'email',
  index_type: 'hash',
  unique_constraint: true,
  store_values: true
});

// Index fields you'll query
await db.createIndex({
  name: 'idx_users_createdAt',
  collection: 'users',
  field_name: 'createdAt',
  index_type: 'btree'
});

// Now store data
await client.store({ collection: 'users', data: [...] });

Payment Handling

Handle Payment Callbacks

Implement payment callbacks for store operations. Handle PaymentRequiredError for read operations.

// Write operations - server provides quote, caller handles USDC payment
await client.store(
  { collection: 'data', data },
  async (quote) => {
    const txHash = await processPayment(quote);
    return { txHash, network: quote.network, sender: walletAddress, chainType: quote.chainType, paymentMethod: 'native' };
  },
  true
);

// Read operations
try {
  const result = await client.queryBuilder()
    .collection('premium_data')
    .execute();
} catch (error) {
  if (error instanceof PaymentRequiredError) {
    // Handle payment flow
    const paymentInfo = error.paymentRequired;
    // ...
  }
}

Error Handling

Use Specific Error Types

Always implement proper error handling with specific error types.

import {
  ValidationError,
  TransactionError,
  PaymentRequiredError,
  OnDBError
} from '@ondb/sdk';

try {
  await client.store(data, paymentCallback);
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation errors
  } else if (error instanceof TransactionError) {
    // Handle transaction failures
  } else if (error instanceof PaymentRequiredError) {
    // Handle payment flow
  } else if (error instanceof OnDBError) {
    // Handle other SDK errors
  }
}

Query Optimization

Use Query Builder for All Queries

Use the QueryBuilder fluent API for all read operations.

// Simple queries
const user = await client.queryBuilder()
  .collection('users')
  .whereField('email').equals('alice@example.com')
  .executeUnique();

// Complex queries
const results = await client.queryBuilder()
  .collection('orders')
  .whereField('status').equals('completed')
  .whereField('createdAt').greaterThanOrEqual(new Date(new Date().getFullYear(), new Date().getMonth(), 1).toISOString())
  .joinOne('customer', 'users')
    .onField('id').equals('$data.customerId')
    .selectFields(['name', 'email'])
    .build()
  .selectAll()
  .limit(50)
  .execute();

Async Operations

Use Task Tickets for Long Operations

Use task tickets for long-running operations and monitor progress.

// Non-blocking store
const response = await client.store(data, paymentCallback, false);

// Monitor progress
const status = await client.getTaskStatus(response.ticket_id);

// Or wait for completion
const task = await client.waitForTaskCompletion(response.ticket_id);

Cost Awareness

Inspect Costs via Payment Callback

The payment callback receives a quote with full cost details before you authorize payment.

await client.store(
  { collection: 'users', data },
  async (quote) => {
    if (quote.totalCost > maxBudget) {
      throw new Error(`Operation costs ${quote.totalCost} ${quote.tokenSymbol}, exceeds budget`);
    }
    const txHash = await processPayment(quote);
    return { txHash, network: quote.network, sender: walletAddress, chainType: quote.chainType, paymentMethod: 'native' };
  },
  true
);

PriceIndex for Commerce

Use PriceIndex for Revenue Sharing

Use PriceIndex when building commerce platforms, ticketing systems, or apps with revenue sharing.

// Create PriceIndex on payment field
await db.createIndex({
  name: 'idx_orders_total',
  collection: 'orders',
  field_name: 'totalPrice',
  index_type: 'price'
});

// Payment = field value, not storage cost
await client.store(
  { collection: 'orders', data: [{ totalPrice: 100000000, items: [...] }] },
  paymentCallback,
  true
);

TypeScript

Leverage Type Safety

Use TypeScript for full type safety and better development experience.

interface User {
  id: string;
  email: string;
  name: string;
  createdAt: string;
}

const user = await client.queryBuilder()
  .collection('users')
  .whereField('email').equals('alice@example.com')
  .executeUnique<User>();
// user is User | null with full IntelliSense

const users = await client.queryBuilder()
  .collection('users')
  .whereField('active').isTrue()
  .execute<User>();
// users.records is User[]

Batch Operations

Use Batches for Bulk Data

Use batch operations for large datasets to improve efficiency.

// Store multiple records in a single call
await client.store(
  { collection: 'products', data: products },
  paymentCallback,
  true
);

// For large datasets, chunk into batches
const BATCH_SIZE = 100;
for (let i = 0; i < products.length; i += BATCH_SIZE) {
  const chunk = products.slice(i, i + BATCH_SIZE);
  await client.store({ collection: 'products', data: chunk }, paymentCallback, true);
  console.log(`${Math.min(i + BATCH_SIZE, products.length)}/${products.length}`);
}

Transaction Monitoring

Monitor Transactions in Real-Time

Use event listeners to track transaction status in real-time.

client.on('transaction:queued', (ticket) => {
  console.log(`Task ${ticket.ticket_id} queued`);
});

client.on('transaction:confirmed', (tx) => {
  console.log(`Confirmed at block ${tx.block_height}`);
});

client.on('transaction:failed', (tx) => {
  console.error(`Failed: ${tx.error}`);
});

Checklist

Create indexes before storing data
Use environment variables for keys
Implement payment callbacks
Handle all error types
Use TypeScript for type safety
Get cost estimates before operations
Monitor transactions with events
Use batch operations for bulk data
Consider PriceIndex for commerce apps

Reference

Changelog

Authentication

Use App Key Auth

Indexes

Payment Handling

Handle Payment Callbacks

Error Handling

Use Specific Error Types

Query Optimization

Use Query Builder for All Queries

Async Operations

Use Task Tickets for Long Operations

Cost Awareness

Inspect Costs via Payment Callback

PriceIndex for Commerce

Use PriceIndex for Revenue Sharing

TypeScript

Leverage Type Safety

Batch Operations

Use Batches for Bulk Data

Transaction Monitoring

Monitor Transactions in Real-Time

Checklist

​Authentication

Use App Key Auth

​Indexes

​Payment Handling

Handle Payment Callbacks

​Error Handling

Use Specific Error Types

​Query Optimization

Use Query Builder for All Queries

​Async Operations

Use Task Tickets for Long Operations

​Cost Awareness

Inspect Costs via Payment Callback

​PriceIndex for Commerce

Use PriceIndex for Revenue Sharing

​TypeScript

Leverage Type Safety

​Batch Operations

Use Batches for Bulk Data

​Transaction Monitoring

Monitor Transactions in Real-Time

​Checklist

Authentication

Indexes

Payment Handling

Error Handling

Query Optimization

Async Operations

Cost Awareness

PriceIndex for Commerce

TypeScript

Batch Operations

Transaction Monitoring

Checklist