Quick Start

This guide will walk you through a complete, minimal setup of BucketDB.

1. Installation

Assuming you are deploying via NPM or Yarn:

npm install @sullux/bucketdb

yarn add @sullux/bucketdb

2. Setting Up a Local Memory Database

For local development or testing, you can use the MemoryDriver to avoid configuring AWS credentials or running MinIO/Localstack.

const { BucketDb } = require('bucket-db');
const { MemoryDriver } = require('bucket-db/lib/storage');

async function main() {
  // Step 1: Create the database
  const db = BucketDb({
    dbPrefix: 'dev_db',
    nodeId: 0,
    driver: MemoryDriver()
  })

  // Start the database lifecycle
  await db.start()

  // Step 2: Register a Schema
  db.registerSchema({

    name: 'users',
    version: 1, // Must be an integer
    fields: {
      id: { typeId: 10, maxLength: 36 }, // varchar (Primary Key)
      name: { typeId: 10, maxLength: 50 }, // varchar
      age: { typeId: 1 } // uint8
    },
    primaryKey: 'id',
    indexes: ['name']
  })

  // Step 3: Write Data using a Batch
  const batch = db.batch()
  batch.insert('users', { id: 'user_1', name: 'Alice', age: 28 })
  batch.insert('users', { id: 'user_2', name: 'Bob', age: 34 })
  await batch.flush() 
  
  // NOTE: The flush() writes to the Write-Forward log.
  // The background daemon will pick this up and write immutable data blocks.

  // Step 4: Query Data
  const results = await db.query('users')
    .where('name', '=', 'Alice')
    .execute()

  console.log(results)
  // Output: [ { id: 'user_1', name: 'Alice', age: 28 } ]

  // Stop the database lifecycle
  await db.stop()
}

main().catch(console.error);

3. Production Deployment with S3

When moving to production, you will remove the MemoryDriver override and provide a custom S3 storage driver.

const { BucketDb } = require('bucket-db');
const { S3Driver } = require('bucket-db/lib/storage');

const driver = S3Driver({
  bucket: process.env.DB_BUCKET_NAME,
  region: process.env.DB_REGION,
  credentials: {
    accessKeyId: process.env.DB_ACCESS_KEY,
    secretAccessKey: process.env.DB_SECRET_KEY
  }
});

const db = BucketDb({
  dbPrefix: 'production',
  nodeId: parseInt(process.env.NODE_ID, 10), // e.g. 0, 1, 2 depending on the container
  driver
});

// Ensure you call await db.start() before any operations
// and await db.stop() when shutting down your application.

Note: In a multi-node deployment, you must coordinate nodeId. See Cluster Operations for details.