NAME

Database::BI::Extract -- SQLite materialisation cache for Database::BI

SYNOPSIS

use Database::BI::Extract;

my $cache = Database::BI::Extract->new(model_dir => '.bi');

# Check cache
my $path = $cache->get($spec, $mtime, $size);
unless ($path) {
    my $bytes = ...; # build the SQLite file
    $path = $cache->put($spec, $mtime, $size, $bytes);
}

DESCRIPTION

Stores SQLite materialisation files (extracts) under model_dir/extracts/. The cache key is an MD5 of the dataset spec, its source mtime, and its size. Deleting the extracts directory leaves the application fully functional.

This is a standalone cache class. The web application does not call it; the caller decides when to build an extract, and the class only stores and finds the bytes.

METHODS

new

API SPECIFICATION

INPUT

{ model_dir => 'string' }   # required; extracts live in <model_dir>/extracts/

OUTPUT

A Database::BI::Extract object. Croaks model_dir is required without model_dir. Nothing is created on disc until put.

path

API SPECIFICATION

INPUT

$spec    # the dataset spec, e.g. 'table:sales'
$mtime   # source modification time (undef is 0)
$size    # source size in bytes (undef is 0)

OUTPUT

'string'   # <model_dir>/extracts/<md5 of spec, mtime and size>.db

The path is computed, not checked: the file need not exist.

get

API SPECIFICATION

INPUT

The same three arguments as path.

OUTPUT

'string' | undef   # the path when that file exists, otherwise undef

A changed mtime or size gives a different path, so a stale extract is a miss.

put

API SPECIFICATION

INPUT

$spec, $mtime, $size   # as for path
$bytes                 # required; the SQLite file's contents

OUTPUT

'string'   # the path written

Creates extracts/ when it is missing. Croaks sqlite_bytes are required when $bytes is undefined or empty, and croaks naming the path when the directory or file cannot be written.

evict

API SPECIFICATION

INPUT

$spec   # accepted but not used: see below

OUTPUT

'integer'   # the number of files removed (0 when there is no extracts/)

A fingerprint cannot be traced back to its spec, so evict removes every .db file in extracts/, not only $spec's.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne. Usage is subject to the GPL2 licence terms.

cpanm Database::BI

perl -MCPAN -e shell
install Database::BI