MaazDB Documentation

Version: 12.4.1
Default Port: 8888
Protocol: TCP / Binary Length-Prefixed

What is MaazDB?

MaazDB is a lightweight, high-performance database management system built with modern development workflows in mind. It features a custom binary protocol, full ACID compliance, and an intuitive SQL-like query language.

Installation

Linux (Debian/Ubuntu/Kali)

macOS

Windows

1. Connection Protocol

MaazDB uses a custom binary protocol over TCP. Every packet follows this structure:

2. Authentication

If you've used older versions of MaazDB, you might remember having to send a LOGIN SQL query to authenticate. We've completely revamped this process to make it much more secure and developer-friendly!

Now, authentication happens entirely under the hood the moment your driver connects to the database. You simply pass your credentials (host, port, username, and password) directly into your language's driver connection method. This ensures that your session is securely authenticated from the very first packet, preventing unauthorized access before any SQL is even parsed.

// No more LOGIN queries! Just pass credentials to your driver:
const db = new MaazDB();
await db.connect("127.0.0.1", 8888, "admin", "admin");

3. Server Configuration

MaazDB is highly customizable. Upon installation, a configuration file is generated. You can use this file to change the default port, bind address, TLS certificates, and fine-tune logging for maximum performance.

# ========================================================
# MaazDB Professional Configuration
# ========================================================

[server]
host = "0.0.0.0"
port = 8888
cert_file = "certs/server.crt"
key_file = "certs/server.key"

[storage]
data_dir = "data"

[logging]
# Set to false to enable high-performance logging
enabled = false
log_dir = "logs"
max_files = 5
# 10 MB rotation limit
max_log_size = 10485760 
# Levels: trace | debug | info | warn | error
level = "info"
# Keep false for maximum benchmark performance
console_enabled = false

Ecosystem & Official Drivers

MaazDB isn't just a standalone database; it's a growing ecosystem. We know that writing raw TCP sockets isn't fun, so we've built native, highly-optimized drivers for your favorite programming languages.

Whether you are building a web backend in Node.js, a high-performance system in Rust, or doing data analysis in Python, we have an official library ready for you. These drivers handle all the complex binary protocol packing, TLS encryption, and connection pooling automatically.

4. Database Management & Architecture

USE <db_name>;

USE ecommerce_app;
-- The system now routes all queries to the 'ecommerce' shards

USE blog_app;
-- The system instantly switches routing to the 'blog' shards

Create Database

Initialize a new storage namespace within the system.

CREATE DATABASE <db_name>;

Show Databases

SHOW DATABASES;

Drop Database

DROP DATABASE <db_name>;

5. Data Types

Create Table

CREATE TABLE <table_name> (
    <col_name> <type> [PRIMARY KEY],
    ...
);

Foreign Keys

CREATE TABLE <table_name> (
    ...
    FOREIGN KEY (<local_col>) REFERENCES <parent_table>(<parent_col>)
);

Table Management

Show Tables

SHOW TABLES;

Describe Table

DESCRIBE <table_name>;

Drop Table

DROP TABLE <table_name>;

6. Data Manipulation (DML)

Insert

Adds new rows to a table. Do not include SERIAL columns in your insert statement, as they auto-increment.

INSERT INTO <table_name> (<col1>, <col2>) VALUES (<val1>, <val2>);

Select

Retrieves data with powerful filtering capabilities.

SELECT <cols> FROM <table_name> [WHERE condition];

Aggregate Functions

Aggregate functions perform a calculation on a set of values and return a single value. They are incredibly useful for data analysis.

-- Get the total number of users and the sum of all salaries
SELECT COUNT(*) as total_users, SUM(salary) as total_payroll FROM users;

-- Find the highest and lowest salary in the company
SELECT MAX(salary) as highest_salary, MIN(salary) as lowest_salary FROM users;

Update

Modifies existing data based on a specific condition.

UPDATE <table_name> SET <col> = <val> WHERE <condition>;

Delete

Removes rows from a table based on a condition.

DELETE FROM <table_name> WHERE <condition>;

7. Disaster Recovery

Backup

BACKUP '<snapshot_name>';

Show Backups

SHOW BACKUPS;

Restore

RESTORE '<snapshot_name>';

8. Comments & Literals

Comments

-- This is a single-line comment
/* This is a
   multi-line comment */

Complete Test Suite Example

Below is a comprehensive test suite demonstrating all major features of MaazDB. You can run this directly in your client to verify your setup.

-- MaazDB Comprehensive Test Suite
-- Note: Authentication is handled by the client driver.

-- 1. Database Management
CREATE DATABASE full_test_db;
USE full_test_db;

-- 2. DDL (Schema Creation)
CREATE TABLE employees (
    id SERIAL PRIMARY KEY,
    name TEXT,
    role TEXT,
    salary DOUBLE,
    is_active BOOL
);

-- 3. DML (Data Insertion)
INSERT INTO employees (name, role, salary, is_active) VALUES ('Alice', 'Engineer', 85000.00, TRUE);
INSERT INTO employees (name, role, salary, is_active) VALUES ('Bob', 'Manager', 95000.50, TRUE);
INSERT INTO employees (name, role, salary, is_active) VALUES ('Charlie', 'Intern', 30000.00, FALSE);

-- 4. SELECT with Aggregates
SELECT COUNT(*) as total_staff FROM employees;
SELECT SUM(salary) as total_payroll FROM employees;
SELECT MAX(salary) as highest_paid FROM employees;
SELECT MIN(salary) as lowest_paid FROM employees;

-- 5. UPDATE & DELETE
UPDATE employees SET salary = 90000.00 WHERE name = 'Alice';
DELETE FROM employees WHERE name = 'Charlie';

-- 6. Cleanup
USE system;
DROP DATABASE full_test_db;