Hazaar DBI Filesystem Backend

The Hazaar DBI library provides a robust and reliable filesystem backend for Hazaar's filesystem abstraction. This backend allows you to store files and directories within any relational database supported by PDO and the Hazaar DBI library. It has been proven in production environments, with users reporting reliable filesystem access and no significant slowdowns even with data stores exceeding 40GB.

One of the key features of the DBI filesystem is its intelligent de-duplication mechanism. Files are stored using a content-addressable storage model where data is hashed to ensure uniqueness. If multiple files contain the exact same data, the physical data is stored only once in the database, regardless of how many times the file appears in the virtual filesystem.

This architecture makes file operations like copying incredibly fast, as the system simply creates a new reference to the existing data rather than physically duplicating it. Crucially, this de-duplication is transparent and safe: modifying one instance of a file will never affect other instances. As soon as a file is modified and its content deviates from the stored original, the system automatically creates a new, independent copy of the data for that specific file.

Media Configuration

The Hazaar media.php configuration file is used to configure media sources and needs to be configured with a new media source that uses the dbi driver.

The options.db configuration array is the same as a standard DBI configuration and is passed directly to the DBI adapter. This means all standard DBI options are supported.

<?php
return [
    'sourcename' => [
        'backend' => 'dbi',
        'options' => [
            'db' => [
                'driver' => 'pgsql',
                'host' => '127.0.0.1',
                'dbname' => 'database_name',
                'user' => 'username',
                'password' => 'password',
            ],
        ],
    ],
];

Usage

Once configured, you can use the Hazaar\File\Manager to interact with files stored in the database just like any other filesystem.

use Hazaar\File\Manager;

// Get the file manager for the 'sourcename' source configured above
$manager = new Manager('sourcename');

// Write a file
$manager->write('test.txt', 'Hello World!');

// Read a file
$content = $manager->read('test.txt');

// List files
$files = $manager->dir('/');

// Delete a file
$manager->delete('test.txt');

Manually Preparing the Database

The database tables required for the DBI filesystem can be automatically created as part of a schema migration if the schema manager detects that the DBI filesystem is being used. However, if you prefer to create them manually, you can use the SQL scripts below.

PostgreSQL

CREATE TABLE public.hz_file_chunk
(
    id serial NOT NULL,
    parent integer,
    n integer NOT NULL,
    data bytea NOT NULL,
    PRIMARY KEY (id),
    FOREIGN KEY (parent)
        REFERENCES public.hz_file_chunk (id) MATCH SIMPLE
        ON UPDATE NO ACTION
        ON DELETE NO ACTION
);

CREATE INDEX hz_file_chunk_parent_idx
    ON public.hz_file_chunk USING btree
    (parent ASC NULLS LAST);

CREATE TABLE public.hz_file
(
    id serial NOT NULL,
    kind text,
    parent integer,
    start_chunk integer,
    filename text,
    created_on timestamp without time zone,
    modified_on timestamp without time zone,
    length integer,
    mime_type text,
    md5 text,
    owner text,
    "group" text,
    mode text,
    metadata json,
    PRIMARY KEY (id),
    FOREIGN KEY (start_chunk)
        REFERENCES public.hz_file_chunk (id) MATCH SIMPLE
        ON UPDATE NO ACTION
        ON DELETE NO ACTION
);

CREATE INDEX hz_file_parent_idx
    ON public.hz_file USING btree
    (parent ASC NULLS LAST);