/ 
Punk-0.02
/ Punk::Model::DBI

NAME

Punk::Model::DBI - the default DBI backend for Punk models

DESCRIPTION

The shipped Punk::Model backend: plain DBI, no ORM. Connections are pooled by dsn and shared across every model that uses them, so a hundred models on one database open one handle per worker, not a hundred; a $$ check reconnects after a fork. RaiseError and AutoCommit are on, and generated SQL is prepared through prepare_cached so each distinct statement is compiled once.

It is selected by default; database backend => 'Class' swaps it for any class honouring the same six methods.

CONFIGURATION

From the database keyword:

database
    dsn      => 'dbi:SQLite:dbname=myapp.db',
    user     => $user,        # optional
    password => $pass,        # optional
    attr     => { ... };      # optional, merged into the connect attrs

CONSTRUCTOR

new

Punk::Model::DBI->new(database => \%conn, table => $t,
                      primary => $pk, columns => \@names);

Built by "_instantiate" in Punk::Model from the database options and the model's table, primary key and columns. Not called directly.

dbh

The live per-worker DBI handle for this backend's dsn, connected on first use and shared with every other backend on the same database.

THE CONTRACT

get(%key)

SELECT * ... WHERE key = ? ... - the row hashref, or undef.

search(\%filter, \%opts)

Equality filters only (WHERE a = ? AND b = ?), ORDER BY the primary key, LIMIT. $opts takes limit (default 20) and after - an opaque keyset token. Returns

{ rows => [ \%row, ... ], has_more_data => 0|1, next => $token|undef }

has_more_data comes from fetching one row past the limit; next is a url-safe, opaque encoding of the last row's primary key. Pass it back as after => $token to fetch the following page - a WHERE pk ?> continuation, so pagination is seek-based, not offset-based.

all()

search({}, {}).

create(\%data)

Inserts the known columns and returns the stored row (via RETURNING where the driver supports it - SQLite 3.35+ or PostgreSQL, detected once per connection - otherwise re-fetched by primary key).

update(\%key_and_changes)

Updates the row named by the primary key with the remaining columns; returns the stored row.

delete(%key)

Deletes and returns the affected row count.

SEE ALSO

Punk::Model, Punk, DBI.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)