gdb() - Database Initialization

Initialize a GenosDB instance with configuration options

Overview

The gdb() function is an async factory function that creates and configures a GenosDB database connection. It serves as the entry point for all GenosDB operations.

Signature

await gdb(name: string, options?: DatabaseOptions): Promise<GDB>

Parameters

name · string · required

Database name used for local storage and P2P synchronization.

options · object

Configuration options for the database instance.

Show options properties

rtc · boolean | object

Enables real-time P2P networking and relay connections. Pass true for defaults or an object to customize:

Show rtc configuration

relayUrls · string[]

Custom list of secure WebSocket relay URLs for Nostr peer discovery.

turnConfig · Array<object>

Configuration for TURN servers:

• urls: Single string or array of TURN server URLs
• username: Authentication username
• credential: Authentication password

cells · boolean | object

Enable Cellular Mesh overlay for massive scalability. Pass true for defaults or configure:

• cellSize: "auto" or fixed number (default: "auto")
• bridgesPerEdge: Redundancy between cells (default: 2)
• maxCellSize: Upper limit per cell (default: 50)
• targetCells: Target number of cells (default: 100)
• debug: Enable debug logging (default: false)

sm · object

Enables and configures the Security Manager for RBAC, ACLs, and identity management.

Show sm configuration

superAdmins · string[] · required

Array of authorized Ethereum addresses with superadmin privileges. Mandatory when enabling SM.

customRoles · object

Custom role definitions with permissions and inheritance.

acls · boolean

Enable Access Control Lists for node-level permissions (default: false).

ai · boolean

Load the AI module for enhanced functionality.

nlq · boolean

Load the Natural Language Query module for prompt-based queries.

rx · boolean

Load the Radix Index module for prefix-based searches.

ii · boolean

Load the Inverted Index module for full-text search.

geo · boolean

Load the Geo module for spatial queries ($near, $bbox operators).

audit · boolean | object

Load the Audit module for content policy enforcement.

Show audit configuration

prompt · string

Custom audit policy prompt (e.g., “detect offensive or inappropriate language”).

password · string

Optional encryption key for securing database content.

saveDelay · number · default: 200

Debounce delay in milliseconds for saving to persistent storage. Higher values reduce disk I/O but increase data loss risk on crashes.

oplogSize · number · default: 20

Maximum number of recent operations in the operation log for delta-based P2P synchronization. Larger values enable efficient sync after longer disconnections but consume more memory.

Return Value

db · GDB

A configured GenosDB instance ready for data operations.

Examples

Basic Initialization

import { gdb } from "genosdb"

const db = await gdb("my-db")

With Password Encryption

const secureDb = await gdb("secure-db", { 
  password: "secret" 
})

Enable P2P Networking

const db = await gdb("my-db", { 
  rtc: true 
})

Custom Relay Configuration

const db = await gdb("my-db", {
  rtc: {
    relayUrls: ["wss://relay1.example.com", "wss://relay2.example.com"]
  }
})

TURN Server Configuration

const db = await gdb("my-db", {
  rtc: {
    turnConfig: [
      {
        urls: ["turn:your-turn-server.ok:1979"],
        username: "username",
        credential: "password"
      }
    ]
  }
})

Cellular Mesh for Massive Scale

// Default cellular mesh
const db = await gdb("my-db", {
  rtc: { cells: true }
})

// Custom cellular configuration
const db = await gdb("my-db", {
  rtc: {
    cells: {
      cellSize: "auto",
      bridgesPerEdge: 2,
      maxCellSize: 50,
      targetCells: 100,
      debug: false
    }
  }
})

Enable Security Manager

const db = await gdb("my-db", {
  rtc: true, // Required for SM
  sm: {
    superAdmins: ["0x1234...", "0x5678..."]
  }
})

Enable Multiple Modules

const db = await gdb("my-db", {
  rtc: true,
  nlq: true,  // Natural Language Queries
  rx: true,   // Radix Index
  geo: true,  // Geo-spatial queries
  audit: { 
    prompt: "detect offensive or inappropriate language" 
  }
})

Performance Tuning

const db = await gdb("my-db", {
  saveDelay: 500,   // Reduce disk writes
  oplogSize: 100    // Support longer offline periods
})

Best Practices

Use top-level await in modern environments (<script type="module">) to avoid unnecessary async function wrappers:

// ✅ Recommended
import { gdb } from "genosdb"
const db = await gdb("my-app")

// ❌ Avoid unless needed for user actions
async function init() {
  const db = await gdb("my-app")
}

When enabling the Security Manager, rtc: true is required as SM relies on the Real-Time Communication module for cryptographic signing and verification of P2P operations.

Related Methods

• put() - Insert or update nodes
• get() - Retrieve nodes
• map() - Query with filters
• Security Manager - RBAC and identity management