🏹 MergenDB

"Big Data on Small Hardware"
MergenDB is an ultra-compact, columnar, embedded database engine and custom query language (MergenQL) designed to run analytical workloads on resource-constrained systems (Raspberry Pi, IoT gateways, low-end VPS, and edge devices) with maximum compression, zero memory exhaustion, and blazingly fast execution.

👨‍💻 Author & Lead Developer: Uğur Türker Kebeci (@ugurturkerkebeci)

Named after Mergen, the ancient Turkic deity of wisdom, precision, and archery—who never misses his target.

📦 Installation

Install MergenDB directly from PyPI:

pip install mergendb

(MergenDB has zero external dependencies for its core engine—runs out of the box on Python 3.8+!)

⚡ Core Philosophy & Architecture

Traditional databases (MySQL, PostgreSQL, SQLite) store data in a row-oriented layout. If a table has 40 columns and you only query temperature and room, row-oriented engines must read all 40 columns from disk, wasting massive I/O bandwidth and RAM.

MergenDB redesigns storage from the silicon up:

  [ Raw Input Records (SQL / CSV / JSON / Dicts) ]
                        │
                        ▼
       [ Vector Chunker (1024 - 4096 rows) ]
                        │
                        ▼
       [ Columnar Vertical Partitioning ]
                        │
  ┌─────────────────────┴──────────────────────┐
  │         Adaptive Compression Engine         │
  │  • Bit-Packing      (8 Bools / Byte)       │
  │  • Frame-of-Ref/Delta (Timestamps & IDs)   │
  │  • Dictionary       (Repeated Strings)     │
  │  • Run-Length (RLE) (Sequential Duplicates)│
  └─────────────────────┬──────────────────────┘
                        │
                        ▼
   [ ZoneMap Indices (Min / Max per Chunk) ]
                        │
                        ▼
      [ .mgdb Columnar Binary Disk Storage ]

1. 🗜️ Adaptive Hardware-Level Encodings

• Bit-Packing: 8 boolean values are packed into a single byte (8x compression).
• Delta / Frame-of-Reference (FoR): Art arda gelen ID'ler veya zaman damgalarında farklar saklanır (8-byte tamsayı yerine 1-2 byte).
• Dictionary Encoding: Tekrar eden metinler (status, category, city) 1-2 byte'lık ID tablolarına eşlenir.
• Run-Length Encoding (RLE): Art arda gelen aynı değerler tek bir sayaçla saklanır.
• Adaptive Selection: MergenDB her blokta en az yer kaplayan algoritmayı otomatik olarak tespit edip seçer.

2. 🎯 ZoneMap Indexing (Zero I/O Block Pruning)

Her veri bloğu minik bir min_val ve max_val üstverisi taşır. Eğer sorgunuz WHERE temperature > 40 ise ve bloğun tavanı 35 ise, MergenDB o bloğu diskten bile okumadan atlar.

3. ✂️ Column Pruning

Tabloda 50 sütun olsa bile sorgunuz 2 sütun istediyse, kalan 48 sütun diskten hiç okunmaz. Disk I/O darboğazı %90+ oranında yok edilir.

4. 🌊 Vectorized & Chunked Streaming (Zero OOM)

Veriler 2048'lik dilimler (chunk) halinde boru hattından akar. 109 Milyonluk dev bir veritabanı bile 512 MB RAM'li küçük bir cihazda belleği patlatmadan (Out Of Memory olmadan) işlenir.

📊 Benchmark: MergenDB vs SQLite vs JSON

Tested on 100,000 analytical telemetry records (12 columns per row):

🚀 Sonuç: MergenDB SQLite'tan 5 kat, JSON'dan 12 kat daha küçüktür. Analitik sorgularda diski 27 kat daha az yorar!

📖 MergenQL & Komut Başvuru Kılavuzu (Cheat Sheet)

MergenDB'nin özgün sorgu dili MergenQL, verinin mantıksal olarak soldan sağa aktığı boru hattı (|) mimarisine dayanır.

1. Boru Hattı Aşamaları (Pipeline Stages)

2. Desteklenen Filtreleme Operatörleri (WHERE)

• Karşılaştırma: ==, =, !=, <>, <, <=, >, >=
• Mantıksal: AND, OR
• Metin Arama: LIKE (SQL % ve _ joker karakterlerini destekler)
  Örnek: | WHERE room LIKE "kit%" veya | WHERE email LIKE "%@gmail.com"

3. Agregasyon Fonksiyonları (AGGREGATE)

• count(*) veya count(col): Satır adedi
• sum(col): Toplam
• avg(col): Aritmetik ortalama
• min(col): En küçük değer
• max(col): En büyük değer
• median(col): Medyan (ortanca) değer
• stddev(col): Standart sapma

📥 SQL & phpMyAdmin Veritabanlarını İçe Aktarma

1. phpMyAdmin veya MySQL Dump Dosyalarını Aktarma (.sql)

phpMyAdmin'den dışa aktarılan database.sql dosyalarını tek satırda dönüştürün (MySQL'e özel ENGINE=InnoDB, AUTO_INCREMENT, LOCK TABLES gibi fazlalıklar otomatik temizlenir):

import mergendb

