Skip to main content

Step 1: Create Your App

  1. Go to dashboard.onchaindb.io
  2. Create a new App to get your appId
  3. Navigate to the “Security” tab to generate your appKey

Step 2: Install the SDK

npm install @onchaindb/sdk
# or
yarn add @onchaindb/sdk

Step 3: Initialize the Client

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

const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'your-app-id',
  appKey: 'your-app-key'
});

Step 4: Create Indexes

Creating indexes automatically creates the collections and sets up the data structure.
Indexes are Required for Production UseYou MUST create at least one index per collection before storing data. Without indexes:
  • Queries will be extremely slow (full collection scans)
  • The OnchainDB dashboard cannot display your collections
  • Your application will run in an unoptimized state
const db = client.database('your-app-id');

// Create indexes - this also creates the collections
await db.createIndex({
  name: 'idx_users_email',
  collection: 'users',
  field_name: 'email',
  index_type: 'hash',
  options: { unique: true }
});

await db.createIndex({
  name: 'idx_users_createdAt',
  collection: 'users',
  field_name: 'createdAt',
  index_type: 'btree'
});

Step 5: Store Data

const result = await client.store({
  collection: 'users',
  data: [{
    email: 'alice@example.com',
    name: 'Alice',
    createdAt: new Date().toISOString()
  }]
});

console.log('Stored at block:', result.block_height);

Step 6: Query Data

// Simple query
const users = await client.query({
  collection: 'users',
  limit: 10
});

console.log(`Found ${users.total} users`);

// Using Query Builder
const activeUsers = await client.queryBuilder()
  .collection('users')
  .whereField('status').equals('active')
  .orderBy('createdAt', 'desc')
  .limit(10)
  .execute();

That’s It!

You now have a fully functional onchain database with indexed queries, automatic transaction management, and blockchain-backed data storage.

SDK Feature Comparison

FeatureTypeScriptGoPHPPython
Query BuilderYesYesYesYes
Server-side JOINsYesYesYesYes
AggregationsYesYesYesYes
Blob StorageYesYesYesYes
Auto-Pay (userKey)YesYesYesYes
Collection SchemasYesYesYesYes
Materialized ViewsYesYesYesYes
Task PollingYesYesYesYes
Context SupportN/AYesN/AN/A

Next Steps