DBI::SQL::Nano(3)

📦
version 1.656 · 26 versions
, in fedora 43, fedora 44

✨ DBI::SQL::Nano ✨ — the lil baby SQL engine 💅

okay bestie, so this is the manual page for DBI::SQL::Nano(3) from the User Contributed Perl Documentation, and honestly? it's giving "tiny but mighty." buckle up 🎀

🌸 NAME 🌸

DBI::SQL::Nano — a very tiny SQL engine 🐣

🦋 SYNOPSIS 🦋

no cap, here's the whole vibe:

 BEGIN { $ENV{DBI_SQL_NANO}=1 } # forces use of Nano rather than SQL::Statement
 use DBI::SQL::Nano;
 use Data::Dumper;
 my $stmt = DBI::SQL::Nano::Statement->new(
     "SELECT bar,baz FROM foo WHERE qux = 1"
 ) or die "Couldn't parse";
 print Dumper $stmt;

💖 DESCRIPTION 💖

so <pink>DBI::SQL::Nano</pink> is literally designed to be the most minimal little SQL engine ever, for when SQL::Statement just isn't there. 🫶

and like… in most situations you're way better off installing SQL::Statement, periodt. but — and this is the tea — DBI::SQL::Nano may be faster for some very simple tasks. so there's that. ⚡

just like SQL::Statement, DBI::SQL::Nano is primarily meant to give you a SQL engine to use with some pure perl DBDs, including DBD::DBM, DBD::CSV, DBD::AnyData, and DBD::Excel. 💫

and here's the honest part: it's not of much use in and of itself. 😭 you can dump out the structure of a parsed SQL statement, but that is about it. that's the whole personality. 🙈

🌈 USAGE 🌈

🎀 Setting the DBI_SQL_NANO flag 🎀

by default, when a DBD uses DBI::SQL::Nano, the module will look to see if SQL::Statement is installed. if it is → SQL::Statement objects get used, slay. if SQL::Statement is not available → DBI::SQL::Nano objects get used. simple as that. ✨

but sometimes? you want the Nano objects even though SQL::Statement is right there. valid. 💅

to force usage of DBI::SQL::Nano objects regardless of whether SQL::Statement is available, set the environment variable DBI_SQL_NANO to 1.

you can set that environment variable in your shell before running your script (with SET or EXPORT or whatever your setup uses), or you can just set it right inside your script by putting this at the top:

 BEGIN { $ENV{DBI_SQL_NANO} = 1 }

🧚 Supported SQL syntax 🧚

here's a pseudo-BNF, bestie. square brackets [] mean optional items; angle brackets <> mean items defined elsewhere in the BNF. 📚

 statement ::=
     DROP TABLE [IF EXISTS] <table_name>
   | CREATE TABLE <table_name> <col_def_list>
   | INSERT INTO <table_name> [<insert_col_list>] VALUES <val_list>
   | DELETE FROM <table_name> [<where_clause>]
   | UPDATE <table_name> SET <set_clause> <where_clause>
   | SELECT <select_col_list> FROM <table_name> [<where_clause>]
                                                [<order_clause>]

 the optional IF EXISTS clause ::=
   * similar to MySQL - prevents errors when trying to drop
     a table that doesn't exist

 identifiers ::=
   * table and column names should be valid SQL identifiers
   * especially avoid using spaces and commas in identifiers
   * note: there is no error checking for invalid names, some
     will be accepted, others will cause parse failures

 table_name ::=
   * only one table (no multiple table operations)
   * see identifier for valid table names

 col_def_list ::=
   * a parens delimited, comma-separated list of column names
   * see identifier for valid column names
   * column types and column constraints may be included but are ignored
     e.g. these are all the same:
       (id,phrase)
       (id INT, phrase VARCHAR(40))
       (id INT PRIMARY KEY, phrase VARCHAR(40) NOT NULL)
   * you are *strongly* advised to put in column types even though
     they are ignored ... it increases portability

 insert_col_list ::=
   * a parens delimited, comma-separated list of column names
   * as in standard SQL, this is optional

 select_col_list ::=
   * a comma-separated list of column names
   * or an asterisk denoting all columns

 val_list ::=
   * a parens delimited, comma-separated list of values which can be:
      * placeholders (an unquoted question mark)
      * numbers (unquoted numbers)
      * column names (unquoted strings)
      * nulls (unquoted word NULL)
      * strings (delimited with single quote marks);
      * note: leading and trailing percent mark (%) and underscore (_)
        can be used as wildcards in quoted strings for use with
        the LIKE and CLIKE operators
      * note: escaped single quotation marks within strings are not
        supported, neither are embedded commas, use placeholders instead

 set_clause ::=
   * a comma-separated list of column = value pairs
   * see val_list for acceptable value formats

 where_clause ::=
   * a single "column/value <op> column/value" predicate, optionally
     preceded by "NOT"
   * note: multiple predicates combined with ORs or ANDs are not supported
   * see val_list for acceptable value formats
   * op may be one of:
        < > >= <= = <> LIKE CLIKE IS
   * CLIKE is a case insensitive LIKE
   * IS NULL matches against NULL and empty strings

 order_clause ::= column_name [ASC|DESC]
   * a single column optional ORDER BY clause is supported
   * as in standard SQL, if neither ASC (ascending) nor
     DESC (descending) is specified, ASC becomes the default

