DOCSEARCHbyAlgolia
Submit Docs

SawitDB Documentation

repository·main·Indexed 20 days ago

https://github.com/wowoengine/sawitdb

A high-performance hybrid paged database (v3.0.0) featuring single-file storage (.sawit), object caching, and worker-thread parallelism. It supports both Generic SQL and a custom Agricultural Query Language (AQL) using Indonesian farming terminology. Key features include ACID transactions (AKAD), virtual views (TEROPONG), triggers (KENTONGAN), stored procedures (SOP), primary-replica replication (CABANG), and Role-Based Access Control (POS RONDA). It utilizes Write-Ahead Logging (WAL) for crash recovery and provides Change Data Capture (CDC) capabilities.

Tokens
11.6K
Snippets
40
Records
54
Agent score
72%

What's inside @wowoengine/sawitdb

  1. SawitDB Core Features Overview

    main

    SawitDB is a single-file database solution (.sawit) featuring a Hybrid Paged Architecture (4KB pages) with object caching for zero-copy reads. Key capabilities include:

    • Data Integrity: Uses fsync protocols and Write-Ahead Logging (WAL) for crash recovery.
    • Advanced SQL & AQL: Supports JOIN (Left/Right/Full/Cross), DISTINCT, and full-text search via BLUSUKAN.
    • Transactions (v3.0): ACID-compliant transactions using MULAI AKAD, SAHKAN, and BATALKAN.
    • Views (v3.0): Virtual tables using PASANG TEROPONG and BUANG TEROPONG.
    • Triggers (v3.0): Event hooks via KENTONGAN.
    • Procedures (v3.0): Stored scripts via SOP.
    • Replication (v3.0): Primary-Replica synchronization via CABANG.
    • Security (v3.0): Role-Based Access Control (RBAC) via POS RONDA (BERI IZIN/CABUT IZIN).
    • Full-Text Search (v3.0): Inverted Index search via BLUSUKAN.

  2. Understand SawitDB Dual Syntax: AQL vs Generic SQL

    main

    SawitDB supports two query syntaxes: the traditional Agricultural Query Language (AQL), which uses Indonesian farming terminology, and Generic SQL, which follows standard SQL conventions. This allows developers to choose between the unique SawitDB experience or standard SQL familiarity.

    OperationAgricultural Query Language (AQL)Generic SQL (Standard)
    Create DBBUKA WILAYAH sales_dbCREATE DATABASE sales_db
    Use DBMASUK WILAYAH sales_dbUSE sales_db
    Show DBsLIHAT WILAYAHSHOW DATABASES
    Drop DBBAKAR WILAYAH sales_dbDROP DATABASE sales_db
    Create TableLAHAN productsCREATE TABLE products
    InsertTANAM KE products (...) BIBIT (...)INSERT INTO products (...) VALUES (...)
    SelectPANEN * DARI products DIMANA ...SELECT * FROM products WHERE ...
    UpdatePUPUK products DENGAN ...UPDATE products SET ...
    DeleteGUSUR DARI products DIMAMA ...DELETE FROM products WHERE ...
    IndexingINDEKS products PADA priceCREATE INDEX ON products (price)
    AggregationHITUNG SUM(stock) DARI productsSame Syntax
    Begin TransactionMULAI AKADBEGIN TRANSACTION
    CommitSAHKANCOMMIT
    RollbackBATALKANROLLBACK
    Create ViewPASANG TEROPONG [nama] SEBAGAI [query]CREATE VIEW [nama] AS [query]
    Drop ViewBUANG TEROPONG [nama]DROP VIEW [nama]
    TriggerPASANG KENTONGAN [nama] PADA ...CREATE TRIGGER [nama] ON ...
    ProcedureSIMPAN SOP [nama] SEBAGAI ...CREATE PROCEDURE [nama] AS ...
    ReplicationSETEL CABANG SEBAGAI ...CONFIGURE REPLICATION AS ...
    Search (FTS)BLUSUKAN KE [table] CARI "term"SEARCH [table] "term"
    Grant PermissionBERI IZIN [action] KEPADA [user] DI [table]GRANT [action] ON [table] TO [user]
    Revoke PermissionCABUT IZIN [action] DARI [user] DI [table]REVOKE [action] ON [table] FROM [user]

  3. Manage Transactions with AKAD

    main

    SawitDB uses the AKAD concept for transactions to ensure ACID properties. You can use either Tani (AQL) or Generic SQL syntax to manage transaction lifecycles.

    Tani (AQL) Keywords:

    • MULAI AKAD: Begin transaction.
    • SAHKAN: Commit transaction.
    • BATALKAN: Rollback transaction.

    Generic SQL Keywords:

    • BEGIN TRANSACTION
    • COMMIT
    • ROLLBACK
    // Using Tani (AQL) syntax via the query method
