1DBI::SQL::Nano(3)     User Contributed Perl Documentation    DBI::SQL::Nano(3)
2
3
4

NAME

6       DBI::SQL::Nano - a very tiny SQL engine
7

SYNOPSIS

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

DESCRIPTION

18       "DBI::SQL::Nano" is meant as a very minimal SQL engine for use in
19       situations where SQL::Statement is not available. In most situations
20       you are better off installing SQL::Statement although DBI::SQL::Nano
21       may be faster for some very simple tasks.
22
23       DBI::SQL::Nano, like SQL::Statement is primarily intended to provide a
24       SQL engine for use with some pure perl DBDs including DBD::DBM,
25       DBD::CSV, DBD::AnyData, and DBD::Excel. It is not of much use in and of
26       itself.  You can dump out the structure of a parsed SQL statement, but
27       that is about it.
28

USAGE

30   Setting the DBI_SQL_NANO flag
31       By default, when a "DBD" uses "DBI::SQL::Nano", the module will look to
32       see if "SQL::Statement" is installed. If it is, SQL::Statement objects
33       are used.  If SQL::Statement is not available, DBI::SQL::Nano objects
34       are used.
35
36       In some cases, you may wish to use DBI::SQL::Nano objects even if
37       SQL::Statement is available.  To force usage of DBI::SQL::Nano objects
38       regardless of the availability of SQL::Statement, set the environment
39       variable DBI_SQL_NANO to 1.
40
41       You can set the environment variable in your shell prior to running
42       your script (with SET or EXPORT or whatever), or else you can set it in
43       your script by putting this at the top of the script:
44
45        BEGIN { $ENV{DBI_SQL_NANO} = 1 }
46
47   Supported SQL syntax
48        Here's a pseudo-BNF.  Square brackets [] indicate optional items;
49        Angle brackets <> indicate items defined elsewhere in the BNF.
50
51         statement ::=
52             DROP TABLE [IF EXISTS] <table_name>
53           | CREATE TABLE <table_name> <col_def_list>
54           | INSERT INTO <table_name> [<insert_col_list>] VALUES <val_list>
55           | DELETE FROM <table_name> [<where_clause>]
56           | UPDATE <table_name> SET <set_clause> <where_clause>
57           | SELECT <select_col_list> FROM <table_name> [<where_clause>]
58                                                        [<order_clause>]
59
60         the optional IF EXISTS clause ::=
61           * similar to MySQL - prevents errors when trying to drop
62             a table that doesn't exist
63
64         identifiers ::=
65           * table and column names should be valid SQL identifiers
66           * especially avoid using spaces and commas in identifiers
67           * note: there is no error checking for invalid names, some
68             will be accepted, others will cause parse failures
69
70         table_name ::=
71           * only one table (no multiple table operations)
72           * see identifier for valid table names
73
74         col_def_list ::=
75           * a parens delimited, comma-separated list of column names
76           * see identifier for valid column names
77           * column types and column constraints may be included but are ignored
78             e.g. these are all the same:
79               (id,phrase)
80               (id INT, phrase VARCHAR(40))
81               (id INT PRIMARY KEY, phrase VARCHAR(40) NOT NULL)
82           * you are *strongly* advised to put in column types even though
83             they are ignored ... it increases portability
84
85         insert_col_list ::=
86           * a parens delimited, comma-separated list of column names
87           * as in standard SQL, this is optional
88
89         select_col_list ::=
90           * a comma-separated list of column names
91           * or an asterisk denoting all columns
92
93         val_list ::=
94           * a parens delimited, comma-separated list of values which can be:
95              * placeholders (an unquoted question mark)
96              * numbers (unquoted numbers)
97              * column names (unquoted strings)
98              * nulls (unquoted word NULL)
99              * strings (delimited with single quote marks);
100              * note: leading and trailing percent mark (%) and underscore (_)
101                can be used as wildcards in quoted strings for use with
102                the LIKE and CLIKE operators
103              * note: escaped single quotation marks within strings are not
104                supported, neither are embedded commas, use placeholders instead
105
106         set_clause ::=
107           * a comma-separated list of column = value pairs
108           * see val_list for acceptable value formats
109
110         where_clause ::=
111           * a single "column/value <op> column/value" predicate, optionally
112             preceded by "NOT"
113           * note: multiple predicates combined with ORs or ANDs are not supported
114           * see val_list for acceptable value formats
115           * op may be one of:
116                < > >= <= = <> LIKE CLIKE IS
117           * CLIKE is a case insensitive LIKE
118
119         order_clause ::= column_name [ASC|DESC]
120           * a single column optional ORDER BY clause is supported
121           * as in standard SQL, if neither ASC (ascending) nor
122             DESC (descending) is specified, ASC becomes the default
123

TABLES

125       DBI::SQL::Nano::Statement operates on exactly one table. This table
126       will be opened by inherit from DBI::SQL::Nano::Statement and implements
127       the "open_table" method.
128
129         sub open_table ($$$$$)
130         {
131             ...
132             return Your::Table->new( \%attributes );
133         }
134
135       DBI::SQL::Nano::Statement_ expects a rudimentary interface is
136       implemented by the table object, as well as SQL::Statement expects.
137
138         package Your::Table;
139
140         use vars qw(@ISA);
141         @ISA = qw(DBI::SQL::Nano::Table);
142
143         sub drop ($$)        { ... }
144         sub fetch_row ($$$)  { ... }
145         sub push_row ($$$)   { ... }
146         sub push_names ($$$) { ... }
147         sub truncate ($$)    { ... }
148         sub seek ($$$$)      { ... }
149
150       The base class interfaces are provided by DBI::SQL::Nano::Table_ in
151       case of relying on DBI::SQL::Nano or SQL::Eval::Table (see SQL::Eval
152       for details) otherwise.
153

BUGS AND LIMITATIONS

155       There are no known bugs in DBI::SQL::Nano::Statement. If you find a one
156       and want to report, please see DBI for how to report bugs.
157
158       DBI::SQL::Nano::Statement is designed to provide a minimal subset for
159       executing SQL statements.
160
161       The most important limitation might be the restriction on one table per
162       statement. This implies, that no JOINs are supported and there cannot
163       be any foreign key relation between tables.
164
165       The where clause evaluation of DBI::SQL::Nano::Statement is very slow
166       (SQL::Statement uses a precompiled evaluation).
167
168       INSERT can handle only one row per statement. To insert multiple rows,
169       use placeholders as explained in DBI.
170
171       The DBI::SQL::Nano parser is very limited and does not support any
172       additional syntax such as brackets, comments, functions, aggregations
173       etc.
174
175       In contrast to SQL::Statement, temporary tables are not supported.
176

ACKNOWLEDGEMENTS

178       Tim Bunce provided the original idea for this module, helped me out of
179       the tangled trap of namespaces, and provided help and advice all along
180       the way.  Although I wrote it from the ground up, it is based on Jochen
181       Wiedmann's original design of SQL::Statement, so much of the credit for
182       the API goes to him.
183
185       This module is originally written by Jeff Zucker < jzucker AT cpan.org
186       >
187
188       This module is currently maintained by Jens Rehsack < jrehsack AT
189       cpan.org >
190
191       Copyright (C) 2010 by Jens Rehsack, all rights reserved.  Copyright (C)
192       2004 by Jeff Zucker, all rights reserved.
193
194       You may freely distribute and/or modify this module under the terms of
195       either the GNU General Public License (GPL) or the Artistic License, as
196       specified in the Perl README file.
197
198
199
200perl v5.32.1                      2021-01-27                 DBI::SQL::Nano(3)
Impressum