NAME
DBIO::Util - Internal utility functions for DBIO
VERSION
version 0.900004
METHODS
assert_class_name
my $class = DBIO::Util::assert_class_name($name);Returns $name when it is a class name: Perl identifiers joined by ::, the first one not starting with a digit. Anything else -- a file path, a name with spaces, .., an empty or undefined value -- throws '...' is not a class name. Class names are class names; every place that turns a string into a loaded class ("ensure_class_loaded" in DBIO::Componentised, the require of a configured class) asks this first.
assert_identifier_text
DBIO::Util::assert_identifier_text("The connect key 'schema'", $name);Returns $name when it can be an identifier handed to a driver: no ;, no line break (\n, \r) and no NUL in it. Otherwise throws a DBIO::Exception that starts with the description $what and never contains the value. Schema names, extension names and library names are identifiers (ADR 0077); this is the one check core makes of them. Whether the rest (a quote, a blank, a backslash) can be written is the driver's to answer, by quoting the name as an identifier or by refusing it.
assert_class_isa
DBIO::Util::assert_class_isa(pool_type => $class, 'DBIO::Replicated::Pool');Throws unless the loaded class $class is a $base (or a subclass of it); $what names the setting in the message. Returns $class. For a class a setting names and the code instantiates: a pool is a pool, a storage class is a storage.
mask_bound_values
my $text = mask_bound_values($text, \@values, $quote);The text of an error with the bound values of the statement taken out (ADR 0075): every value that has at least four characters as a string is replaced by ***. A value is looked for as it was written and as $quote writes it -- once with and once without the outer quotation marks, which finds the doubled quote of '' and the \' escape of an engine that quotes with a backslash. The longest form goes first, so a value that holds another is masked as a whole. A value of three characters or fewer stays in the text: it is too short to tell from the words around it, and the rules for those belong to the driver of the engine.
@values are plain values; undef and a reference that is no plain value (is_plain_value) are skipped, an object with a stringification counts as its string. $quote is optional, a coderef that quotes a value as the engine does; one that dies is left out. Returns $text unchanged when it is undef or a reference.
mask_bound_values("Duplicate entry 'geheim-1' for key 'name'", ['geheim-1'])
# Duplicate entry '***' for key 'name'masked_longmess
my $trace = DBIO::Util::masked_longmess("something went wrong");Returns a message with a stack trace, in the form of "longmess" in Carp: MESSAGE at FILE line N. and a line SUB(ARGS) called at FILE line N for each frame above the place the trace starts at, arguments shown as Carp shows them (numbers bare, strings quoted and escaped, cut at $Carp::MaxArgLen, no more than $Carp::MaxArgNums of them). A reference as the message is returned as it came.
Every argument that is no reference is looked through for what the connect info of the live frames names -- the arguments of connect and connection on a DBIO::Schema, a dbi: DSN with a user name and a password in any frame -- before it is formatted: a password is shown as *** wherever an argument repeats it, and so is a password inside a DSN, under a password, passwd, pwd or pass key, or in a URI. An SQL statement among the arguments reads password = *** where it said password = ?.
DBIO builds its own traces with it, and a driver that writes one of its own (a confess, cluck or longmess) calls these functions instead of Carp's. It reads $Carp::CarpLevel, %Carp::Internal, %Carp::CarpInternal, $Carp::MaxArgLen, $Carp::MaxArgNums, $Carp::MaxEvalLen and $Carp::RefArgFormatter as Carp documents them; it does not look at $Carp::Verbose, and it replaces nothing of Carp.
What it does not cover: a trace Carp writes of its own accord -- a croak under $Carp::Verbose, a confess in code that is not DBIO's -- shows its arguments as Carp does, and so does a trace outside of DBIO; and a password that reaches DBIO in no argument -- from a DBIO::AccessBroker, a connection coderef or the environment -- is not known to it.
masked_confess
DBIO::Util::masked_confess("something went wrong");Dies with the message and stack trace of "masked_longmess", as "confess" in Carp does. The place the trace starts at is the call of masked_confess itself.
masked_cluck
DBIO::Util::masked_cluck("something looks wrong");Warns with the message and stack trace of "masked_longmess", as "cluck" in Carp does. The place the trace starts at is the call of masked_cluck itself.
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.