NAME

DBIO::DuckDB::Util - Shared DuckDB-specific helper functions for DBIO

VERSION

version 0.900007

SYNOPSIS

use DBIO::DuckDB::Util qw(mask_error_details);

my $message = mask_error_details(
  q{Constraint Error: Duplicate key "email: a@b.c" violates unique constraint.}
);
# Constraint Error: Duplicate key "email: ***" violates unique constraint.

DESCRIPTION

Helpers of the DuckDB driver that do not belong to one class.

METHODS

mask_error_details

my $message = mask_error_details($message);
my $message = mask_error_details($message, \@binds);
my $message = mask_error_details($message, \@binds, $statement);

DuckDB writes the offending value into its error text, also when the value was a bind: Could not convert string 'x' to INT32, Duplicate key "email: x" violates unique constraint.. The family's rule is that a message names keys, columns and options, never values; the engine's text is the driver's to keep to it, and this is where the driver does.

Every value in the sentences of the engine that quote one is replaced by ***, and what the caller needs to find the cause stays: the type, the column, the constraint, the table.

Conversion Error: Could not convert string '***' to INT32
Conversion Error: Type DOUBLE with value *** can't be cast because the value is out of range for the destination type INT16
Constraint Error: Duplicate key "id: ***" violates primary key constraint.
Constraint Error: Violates foreign key constraint because key "a: ***, b: ***" does not exist in the referenced table
Conversion Error: Malformed JSON at byte 1 of input: unexpected character.  Input: "***"
Conversion Error: date field value out of range: "***"
Conversion Error: Could not cast value *** to DECIMAL(4,1)
Invalid Input Error: missing ): ***

A key is written column: value for each column of the key. The columns stay where that text can be read in one way only; a value that holds , or : could be taken for one more column, so a key text with such a part, a column twice, or a bound value (\@binds) with , or : in it is masked whole ("***").

\@binds is optional: the values bound to the statement. Each one of four characters or more that is found elsewhere in the message (the name of a sequence taken from a bind, a file path) is replaced as well. Shorter values, undef and references are not looked for, since a letter or a number is part of any text; the sentences above hold those.

$statement is the text of the statement that was run. The excerpt DuckDB appends to it (\n\nLINE 1: ... and the caret line) is the caller's own statement text and stays as it is -- but only when it is DuckDB's: it must end the message, hold one line of $statement (cut with ... at either end, the line number being the one of the excerpt) and be followed by the caret line. Anything else that looks like it is part of the message, and so is a value that imitates it: all of the text is masked, the search for the bound values included. Without $statement there is no excerpt. Core's [for Statement "..." with N bind values] is appended after the masking and never reaches the masker; a text that holds it is plain text here. The storage calls this function from its _mask_error_values with the values core gives it, and core's own masking of the bound values follows; the search for the bound values above overlaps with that one and stays for the callers of this function.

A message the sentences do not know is returned as it is, and so is one without a value, CHECK constraint failed on table p with expression CHECK((c > 0)) or NOT NULL constraint failed: p.nn.

SEE ALSO

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.