db.query('MULAI AKAD');
db.query("TANAM KE Users (name) BIBIT ('Alice')");
db.query('SAHKAN');

  4. Understand SawitDB Architecture

    main

    SawitDB is designed for high performance and fault tolerance using a multi-threaded approach and a hybrid storage engine.

    Key Architectural Components

    • Worker Pool (Multi-threaded):
      • Main Thread: Dedicated strictly to I/O (Networking and Protocol Parsing).
      • Worker Threads: Execute queries in parallel using a Least-Busy Load Balancing strategy.
      • Fault Tolerance: Includes automatic worker healing and rejection of stuck queries.
    • Storage Engine:
      • Hybrid Paging: Uses 4KB binary pages combined with an In-Memory Object Cache for hot data.
      • WAL (Write-Ahead Log): Ensures ACID compliance and enables crash recovery.
      • B-Tree Indexing: Provides $O(\log n)$ lookup performance.
    • Modular Design: Core logic is decoupled into specialized modules like Pager.js, ThreadPool.js, and BTreeIndex.js.

  6. Quick Start: Start the SawitDB Server

    main

    To run the SawitDB server, use the provided executable. By default, the server listens on 0.0.0.0:7878. You can also enable Cluster Mode by configuring your .env file.

    node bin/sawit-server.js

  7. Enable Change Data Capture (CDC) via CPO Adapter

    main

    To enable Change Data Capture (CDC), you must configure a CDC Adapter in your .env file. Currently, only the CPO adapter is supported. The adapter captures changes in SawitDB and writes them as AQL to a specified file.

    Set the following environment variables in your .env file:

    • SAWIT_CDC_FILE: The path where the .cpo log file will be written.
    • SAWIT_CDC_ADAPTER: Set this to cpo to enable the adapter.
    SAWIT_CDC_FILE=./examples/logs/sawit.cpo
SAWIT_CDC_ADAPTER=cpo

  8. Implement Change Data Capture (CDC) with DB Event

    main

    SawitDB provides Event Driven capabilities for Change Data Capture (CDC).

    Supported Events

    • OnTableCreated, OnTableDropped, OnTableSelected, OnTableInserted, OnTableUpdated, OnTableDeleted.

    Enabling CDC via Environment Variables

    To enable CDC using the CPO adapter, set the following in your .env file:

    SAWIT_CDC_FILE=./examples/logs/sawit.cpo
SAWIT_CDC_ADAPTER=cpo

    Custom Event Handler

    To use a custom handler, pass an instance of your handler class to the SawitDB constructor:

    const CustomHandler = require('./dbeventHandlerExample');
const db = new SawitDB(dbPath, { dbevent: new CustomHandler() });

  9. Quick Start: Connect to the SawitDB Server

    main

    Once the server is running, you can connect to it using the built-in CLI tool for remote access:

    node cli/remote.js

    Alternatively, you can integrate the SawitClient class directly into your Node.js application to connect via the sawitdb:// protocol over TCP.

  10. Query with Tani Edition (AQL) and Generic SQL

    main

    SawitDB supports two query syntaxes: Tani Edition (AQL), which uses Indonesian-inspired terminology, and Generic SQL, which follows standard SQL patterns. Both syntaxes are mapped to the same underlying engine operations.

    Management Commands

    • Create Table: LAHAN users (Tani) or CREATE TABLE users (Generic).
    • Show Tables: LIHAT LAHAN (Tani) or SHOW TABLES (Generic).
    • Drop Table: BAKAR LAHAN users (Tani) or DROP TABLE users (Generic).

    Data Manipulation

    • Insert: TANAM KE users (name, role) BIBIT ('Alice', 'Admin') (Tani) or INSERT INTO users (name, role) VALUES ('Alice', 'Admin') (Generic).
    • Select: PANEN name, role DARI users DIMANA role = 'Admin' (Tani) or SELECT name, role FROM users WHERE role = 'Admin' (Generic).
    • Update: PUPUK users DENGAN role='SuperAdmin' DIMANA name='Alice' (Tani) or UPDATE users SET role='SuperAdmin' WHERE name='Alice' (Generic).
    • Delete: GUSUR DARI users DIMANA name='Bob' (Tani) or DELETE FROM users WHERE name='Bob' (Generic).

    Advanced Operations

    • Indexing: INDEKS [table] PADA [field] or CREATE INDEX ON [table] ([field]).
    • Aggregation: Use HITUNG (Tani) or standard SQL functions like COUNT, AVG, SUM, MIN, MAX with KELOMPOK (Tani) or GROUP BY (Generic).
    • Full-Text Search (BLUSUKAN): BLUSUKAN KE products CARI "sawit" or SEARCH products "sawit".
    • Explain Plan: JELASKAN SELECT ... or EXPLAIN SELECT ... to view execution plans.
    -- Tani (AQL) Example
TANAM KE users (name, role) BIBIT ('Alice', 'Admin')
PANEN name, role DARI users DIMANA role = 'Admin'

-- Generic SQL Example
INSERT INTO users (name, role) VALUES ('Alice', 'Admin')
SELECT name, role FROM users WHERE role = 'Admin'

  12. Configure Replication (CABANG)

    main

    SawitDB supports replication using a Primary/Replica model. Use the SETEL CABANG command to define the role of a node.

    Roles:

    • PRIMARY / PUSAT: The master database.
    • REPLICA / CABANG: The slave database.

    Usage:

    • On Master: SETEL CABANG SEBAGAI PRIMARY
    • On Slave: SETEL CABANG SEBAGAI REPLICA [host] [port] (e.g., SETEL CABANG SEBAGAI REPLICA 192.168.1.100 7878).
    -- On Master
SETEL CABANG SEBAGAI PRIMARY

-- On Slave
SETEL CABANG SEBAGAI REPLICA 192.168.1.100 7878