/ 
Concierge-Users-v0.7.3
/ Concierge::Users::Database

NAME

Concierge::Users::Database - SQLite storage backend for Concierge::Users

VERSION

v0.7.2

SYNOPSIS

use Concierge::Users;

# Setup with the database backend
Concierge::Users->setup({
    storage_dir             => '/var/lib/myapp/users',
    backend                 => 'database',
    include_standard_fields => 'all',
});

# Runtime -- the backend is loaded automatically
my $users = Concierge::Users->new('/var/lib/myapp/users/users-config.json');

DESCRIPTION

Concierge::Users::Database implements the Concierge::Users storage interface using SQLite via DBI and DBD::SQLite. User records are stored in a single users table inside <storage_dir>/users.db.

This is the recommended backend for production deployments and larger datasets. It provides indexed lookups, SQL-based filtering, and transactional writes with no external database server required.

Archiving: When setup() is called and the users table already contains data, the existing table is renamed to users_YYYYMMDD_HHMMSS before a new table is created. Empty tables are silently dropped.

Applications interact with this module indirectly through the Concierge::Users API; direct instantiation is not required.

METHODS

configure

my $result = Concierge::Users::Database->configure(\%setup_config);

Class method called by Concierge::Users->setup(). Creates (or archives and recreates) the SQLite database and users table. Returns a hashref with success, message, and config.

new

my $backend = Concierge::Users::Database->new(\%runtime_config);

Constructor called by Concierge::Users->new(). Connects to the existing SQLite database using the saved configuration. Croaks on connection failure.

add

my $result = $backend->add($user_id, \%initial_record);

Inserts a new row. Sets created_date and last_mod_date to the current UTC timestamp.

fetch

my $result = $backend->fetch($user_id);

Retrieves a single user by user_id. Returns { success => 1, data => \%row } or { success => 0, message => "..." }.

update

my $result = $backend->update($user_id, \%updates);

Updates the specified fields for an existing user. Read-only fields (user_id, created_date, last_mod_date) are stripped automatically; last_mod_date is refreshed.

delete

my $result = $backend->delete($user_id);

Deletes the row matching user_id.

list

my $result = $backend->list(\%filters, \%options);

Returns all users matching the parsed filter structure (see "FILTER DSL" in Concierge::Users::Meta). With no filters, returns all users. Result: { data => \@rows, total_count => $n }.

disconnect

$backend->disconnect();

Closes the database handle. Also called automatically during object destruction.

DEPENDENCIES

DBI, DBD::SQLite

SEE ALSO

Concierge::Users -- main API

Concierge::Users::Meta -- field definitions and validators

Concierge::Users::File, Concierge::Users::YAML -- alternative backends

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.