🚀 PdoDb — Future-Proof PDO Database Core

Production-grade, single-file PDO execution core and lightweight query builder for PHP.

Provides a secure, ergonomic, and efficient way to interact with databases using prepared statements, strict validation, and zero-dependency architecture.

Based on long-term production backend design principles.

---

🎯 Project Philosophy

This project is designed using Principal / Lead Architect backend standards:

✅ Security First
✅ Prepared Statements Only
✅ Deterministic Query Execution
✅ Zero Framework Lock-In
✅ Zero Runtime Dependencies
✅ Long-Term Maintainability (10+ years mindset)
✅ Production Infrastructure Friendly

---

📦 Core Features

✅ Single File Architecture

Drop into any project instantly.

No Composer required.
No dependency hell.

---

✅ PDO Based Execution Core

Supports:

• MySQL / MariaDB
• PostgreSQL
• SQLite (driver dependent)

---

✅ Lightweight Query Builder

Fluent builder similar to MysqliDb ergonomics.

---

✅ Multiple Connections

Supports named connections and runtime switching.

---

✅ Nested Transactions

Supports SAVEPOINT-based nested transaction logic.

---

✅ Hooks System

Built-in extension points:

• Query Logging
• Metrics
• Auditing
• Retry logic

---

✅ Pagination Support

Built-in pagination helper.

---

🧱 Installation

Just include file:

require_once 'PdoDb.php';

---

⚡ Initialization

$db = PdoDb::create([
    'default' => [
        'dsn' => 'mysql:host=localhost;dbname=test_db;charset=utf8mb4',
        'username' => 'root',
        'password' => 'secret'
    ]
]);

---

📊 Basic Usage

---

SELECT — Get Multiple Rows

$users = $db->get('users');

---

SELECT — With Conditions

$users = $db
    ->where('active', 1)
    ->orderBy('created_at', 'DESC')
    ->limit(10)
    ->get('users');

---

SELECT — Get One Row

$user = $db->where('id', 42)->getOne('users');

---

SELECT — Get Single Value

$count = $db->getValue('users', 'COUNT(*)');

---

✏️ Insert Data

---

Insert Single Row

$id = $db->insert('users', [
    'username' => 'john',
    'email' => 'john@example.com'
]);

---

Insert Multiple Rows

$db->insertMulti('users', [
    ['username' => 'user1'],
    ['username' => 'user2']
]);

---

🔄 Update Data

$db->where('id', 42)->update('users', [
    'active' => 0
]);

---

❌ Delete Data

$db->where('last_login', '2023-01-01', '<')
   ->delete('users');

---

🔗 Query Builder Methods

---

WHERE

$db->where('id', 1);
$db->orWhere('status', 'active');

---

JOIN

$db->join('profiles', 'users.id = profiles.user_id', 'INNER');

---

GROUP BY

$db->groupBy('role');

---

ORDER BY

$db->orderBy('created_at', 'DESC');

---

LIMIT / OFFSET

$db->limit(10)->offset(20);

---

🔥 Raw Queries (Still Safe)

---

Multiple Rows

$db->rawQuery("SELECT * FROM users WHERE id > ?", [100]);

---

One Row

$db->rawQueryOne("SELECT * FROM users WHERE id = ?", [1]);

---

Single Value

$db->rawQueryValue("SELECT COUNT(*) FROM users");

---

📄 Pagination

$result = $db->paginate('users', 1, 20);

Returns:

[
  data => [...],
  pagination => ...
]

---

🔐 Transactions

---

Basic Transaction

$db->startTransaction();

try {
    $db->insert('logs', ['msg' => 'start']);
    $db->commit();
} catch (Exception $e) {
    $db->rollback();
}

---

Nested Transaction

$db->startTransaction();
$db->startTransaction(); // Savepoint
$db->commit();
$db->commit();

---

🌍 Multiple Connections

$analytics = $db->withConnection('analytics');

---

🧪 Debug Mode

$db->debug(true);
print_r($db->queryLog());

---

🔌 Hooks Example

$hooks->afterQuery = function($ctx) {
   if ($ctx['duration_ms'] > 500) {
       error_log("Slow Query");
   }
};

---

🔒 Security Model

✔ Prepared Statements Only
✔ Safe Parameter Binding
✔ Identifier Validation
✔ No SQL Injection Risk

---

⚡ Performance Design

Optimized for:

• OPcache
• Low memory allocation
• Statement reuse
• Future connection pooling

---

🚫 What This Is NOT

❌ Not ORM
❌ Not ActiveRecord
❌ Not Framework
❌ Not Migration Tool

---

🏁 Production Use Cases

✔ SaaS Backends
✔ REST APIs
✔ Microservices
✔ High Traffic Systems
✔ Enterprise PHP Systems

---

📜 License

MIT