> For the complete documentation index, see [llms.txt](https://bucketdb.sullux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bucketdb.sullux.com/getting-started/quick-start.md).

# Quick Start

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

## 1. Installation

Assuming you are deploying via NPM or Yarn:

```bash
npm install @sullux/bucketdb
```

```bash
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.

```javascript
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.

```javascript
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*](/core-concepts/cluster.md) *for details.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bucketdb.sullux.com/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.