table = mergendb.from_sql_dump("phpmyadmin_dump.sql", "database.mgdb")
print(f"Toplam {table.row_count:,} satır MergenDB'ye aktarıldı!")

2. SQLite Veritabanlarını Aktarma (.db, .sqlite)

table = mergendb.from_sqlite("legacy.db", "orders.mgdb", table_name="orders")

3. Canlı MySQL / PostgreSQL / Oracle Bağlantılarından Çekme

import pymysql
from mergendb.io.importer import DataImporter

conn = pymysql.connect(host="localhost", user="root", password="", database="eticaret")
cur = conn.cursor()
cur.execute("SELECT * FROM siparisler")

DataImporter.from_cursor(cur, output_mgdb_path="siparisler.mgdb")

4. CSV Dosyalarını Otomatik Tip Algılama ile Aktarma

table = mergendb.from_csv("sensor_data.csv", "sensor_data.mgdb")

💻 İnteraktif Terminal Kabuğu (REPL CLI) & SQL Desteği

MergenDB, terminalden tek bir komutla açılan, tıpkı MySQL CLI gibi zengin komut setine sahip bir REPL kabuğu içerir:

# Terminalden anında başlatın:
mergen
# veya:
python -m mergendb.cli.repl

                _
               / \
              /   \
             / / \ \                   __  __                                _____  ____  
            / /   \ \                 |  \/  |                             |  __ \|  _ \ 
           / /  |  \ \                | \  / | ___ _ __ __ _  ___ _ __     | |  | | |_) |
          / /  / \  \ \               | |\/| |/ _ \ '__/ _` |/ _ \ '_ \    | |  | |  _ < 
         / /  /   \  \ \              | |  | |  __/ | | (_| |  __/ | | |   | |__| | |_) |
        / /  / /|\ \  \ \             |_|  |_|\___|_|  \__, |\___|_| |_|   |_____/|____/ 
       / /  / / | \ \  \ \                              __/ |                            
      / /__/_/  |  \_\__\ \                            |___/  v0.4.0 (Lightning Engine)
     /     \    |    /     \
    /_______\   |   /_______\         =[ MergenDB - Lightning Columnar Database      ]
             \  |  /           + -- --=[ 16 Adaptive Hardware Encodings (Up to 16x)  ]
              \ | /            + -- --=[ ZoneMap Zero-I/O Indexing (100M+ Rows Safe) ]
               \|/             + -- --=[ Network SQL/MergenQL Server on Port 8765    ]
                |              + -- --=[ Zero External Dependencies | Pure Speed     ]
                '              + -- --=[ Author: Ugur Turker Kebeci (@ugurturkerkebeci)

                   "Target Acquired. Zero Waste. Pure Speed."
    Type SQL or MergenQL commands ending with ';'. Type 'HELP;' for command list.

🛠️ MySQL Benzeri Veritabanı Yönetim Komutları

🌐 MergenDB Network Server (MySQL/PostgreSQL Tarzı Ağ Sunucusu)

MergenDB yalnızca gömülü (embedded) bir kütüphane değil, aynı zamanda uzaktan REST & JSON üzerinden sorgu çalıştırabileceğiniz bir Veritabanı Sunucusudur.

Sunucuyu Başlatma

# Bağımsız sunucuyu 8765 portunda başlatın:
mergendb-server --port 8765

# Veya Python içerisinden:
mergendb serve 8765

======================================================================
   🏹 MERGENDB SERVER (MergenQL & SQL Network Engine)
======================================================================
  * Status        : RUNNING
  * Listening on  : http://0.0.0.0:8765
  * Local Web API : http://localhost:8765
  * Query Endpoint: POST http://localhost:8765/query
  * Working Dir   : /data/db
======================================================================

Uzaktan Sorgu Gönderme (HTTP & cURL)

Herhangi bir dilden (Python, Node.js, Go, PHP, C# vb.) standart HTTP POST isteğiyle MergenQL veya SQL sorguları çalıştırabilirsiniz:

curl -X POST http://localhost:8765/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT user_id, email, city FROM users WHERE city == \"Istanbul\" LIMIT 10;"}'

JSON Yanıtı:

{
  "success": true,
  "columns": ["user_id", "email", "city"],
  "rows": [
    [1001, "ugur@example.com", "Istanbul"],
    [1042, "ali@example.com", "Istanbul"]
  ],
  "stats": {
    "execution_time_ms": 1.45,
    "rows_returned": 2,
    "blocks_scanned": 1,
    "blocks_skipped": 48,
    "bytes_read": 1024
  }
}

🧪 Test Paketini Çalıştırma

python -m unittest discover tests

(Tüm 16 birim testi sıfır hata ile geçmektedir).

👨‍💻 Yazar & İletişim

• Geliştirici: Uğur Türker Kebeci
• GitHub: @ugurturkerkebeci
• Proje Deposu: https://github.com/ugurturkerkebeci/MergenDB
• PyPI: https://pypi.org/project/mergendb/

📄 Lisans

Bu proje MIT Lisansı ile lisanslanmıştır. Açık kaynak dünyasına ve düşük donanımlı sistemlerde büyük veri analitiğine katkı sağlamak amacıyla geliştirilmiştir.