Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dabinuss/flatfiledb

FlatFileDB is a lightweight, file-based database for PHP with JSON lines, indexing, schema validation, and transaction logging—ideal for small to medium projects.
https://github.com/dabinuss/flatfiledb

file-based-database file-storage flat-file flatfile flatfiledb json json-lines nosql nosql-database nosql-databases php php-database php8

Last synced: 2 months ago
JSON representation

FlatFileDB is a lightweight, file-based database for PHP with JSON lines, indexing, schema validation, and transaction logging—ideal for small to medium projects.

Awesome Lists containing this project

README 

        
FlatFileDB Documentation

========================



FlatFileDB: A Simple File-Based Database Solution for PHP

=========================================================



Introduction

------------



FlatFileDB is a lightweight, file-based database solution for PHP applications that requires no external database servers such as MySQL or PostgreSQL. This system is perfect for small to medium-sized projects where setting up and maintaining a full-fledged database would be disproportionate in terms of effort.



### Why FlatFileDB?



-   **Easy Installation**: No complex server configuration needed -- simply include the PHP classes and get started.

-   **Portability**: The entire database consists of plain files, which can be easily moved between different environments.

-   **No Dependencies**: Works without external libraries or services.

-   **Transparency**: Records are stored in readable JSON-lines files, making debugging and manual intervention straightforward.

-   **Performance**: Indexing ensures that data access remains efficient even with larger datasets.



### Use Cases



FlatFileDB is particularly suitable for:



-   Prototypes and proof-of-concept applications

-   Small web applications with limited data volume

-   Local tools and utilities

-   Projects with restricted server resources

-   Educational settings to learn about database concepts



### Technical Fundamentals



FlatFileDB is based on the following principles:



-   Data stored in JSON-lines format (one JSON object per line)

-   Indexing of records to speed up access

-   Transaction-safe logging for traceability of changes

-   Schemas for validating records



It is fully implemented in PHP and can be used in any environment that supports PHP.



* * * * *



1\. Overview and Preparation

----------------------------



FlatFileDB is a simple file-based database that stores records in JSON-lines files. Its key features include:



-   **CRUD Operations**: Insert, update, delete, and retrieve records.

-   **Index Management**: An internal index maps record IDs to byte offsets in the file, ensuring efficient access even with large files.

-   **Transaction Logging**: Each operation is logged, which is particularly useful for error tracing or auditing.

-   **Compaction**: Redundant (deleted or outdated) records can be removed from the file, and the index can be rebuilt.



Before you start, you should have the following files in your project:



-   FlatFileDB.php (contains all classes: FlatFileDatabase, FlatFileTableEngine, etc.)

-   A file in which you write your application logic (e.g. testdb.php)



2\. Including and Initializing the Database

-------------------------------------------



First, include the database classes and create a database instance.



Example:



php



KopierenBearbeiten



`registerTables(['users', 'products']);`



3\. Defining the Schema

-----------------------



For each table, you can define a schema. The schema specifies required fields and expected data types. This is especially helpful to ensure that only valid records make it into the database.



Example:



php



KopierenBearbeiten



`// For the "users" table, we define that 'name' and 'email' are required fields.

// We also specify that 'name' and 'email' are strings, and 'age' is an integer.

$db->table('users')->setSchema(

    ['name', 'email'],

    ['name' => 'string', 'email' => 'string', 'age' => 'int']

);`



4\. CRUD Operations

-------------------



### a) Inserting a Record (Insert)



Use the `insertRecord()` method to add a new record. It's important that the ID is unique.



Example:



php



KopierenBearbeiten



`// Insert a new user

$success = $db->table('users')->insertRecord('user123', [

    'name'  => 'Alice Johnson',

    'email' => '[email protected]',

    'age'   => 32

]);



if ($success) {

    echo "User successfully inserted.";

} else {

    echo "Error: A user with this ID already exists.";

}



// After writing, manually commit the index

// so the current index file is used on page reload

$db->commitAllIndexes();`



### b) Updating a Record (Update)



Use `updateRecord()` to update an existing record. Older versions of the record are marked as deleted, and a new entry is appended.



Example:



php



KopierenBearbeiten



`// Update an existing user

$success = $db->table('users')->updateRecord('user123', [

    'name'  => 'Alice J.',

    'email' => '[email protected]',

    'age'   => 33

]);



if ($success) {

    echo "User successfully updated.";

} else {

    echo "Error: User not found.";

}



// Commit the index

$db->commitAllIndexes();`



### c) Deleting a Record (Delete)



Use `deleteRecord()` to delete a record. The record is marked as deleted, and the index is updated accordingly.



Example:



php



KopierenBearbeiten



`// Delete a user

$success = $db->table('users')->deleteRecord('user123');



if ($success) {

    echo "User successfully deleted.";

} else {

    echo "Error: User could not be found.";

}



// Save the index

$db->commitAllIndexes();`



### d) Retrieving a Record (Select)



Use `selectRecord()` to retrieve a single record, and `selectAllRecords()` to fetch all active (non-deleted) records.



Example:



php



KopierenBearbeiten



`// Retrieve a single user

$user = $db->table('users')->selectRecord('user123');

if ($user) {

    print_r($user);

} else {

    echo "User not found.";

}



// Retrieve all active users

$allUsers = $db->table('users')->selectAllRecords();

foreach ($allUsers as $user) {

    echo "ID: {$user['id']}, Name: {$user['name']}
";

}`



5\. Additional Functions

------------------------



### a) Index Management



**compactTable()**:



-   This operation "cleans up" the data file by removing outdated and deleted entries and rebuilding the index.

-   Usage: Run compaction manually or periodically, as it can be relatively intensive.



Example:



php



KopierenBearbeiten



`$db->table('users')->compactTable();

echo "Table 'users' has been compacted.";`



### b) Backup and Clearing the Database



**Creating a Backup**:



-   Use `createBackup($backupDir)` to back up all tables.



Example:



php



KopierenBearbeiten



`$backupResults = $db->createBackup(FlatFileDBConstants::DEFAULT_BACKUP_DIR);

echo "Backup has been created.";`



**Clearing the Database**:



-   Use `clearDatabase()` to delete all data, indexes, and logs.



Example:



php



KopierenBearbeiten



`$db->clearDatabase();

echo "The database has been cleared.";`



6\. Integrating into Your HTML Interface

----------------------------------------



Typically, you combine the operations described above with an HTML form to allow user interactions. A sample workflow might look like this:



**Submitting a Form via POST**:



-   Each action (insert, update, delete, search, backup, compaction) is defined by a hidden field `action`, for example:



html



KopierenBearbeiten



`

    

    

    Add User

`



**Executing the PHP Logic**:



-   In your PHP code, read `$_POST['action']` and run the corresponding case in a switch statement (as in the examples above).



**Feedback and Updates**:



-   After the operation, commit the index (or optionally compact the table). Then display a success message. On page reload, the current data is loaded from the file (or from the persisted index).