NAME
DBIO::SQLite::SQLMaker - SQLite-specific SQL generation for DBIO
VERSION
version 0.900007
DESCRIPTION
SQLite-specific subclass of DBIO::SQLMaker. Disables SELECT ... FOR UPDATE locking syntax, which SQLite does not support, and renders the INSERT ... ON CONFLICT clause of the atomic upsert (ADR 0036). All other SQL generation is inherited from DBIO::SQLMaker.
This class is set as the sql_maker_class by DBIO::SQLite::Storage and is not normally instantiated directly.
METHODS
insert
Overrides "insert" in DBIO::SQLMaker to render two SQLite-specific pieces, both carried on the same $options transport as returning:
$options->{on_conflict}-- theON CONFLICTtail of an atomic upsert (ADR 0036):INSERT INTO ... VALUES ( ... ) ON CONFLICT ( ... ) DO ... [ RETURNING ... ]$options->{insert_or}-- SQLite's OR-conflict clause,'ignore'or'replace', which sits between theINSERTkeyword andINTO. This is a different mechanism fromon_conflict:INSERT OR IGNORE INTO ... VALUES ( ... ) INSERT OR REPLACE INTO ... VALUES ( ... )It is an option of this method only: "insert" in DBIO::Storage::DBI builds the options it hands down itself (
returning, andon_conflictfor "upsert" in DBIO::ResultSet) and passes nothing else on from its caller, so no ORM call ($rs->create,$row->insert) can reachinsert_or-- it is for a caller that generates the statement through the SQL maker and executes it itself.
Both keys are consumed (deleted from $options) before delegating to the generic insert. Without either, the call is passed straight through, so a plain insert is byte-for-byte what it was before.
_insert_or_clause
my $sql = $sql_maker->_insert_or_clause($insert_sql, 'ignore');
Splices SQLite's OR-conflict clause into a finished INSERT statement, turning INSERT INTO ... into INSERT OR IGNORE INTO ... or INSERT OR REPLACE INTO .... Only 'ignore' and 'replace' are accepted; any other value throws.
_insert_on_conflict
my ($sql_tail, @bind) = $sql_maker->_insert_on_conflict(\%on_conflict);
Renders the ON CONFLICT tail from the engine-neutral structure core builds in "upsert" in DBIO::ResultSet, mirroring _insert_returning:
{ target => \@cols | { constraint => $name, columns => \@cols } | 'any',
action => 'update' | 'nothing',
set => { $col => { -attempted => $col } | \'literal' | $scalar },
where => $cond }
{ -attempted => $col } is rendered as excluded.<col> -- the value the statement tried to insert. Literal \'...', literal-with-bind \[ '...', @bind ] and plain scalars (bound) are accepted as written.
where is "upsert" in DBIO::ResultSet's update_where, the conditional conflict branch, and is present only when the caller passed one. It is rendered after the SET list and before RETURNING, with its bind values spliced in at that position, and it accepts everything a SQL::Abstract condition accepts. See "_upsert_condition_sql" in DBIO::SQLMaker for the one thing that is not plain _recurse_where.
Every route to a dropped condition throws instead, because silently dropping one is the mistake this feature exists to prevent -- it leaves a perfectly valid unconditional DO UPDATE behind, with no symptom of its own. That is a where on the action => 'nothing' branch (there is no update branch for a condition to gate), an undef one (the key is set only when there is a condition), and one that renders to an empty string ({ -and => [] }).
The hashref target is upsert(..., { key => $constraint }): core resolves the constraint name once and hands down both halves. SQLite renders the columns -- its grammar has no ON CONSTRAINT form, and a DBIO constraint name is client-side add_unique_constraint metadata that need not name anything the server knows. key and the equivalent conflict_target => \@columns therefore produce identical SQL.
Two shapes throw here rather than emit something wrong:
a hashref target whose
columnsare absent or empty -- a SQLMaker has no ResultSource of its own to resolve the name against, so there is nothing to render andON CONFLICT ()would be the alternative.target => 'any'together withaction => 'update'--DO UPDATErequires a conflict target.'any'withaction => 'nothing'is fine and emits a targetlessDO NOTHING.
_upsert_attempted_sql
my $sql = $sql_maker->_upsert_attempted_sql('rank');
Spells core's engine-neutral { -attempted => $column } marker -- the value the statement tried to insert -- as this engine's reference to the attempted row: excluded.<column>.
It is the one engine-specific piece of the atomic upsert: core's "_upsert_condition_sql" in DBIO::SQLMaker has no default for it and is parameterized over it (ADR 0036 pins the token to the driver). Both halves of the statement use this method -- the set list and the conditional branch -- so the pseudo-row is spelled identically wherever it appears.
SEE ALSO
DBIO::SQLMaker - Base SQL generation class
DBIO::SQLite::Storage - Storage driver that uses this SQL maker
DBIO::SQLite - Top-level SQLite schema component
"upsert" in DBIO::ResultSet - The user-facing atomic upsert
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.