README

The Gabbro Database Library provides a lightweight, consistent abstraction layer over SQL databases.
It is designed to expose a common set of interfaces (Connection, Statement, Cursor) that can be reused across multiple database backends, while still giving developers access to features like typed placeholders and prepared statements.

Key Concepts

• Connection
  Represents an open database connection.
  Provides methods to execute() statements, query() to return results, and prepare() to create reusable prepared statements.

• Statement
  A precompiled SQL statement created via Connection::prepare().
  Statements can be executed or queried to return a Cursor.

• Cursor
  Provides iteration over a result set.
  Offers row navigation (moveTo(), moveToNext()), metadata (getCount(), getColumnCount()), and column value retrieval (getColumn()).

Placeholders

Queries use custom placeholders similar to sprintf() but adapted for SQL:

• %s → string
• %i → integer
• %f → float
• %b → blob

The library parses placeholders, replaces them with database-specific markers (e.g. ? for SQLite), and binds values in a safe, type-aware way.

Current Implementation

• SQLite3 backend is included (gabbro\\database\\sqlite3\\Connection).
  Uses in-memory or file-based SQLite databases and fully supports the interfaces.

use gabbro\database\sqlite3\Connection;

$db = new Connection($file);
$cursor = $db->query("SELECT * FROM MyTable WHERE id > %i", 10);

while ($cursor->moveToNext()) {
    $name = $cursor->getColumn("username");
    ...
}

Goals

• Provide a unified API across different SQL backends.
• Ensure safe handling of placeholders and type conversions.
• Keep the design minimal, without hiding the underlying database’s capabilities.