Changes for version v2.0.5 - 2026-11-08
- The successor to 1.6.5: a rewrite in modern Perl.
- The reference and the how-to ship as POD manuals, so MetaCPAN and perldoc have them with the modules (roadmap 2026-0001).
- Code written for 1.x needs changes to run. "Upgrading from 1.x", in DBIx::Squirrel::Manual::Reference, lists them. To stay on 1.x, which supports older Perls, install its last version: cpanm DBIx::Squirrel@1.6.5. Its code is archived at https://github.com/nukopian/DBIx-Squirrel-1.
- Requires Perl 5.36 or later. Compress::Bzip2, Crypt::CBC, Dotenv, JSON::Syck and YAML::Syck are no longer dependencies, and loading the module no longer reads a .env file.
- Placeholders in the styles ?, ?1, :1, $1, :name and $name, one style to a statement, each rewritten as ? for the DBI. Quoted strings and identifiers, comments, casts and PostgreSQL's dollar-quoted bodies are left alone, read by the database's rules; the ekorn_dialect attribute names the database behind DBD::ODBC or DBD::Proxy. DBD::Pg's placeholder options are followed. Comments are passed on to the database, where 1.x removed them.
- A numbered or named placeholder takes one value wherever it appears. Numbers are written in the digits 0-9: a digit of another script is part of a name, there and in get_column, pluck and bind_param, rather than read as 0. Named values come as pairs or in a hash reference, with or without the sigil, and an array reference stands for the values in it. Values that don't match the placeholders croak, and so does executing a statement with some left unbound.
- A placeholder with "..." before it, such as ...:ids or ...?, takes a list, written as a ? for each of its values, for IN and anywhere else SQL takes a list. The statement is prepared with its values, by do, the select methods, iterate, results and Sugar's functions; prepare and prepare_cached croak given one, and so do an empty list and a list holding a reference. To a statement whose one value is a list, a single array reference is the list. An iterator's reset prepares the statement again for a list of another length.
- A statement can be a string, lines in an array reference, a code reference returning either, or a statement handle.
- do and the select methods take bind values without the attributes in front. do returns what the DBI's do returns, in any context: 1.x also returned the statement handle in list context.
- connect and prepare croak if they fail, whatever RaiseError says. connect clones a database handle given in place of a data source.
- Errors, and the DBI's warnings, are reported at the line that called DBIx::Squirrel, naming the method called, as plain DBI reports them.
- iterate returns a DBIx::Squirrel::Iterator, replacing DBIx::Squirrel::it, with next, all, single, reset, count, column_names and sth, and no aliases. next no longer sets $_, and single croaks on a second result, where 1.x warned. Rows are fetched 100 at a time, in the shape the ekorn_slice attribute gives, replacing slice, cache_size and their defaults; all, without stages, fetches the rest at once, close to the DBI's own speed. column_names gives the statement's column names, read when it's executed, as DBD::mysql gives none once the last row is fetched.
- Stages, 1.x's transformations, follow the bind values. Each takes a value as its argument and in $_, and returns nothing to drop it, one value, or several. Stop, from DBIx::Squirrel::Stop, ends a pipeline early, and DBIx::Squirrel::Context gives a stage its iterator, result_number and result_original.
- DBIx::Squirrel::Pipeline runs any values through stages, and pipe and tap run a database or statement handle through them. A pipeline's stages method returns its stages, to give wherever stages go, with more after them.
- Once a stage dies, an iterator or result set has ended: next and all return nothing more, and the statement is finished; reset runs it again from the start.
- gather, from DBIx::Squirrel::Gather, makes a stage afresh for each run of its pipeline, from a block returning the stage and, optionally, a function called once the values run out, whose values go through the rest of the stages. A stage can batch rows, make one value from all of them, or keep a count that starts again on each execution.
- Canned stages, each module exporting its usual ones: DBIx::Squirrel::Stages::Flow's take and drop, with take_while and drop_while on request; DBIx::Squirrel::Stages::Rows's pluck and as_hash, for rows of any shape; DBIx::Squirrel::Stages::Batch's batch and collect, passing values on in batches, or all at once; and DBIx::Squirrel::Stages::Taps's peek and count_into, with dump_to on request, looking at values as they go by.
- The pipeline is Ekorn::Pipeline, a distribution of its own, which began here, and which DBIx::Squirrel requires, from v0.1.1 up to, but not including, v0.2.0. DBIx::Squirrel::Pipeline, Stop, Gather and Pipes, and the stages in DBIx::Squirrel::Stages::Flow, Batch and Taps, are DBIx::Squirrel's names for its modules, and stay: each is a subclass of Ekorn's, or exports Ekorn's functions, from a list of its own. A stage that catches errors throws a stop on if it isa Ekorn::Pipeline::Stop, which every stop is, including those the canned stages throw.
- results returns a DBIx::Squirrel::Results, replacing DBIx::Squirrel::rs, whose rows are DBIx::Squirrel::Result objects, replacing DBIx::Squirrel::rc: one class for each list of column names, with a method for each column, in lower case. get_column takes a name or a position, and the ekorn_result_class attribute sets the rows' base class.
- DBIx::Squirrel::Sugar replaces database_entities: a function for each database, connected when it's first used, and for each statement, with stages of its own.
- prepare_cached keeps apart statements rewritten the same, such as SELECT :a, :b and SELECT :b, :a, and never hands out a handle an iterator is part way through.
- The ekorn_finish_active attribute finishes a statement still active before executing it again.
- Attributes starting ekorn_ aren't passed on to the DBI. Given to connect, they're the defaults for every statement the handle prepares.
- use DBIx::Squirrel takes the names the DBI exports, such as :sql_types, as use DBI does.
- The reference and the how-to ship as POD, DBIx::Squirrel::Manual::Reference and DBIx::Squirrel::Manual::HowTo, made from their Markdown, so MetaCPAN and perldoc have them with the modules (roadmap 2026-0001).
- SECURITY.md says how to report a vulnerability, privately, and CONTRIBUTING.md how to report a bug or ask for a feature; the distribution takes issues, not pull requests.
- Gone, as out of scope: DBIx::Squirrel::Crypt::Fernet, the DBIx::Squirrel::Transform modules for JSON and YAML, load_tuples, and the file and encoding helpers in DBIx::Squirrel::util. Those for Data::Dumper and IO give way to dump_to and peek.
Documentation
DBIx::Squirrel how-to
DBIx::Squirrel reference
Modules
DBI, minus the boilerplate, plus a pipeline
what a stage can ask about the result it's making
report the DBI's errors at the caller's line
a stage made afresh for each run, told when the values run out
an iterator over a statement's results
run values through a list of stages
the pipe and tap methods of DBIx::Squirrel's handles
find the placeholders in a statement, and match values to them
the base class of the rows a result set hands out
an iterator handing out rows as objects
stages gathering values: batch and collect
stages taking or dropping values: take, drop, take_while and drop_while
stages reshaping rows: pluck and as_hash
stages run for their side effects: peek, count_into and dump_to
end a DBIx::Squirrel pipeline early
a function for each database, and each statement
helpers shared by DBIx::Squirrel's modules
DBIx::Squirrel's database handle class
DBIx::Squirrel's statement handle class