👑 TABLES 👑

DBI::SQL::Nano::Statement operates on exactly one table. that table gets opened by inheriting from DBI::SQL::Nano::Statement and implementing the open_table method. 🌟

 sub open_table ($$$$$)
 {
     ...
     return Your::Table->new( \%attributes );
 }

DBI::SQL::Nano::Statement_ expects a rudimentary interface to be implemented by the table object, same as SQL::Statement expects. 🧵

 package Your::Table;

 our @ISA = qw(DBI::SQL::Nano::Table);

 sub drop ($$)        { ... }
 sub fetch_row ($$$)  { ... }
 sub push_row ($$$)   { ... }
 sub push_names ($$$) { ... }
 sub truncate ($$)    { ... }
 sub seek ($$$$)      { ... }

the base class interfaces are provided by DBI::SQL::Nano::Table_ if you're relying on DBI::SQL::Nano, or by SQL::Eval::Table (see SQL::Eval for details) otherwise. 🫡

💀 BUGS AND LIMITATIONS 💀

ngl, there are no known bugs in DBI::SQL::Nano::Statement. if you find one and want to report it, please see DBI for how to report bugs. 🐛

DBI::SQL::Nano::Statement is designed to provide a minimal subset for executing SQL statements. that's the assignment and it ate. 🎯

the most important limitation might be the restriction on one table per statement. this implies that no JOINs are supported, and there cannot be any foreign key relation between tables. 😭

the where clause evaluation of DBI::SQL::Nano::Statement is very slow (SQL::Statement uses a precompiled evaluation). 💤

INSERT can handle only one row per statement. to insert multiple rows, use placeholders as explained in DBI. 📝

the DBI::SQL::Nano parser is very limited and does not support any additional syntax such as brackets, comments, functions, aggregations etc. 🙅‍♀️

and in contrast to SQL::Statement, temporary tables are not supported. 💔

🫶 ACKNOWLEDGEMENTS 🫶

Tim Bunce provided the original idea for this module, helped me out of the tangled trap of namespaces, and provided help and advice all along the way. 💜 although I wrote it from the ground up, it is based on Jochen Wiedmann's original design of SQL::Statement, so much of the credit for the API goes to him. 🌟

this module is originally written by Jeff Zucker < jzucker AT cpan.org > ✍️

this module is currently maintained by Jens Rehsack < jrehsack AT googlemail.com > 🛠️

Copyright (C) 2010 by Jens Rehsack, all rights reserved. Copyright (C) 2004 by Jeff Zucker, all rights reserved. 📅

you may freely distribute and/or modify this module under the terms of either the GNU General Public License (GPL) or the Artistic License, as specified in the Perl README file. 🌈

and that's the whole page, bestie!! this one shipped with perl v5.42.3, dated 2026-10-19 — go forth and parse your lil one-table queries 🎀✨💖

📦 where this page comes from