Schema Definition

In BucketDB, schemas serve a very specific, limited purpose: to instruct the storage engine on how to efficiently serialize your JavaScript objects into packed binary rows.

BucketDB adheres to the philosophy that data validation (e.g., ensuring a string matches an email regex, or an integer falls within a specific range) belongs in your application's business logic layer. Thus, BucketDB schemas do not reject writes based on constraint validation.

Defining a Schema

You must register a schema before you can write to or query a table. A schema definition consists of the table name, a version number, an object of fields, a primary key designation, and optionally an array of indexes.

Basic Example

db.registerSchema({
  name: 'users',
  version: 1,  // Increment to perform migrations
  fields: {
    id: { typeId: 10, maxLength: 36 }, // varchar
    name: { typeId: 10, maxLength: 50 }, // varchar
    active: { typeId: 6 }, // boolean
    age: { typeId: 1 } // uint8
  },
  primaryKey: 'id',
  indexes: ['name']
});

Supported Data Types

When a row is written, its fields are serialized into a fixed-width binary block according to these types. BucketDB uses integer type IDs to compress schemas.

Type ID	Type	Description	Max Value / Size
`1`	`uint8`	Unsigned 8-bit integer	0 to 255
`2`	`uint32`	Unsigned 32-bit integer	0 to 4,294,967,295
`3`	`uint64`	Unsigned 64-bit integer	0 to 18,446,744,073,709,551,615
`4`	`int32`	Signed 32-bit integer	-2,147,483,648 to 2,147,483,647
`5`	`float64`	Double precision float	Standard JS Number
`6`	`boolean`	Boolean	`true` or `false`
`7`	`timestamp`	UTC Unix timestamp	Milliseconds
`10`	`varchar`	Variable-length UTF-8 text	Stored in the Heap. Requires `maxLength` config.
`11`	`blob`	Managed Unstructured Blob	Stored in the Heap as a 36-char UUID pointer
`12`	`json`	Arbitrary nested objects/arrays	Stored in the Heap

The Heap (Variable Length Data)

To ensure the primary data block remains fixed-width (allowing instantaneous seeking by multiplying row index by byte width), types like varchar and json are not stored directly in the row. Instead, the row stores a pointer (offset and length) to a secondary section of the block called the Heap.

Primary Keys

You must explicitly designate a primaryKey field.

It must be unique per table.
Most commonly, this is a varchar (e.g., a UUID or KSUID).
You must always provide this field when calling batch.insert(), batch.update(), or batch.delete().

Index Design

Queries in BucketDB without an index require a full table scan, meaning the system must download every single data block for that table and scan it in memory.

By defining indexes, you instruct BucketDB to maintain Copy-on-Write (CoW) B+Tree files natively in the storage driver.

Defining Indexes

Indexes are defined as an array of field names. B+Tree indexes natively support exact equality matches (=) as well as range queries (>, >=, <, <=). See Querying for performance implications.

Schema Versioning

Because blocks are immutable, schemas in BucketDB are permanently tied to the blocks they create. You cannot modify a registered schema version. Instead, you create a new version (e.g., version: 2) and initiate a zero-downtime background migration via the Storage-Level Migration Daemon.

See Schema Migrations for the complete guide on modifying schemas safely.