/ 
Punk-Observe-0.02
/ Punk::Observe::Backend::SQLite

NAME

Punk::Observe::Backend::SQLite - the default configuration store

SYNOPSIS

plugin 'Observe' => {
    guard => 'Web::Auth#observe_admin',
    store => '/var/lib/punk-observe',
    db    => 'dbi:SQLite:dbname=/var/lib/punk-observe/config.db',
};

DESCRIPTION

The default. A self-hosted single-node installation is the case this distribution is built for, and for a few dozen rows of configuration a file beside the store is the right database - it needs no server, no user, and no second thing to back up.

Punk::Observe::Backend::Pg is the option for an installation that already runs PostgreSQL and would rather have one database than two.

What this turns on

foreign_keys, which SQLite leaves off for compatibility - so without it every REFERENCES in the schema is decoration, and a panel outliving its deleted dashboard surfaces as a render failure a long way from the cause.

journal_mode = WAL, so the request drawing a page and the worker running a migration do not block each other, and busy_timeout, so the one that loses waits instead of failing.

The lock is the transaction

SQLite has no advisory lock. migrate therefore takes the write lock itself, with BEGIN IMMEDIATE rather than the deferred default: deferred would let two workers both begin, both read version 0, and one fail partway through applying the same migration. Immediate makes them serialise.

It is taken through begin_work, with sqlite_use_immediate_transaction set so that begin_work means BEGIN IMMEDIATE. Issuing the BEGIN as a statement instead leaves a transaction DBI does not know it has, and a transaction nobody commits is a connection holding the write lock for the rest of its life - which with four workers is four processes each pinning the database, and every write anywhere answering "database is locked" with nothing visibly contending.

If the caller already has a transaction open, this joins it rather than nesting - SQLite has no nested transactions, and the alternative is a commit that silently ends somebody else's.

METHODS

Everything is inherited from Punk::Observe::Backend. This class exists to say what the dialect needs.

SEE ALSO

Punk::Observe::Backend

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under the Artistic License 2.0.