taeluf/big-db

A feature-rich (but somewhat minimalist) database layer for php, with ORM, migrations, and more.

v1.0.x-dev 2025-06-05 17:02 UTC

Requires

• taeluf/lildb: v0.1.x-dev

Requires (Dev)

• taeluf/cli: v0.1.x-dev
• taeluf/code-scrawl: v0.8.x-dev
• taeluf/tester: v0.3.x-dev

Suggests

• taeluf/cli: Required for bigdb cli, for easy access to your database

MIT

• Taeluf

README

BigDb

BigDb is a database library centered around raw SQL with migration and ORM support, with convenience features but very little magic.

NOTICE: cli bin/bigdb is undergoing major changes & is currently broken.
NOTICE: BigDb is mostly stable, but is still under development & much may change.

Install

composer require taeluf/big-db v1.0.x-dev   

or in your composer.json

{"require":{ "taeluf/big-db": "v1.0.x-dev"}}  

Documentation

(Note: Much of the documentation needs improvement)

• Getting Started (below)
• Usage
  • Cli - work with your database from the command line
  • CRUD - Simple CRUD operations and SQL execution.
  • ORMs - Query for orms & use them to insert, update, and delete rows.
  • Run Migrations - vendor/bin/bigdb migrate [cur_ver] [target_ver]
• Library Development
  • Stored Sql - Store SQL, execute them, query for rows, query for ORMs
  • Migrations - Upgrade & Downgrade your database schema
  • BigDb Subclass - Subclass BigDb modify internals and share features across orms.
  • Create ORMs - Represent database rows with php objects
• Other
  • Test Your ORMs - Simplified testing by defining data.
  • Changelog
  • Status Notes
  • License
  • API Documentation - Breakdown of all the classes, their properties, and methods.
  • Sample BigDb Library - A full BigDb library used by our tests. See BigDb Tests for an example of how this library is used.
  • Bugs/Issues - Known issues & quirks

Getting Started

The essential steps are:

1. Create a db folder
2. Initialize PDO & BigDb
3. Execute a stored query, a migration, or load an orm.

1. Create a db folder

Note: Your orm and other class files don't have to go in this directory. If you put them here, update your autoload directory configurations to find them.

See links above for more information on each of the files below.

(everything is optional)

db/  
    MyBigDb.php     // subclass of \Tlf\BigDb  
    MyBigOrm.php    // subclass of \Tlf\BigOrm   
    sql/  
        create.sql  // SQL for initializing your database  
        main.sql    // other SQL statements/queries  
    migrate/  
        v1/  
            up.php // initialize your database  
            down.php // downgrade from v2  
    orm/  
        MyOrmClass.php  // extend from \Tlf\LilOrm or MyLilOrm if you made a custom parent class  

2. Initialize PDO & BigDb

Create a function like the following and call it globally or put it as a static function on your BigDb subclass.

<?php  
  
namespace YourNamespace;  
  
function get_db(): \Tlf\BigDb {  
    static $big_db;  
    if (isset($big_db) && $big_db instanceof \Tlf\BigDb) return $big_db;  
  
    $db_dir = __DIR__.'/db/';  
    $env_file = __DIR__.'/.env/secret.json';  
  
    $settings = json_decode(file_get_contents($env_file), true);  
    $pdo = new \PDO('mysql:dbname='.$settings['db.name'].';host='.$settings['db.host'], $settings['db.user'], $settings['db.password']);  
  
    // define the db params, of course    
    $pdo = new \PDO('mysql:dbname='.$db_name.';host='.$db_host, $user_name, $password);    
  
    $big_db = new \Tlf\BigDb($pdo);  
    $big_db->init_from_dir($db_dir);  
    $big_db->orm_namespace = "\\YourNamespace\\Orm"; // all orm class will be loaded from within this namespace.  
  
    return $big_db;  
}  

3. Execute a stored query, a migration, or load an orm.

Stored Queries

<?php  
$big_db = \YourNamespace\get_db();  
  
// stored queries   
$rows = $big_db->query_rows('main.get_books', $paramaters = [...]);   
$num_rows_affected = $big_db->exec('main.delete_adult_books', $paramaters = [...]);  

Migrations

<?php  
$big_db = \YourNamespace\get_db();  
  
$big_db->migrate(0,2); // executes v1/up.php AND v2/up.php  

Load an orm

<?php  
$big_db = \YourNamespace\get_db();  
  
$orms = $big_db->query('book', 'main.get_books', $paramaters = [...]); // loads class `\YourNamespace\Orm\Book` for each row.  
// OR: $orm = $big_db->row_to_orm('book', $book_row);  
  
$first_book = $orms[0];  
$first_book->title = "(modified)".$first_book->title;  
$first_book->save();  
if ($first_book->is_adult()){  
    $first_book->delete();  
}  
  
$new_book = new \YourNamespace\Orm\Book($big_db);  
$new_book->title = "New book";   
$new_book->save();