diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..293de56 --- /dev/null +++ b/LICENSE @@ -0,0 +1,396 @@ +Terms of Perl itself + +a) the GNU General Public License as published by the Free + Software Foundation; either version 1, or (at your option) any + later version, or +b) the "Artistic License" + +---------------------------------------------------------------------------- + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + +---------------------------------------------------------------------------- + +The Artistic License + +Preamble + +The intent of this document is to state the conditions under which a Package +may be copied, such that the Copyright Holder maintains some semblance of +artistic control over the development of the package, while giving the users of the +package the right to use and distribute the Package in a more-or-less customary +fashion, plus the right to make reasonable modifications. + +Definitions: + +- "Package" refers to the collection of files distributed by the Copyright + Holder, and derivatives of that collection of files created through textual + modification. +- "Standard Version" refers to such a Package if it has not been modified, + or has been modified in accordance with the wishes of the Copyright + Holder. +- "Copyright Holder" is whoever is named in the copyright or copyrights for + the package. +- "You" is you, if you're thinking about copying or distributing this Package. +- "Reasonable copying fee" is whatever you can justify on the basis of + media cost, duplication charges, time of people involved, and so on. (You + will not be required to justify it to the Copyright Holder, but only to the + computing community at large as a market that must bear the fee.) +- "Freely Available" means that no fee is charged for the item itself, though + there may be fees involved in handling the item. It also means that + recipients of the item may redistribute it under the same conditions they + received it. + +1. You may make and give away verbatim copies of the source form of the +Standard Version of this Package without restriction, provided that you duplicate +all of the original copyright notices and associated disclaimers. + +2. You may apply bug fixes, portability fixes and other modifications derived from +the Public Domain or from the Copyright Holder. A Package modified in such a +way shall still be considered the Standard Version. + +3. You may otherwise modify your copy of this Package in any way, provided +that you insert a prominent notice in each changed file stating how and when +you changed that file, and provided that you do at least ONE of the following: + + a) place your modifications in the Public Domain or otherwise + make them Freely Available, such as by posting said modifications + to Usenet or an equivalent medium, or placing the modifications on + a major archive site such as ftp.uu.net, or by allowing the + Copyright Holder to include your modifications in the Standard + Version of the Package. + + b) use the modified Package only within your corporation or + organization. + + c) rename any non-standard executables so the names do not + conflict with standard executables, which must also be provided, + and provide a separate manual page for each non-standard + executable that clearly documents how it differs from the Standard + Version. + + d) make other distribution arrangements with the Copyright Holder. + +4. You may distribute the programs of this Package in object code or executable +form, provided that you do at least ONE of the following: + + a) distribute a Standard Version of the executables and library + files, together with instructions (in the manual page or equivalent) + on where to get the Standard Version. + + b) accompany the distribution with the machine-readable source of + the Package with your modifications. + + c) accompany any non-standard executables with their + corresponding Standard Version executables, giving the + non-standard executables non-standard names, and clearly + documenting the differences in manual pages (or equivalent), + together with instructions on where to get the Standard Version. + + d) make other distribution arrangements with the Copyright Holder. + +5. You may charge a reasonable copying fee for any distribution of this Package. +You may charge any fee you choose for support of this Package. You may not +charge a fee for this Package itself. However, you may distribute this Package in +aggregate with other (possibly commercial) programs as part of a larger +(possibly commercial) software distribution provided that you do not advertise +this Package as a product of your own. + +6. The scripts and library files supplied as input to or produced as output from +the programs of this Package do not automatically fall under the copyright of this +Package, but belong to whomever generated them, and may be sold +commercially, and may be aggregated with this Package. + +7. C or perl subroutines supplied by you and linked into this Package shall not +be considered part of this Package. + +8. The name of the Copyright Holder may not be used to endorse or promote +products derived from this software without specific prior written permission. + +9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR +PURPOSE. + +The End + diff --git a/MANIFEST b/MANIFEST new file mode 100644 index 0000000..6a20f66 --- /dev/null +++ b/MANIFEST @@ -0,0 +1,106 @@ +Changes +dbdimp.c +dbdimp.h +fts3_tokenizer.h +inc/Test/NoWarnings.pm +inc/Test/NoWarnings/Warning.pm +lib/DBD/SQLite.pm +lib/DBD/SQLite/Cookbook.pod +LICENSE +Makefile.PL +MANIFEST This list of files +MANIFEST.SKIP +ppport.h +README +SQLite.xs +sqlite3.c +sqlite3.h +sqlite3ext.h +SQLiteXS.h +t/01_compile.t +t/02_logon.t +t/03_create_table.t +t/04_insert.t +t/05_select.t +t/06_tran.t +t/07_error.t +t/08_busy.t +t/09_create_function.t +t/10_create_aggregate.t +t/12_unicode.t +t/13_create_collation.t +t/14_progress_handler.t +t/15_ak_dbd.t +t/16_column_info.t +t/17_createdrop.t +t/18_insertfetch.t +t/19_bindparam.t +t/20_blobs.t +t/21_blobtext.t +t/22_listfields.t +t/23_nulls.t +t/24_numrows.t +t/25_chopblanks.t +t/26_commit.t +t/27_metadata.t +t/28_schemachange.t +t/29_cppcomments.t +t/30_auto_rollback.t +t/31_bind_weird_number_param.t +t/32_inactive_error.t +t/33_non_latin_path.t +t/34_online_backup.t +t/35_table_info.t +t/36_hooks.t +t/37_regexp.t +t/38_empty_statement.t +t/39_foreign_keys.t +t/40_multiple_statements.t +t/41_placeholders.t +t/42_primary_key_info.t +t/43_fts3.t +t/44_rtree.t +t/45_savepoints.t +t/46_mod_perl.t +t/47_execute.t +t/48_bind_param_is_sticky.t +t/49_trace_and_profile.t +t/50_foreign_key_info.t +t/51_table_column_metadata.t +t/52_db_filename.t +t/53_status.t +t/54_literal_txn.t +t/cookbook_variance.t +t/lib/Test.pm +t/rt_15186_prepcached.t +t/rt_21406_auto_finish.t +t/rt_25371_asymmetric_unicode.t +t/rt_25460_numeric_aggregate.t +t/rt_25924_user_defined_func_unicode.t +t/rt_26775_distinct.t +t/rt_27553_prepared_cache_and_analyze.t +t/rt_29058_group_by.t +t/rt_29629_sqlite_where_length.t +t/rt_31324_full_names.t +t/rt_32889_prepare_cached_reexecute.t +t/rt_36836_duplicate_key.t +t/rt_36838_unique_and_bus_error.t +t/rt_40594_nullable.t +t/rt_48393_debug_panic_with_commit.t +t/rt_50503_fts3.t +t/rt_52573_manual_exclusive_lock.t +t/rt_53235_icu_compatibility.t +t/rt_62370_diconnected_handles_operation.t +t/rt_64177_ping_wipes_out_the_errstr.t +t/rt_67581_bind_params_mismatch.t +t/rt_71311_bind_col_and_unicode.t +t/rt_73159_fts_tokenizer_segfault.t +t/rt_73787_exponential_buffer_overflow.t +t/rt_77724_primary_key_with_a_whitespace.t +t/rt_78833_utf8_flag_for_column_names.t +t/rt_81536_multi_column_primary_key_info.t +typemap +util/getsqlite.pl +xt/meta.t +xt/pmv.t +xt/pod.t diff --git a/README b/README new file mode 100644 index 0000000..c1577c2 --- /dev/null +++ b/README @@ -0,0 +1,1320 @@ +NAME + DBD::SQLite - Self-contained RDBMS in a DBI Driver + +SYNOPSIS + use DBI; + my $dbh = DBI->connect("dbi:SQLite:dbname=$dbfile","",""); + +DESCRIPTION + SQLite is a public domain file-based relational database engine that you + can find at . + + DBD::SQLite is a Perl DBI driver for SQLite, that includes the entire + thing in the distribution. So in order to get a fast transaction capable + RDBMS working for your perl project you simply have to install this + module, and nothing else. + + SQLite supports the following features: + + Implements a large subset of SQL92 + See for details. + + A complete DB in a single disk file + Everything for your database is stored in a single disk file, making + it easier to move things around than with DBD::CSV. + + Atomic commit and rollback + Yes, DBD::SQLite is small and light, but it supports full + transactions! + + Extensible + User-defined aggregate or regular functions can be registered with + the SQL parser. + + There's lots more to it, so please refer to the docs on the SQLite web + page, listed above, for SQL details. Also refer to DBI for details on + how to use DBI itself. The API works like every DBI module does. + However, currently many statement attributes are not implemented or are + limited by the typeless nature of the SQLite database. + +NOTABLE DIFFERENCES FROM OTHER DRIVERS + Database Name Is A File Name + SQLite creates a file per a database. You should pass the "path" of the + database file (with or without a parent directory) in the DBI connection + string (as a database "name"): + + my $dbh = DBI->connect("dbi:SQLite:dbname=$dbfile","",""); + + The file is opened in read/write mode, and will be created if it does + not exist yet. + + Although the database is stored in a single file, the directory + containing the database file must be writable by SQLite because the + library will create several temporary files there. + + If the filename $dbfile is ":memory:", then a private, temporary + in-memory database is created for the connection. This in-memory + database will vanish when the database connection is closed. It is handy + for your library tests. + + Note that future versions of SQLite might make use of additional special + filenames that begin with the ":" character. It is recommended that when + a database filename actually does begin with a ":" character you should + prefix the filename with a pathname such as "./" to avoid ambiguity. + + If the filename $dbfile is an empty string, then a private, temporary + on-disk database will be created. This private database will be + automatically deleted as soon as the database connection is closed. + + Accessing A Database With Other Tools + To access the database from the command line, try using "dbish" which + comes with the DBI::Shell module. Just type: + + dbish dbi:SQLite:foo.db + + On the command line to access the file foo.db. + + Alternatively you can install SQLite from the link above without + conflicting with DBD::SQLite and use the supplied "sqlite3" command line + tool. + + Blobs + As of version 1.11, blobs should "just work" in SQLite as text columns. + However this will cause the data to be treated as a string, so SQL + statements such as length(x) will return the length of the column as a + NUL terminated string, rather than the size of the blob in bytes. In + order to store natively as a BLOB use the following code: + + use DBI qw(:sql_types); + my $dbh = DBI->connect("dbi:SQLite:dbfile","",""); + + my $blob = `cat foo.jpg`; + my $sth = $dbh->prepare("INSERT INTO mytable VALUES (1, ?)"); + $sth->bind_param(1, $blob, SQL_BLOB); + $sth->execute(); + + And then retrieval just works: + + $sth = $dbh->prepare("SELECT * FROM mytable WHERE id = 1"); + $sth->execute(); + my $row = $sth->fetch; + my $blobo = $row->[1]; + + # now $blobo == $blob + + Functions And Bind Parameters + As of this writing, a SQL that compares a return value of a function + with a numeric bind value like this doesn't work as you might expect. + + my $sth = $dbh->prepare(q{ + SELECT bar FROM foo GROUP BY bar HAVING count(*) > ?; + }); + $sth->execute(5); + + This is because DBD::SQLite assumes that all the bind values are text + (and should be quoted) by default. Thus the above statement becomes like + this while executing: + + SELECT bar FROM foo GROUP BY bar HAVING count(*) > "5"; + + There are three workarounds for this. + + Use bind_param() explicitly + As shown above in the "BLOB" section, you can always use + "bind_param()" to tell the type of a bind value. + + use DBI qw(:sql_types); # Don't forget this + + my $sth = $dbh->prepare(q{ + SELECT bar FROM foo GROUP BY bar HAVING count(*) > ?; + }); + $sth->bind_param(1, 5, SQL_INTEGER); + $sth->execute(); + + Add zero to make it a number + This is somewhat weird, but works anyway. + + my $sth = $dbh->prepare(q{ + SELECT bar FROM foo GROUP BY bar HAVING count(*) > (? + 0); + }); + $sth->execute(5); + + Set "sqlite_see_if_its_a_number" database handle attribute + As of version 1.32_02, you can use "sqlite_see_if_its_a_number" to + let DBD::SQLite to see if the bind values are numbers or not. + + $dbh->{sqlite_see_if_its_a_number} = 1; + my $sth = $dbh->prepare(q{ + SELECT bar FROM foo GROUP BY bar HAVING count(*) > ?; + }); + $sth->execute(5); + + You can set it to true when you connect to a database. + + my $dbh = DBI->connect('dbi:SQLite:foo', undef, undef, { + AutoCommit => 1, + RaiseError => 1, + sqlite_see_if_its_a_number => 1, + }); + + This is the most straightforward solution, but as noted above, + existing data in your databases created by DBD::SQLite have not + always been stored as numbers, so this *might* cause other obscure + problems. Use this sparingly when you handle existing databases. If + you handle databases created by other tools like native "sqlite3" + command line tool, this attribute would help you. + + Placeholders + SQLite supports several placeholder expressions, including "?" and + ":AAAA". Consult the DBI and sqlite documentation for details. + + + + Note that a question mark actually means a next unused (numbered) + placeholder. You're advised not to use it with other (numbered or named) + placeholders to avoid confusion. + + my $sth = $dbh->prepare( + 'update TABLE set a=?1 where b=?2 and a IS NOT ?1' + ); + $sth->execute(1, 2); + + Foreign Keys + BE PREPARED! WOLVES APPROACH!! + + SQLite has started supporting foreign key constraints since 3.6.19 + (released on Oct 14, 2009; bundled in DBD::SQLite 1.26_05). To be exact, + SQLite has long been able to parse a schema with foreign keys, but the + constraints has not been enforced. Now you can issue a pragma actually + to enable this feature and enforce the constraints. + + To do this, issue the following pragma (see below), preferably as soon + as you connect to a database and you're not in a transaction: + + $dbh->do("PRAGMA foreign_keys = ON"); + + And you can explicitly disable the feature whenever you like by turning + the pragma off: + + $dbh->do("PRAGMA foreign_keys = OFF"); + + As of this writing, this feature is disabled by default by the sqlite + team, and by us, to secure backward compatibility, as this feature may + break your applications, and actually broke some for us. If you have + used a schema with foreign key constraints but haven't cared them much + and supposed they're always ignored for SQLite, be prepared, and please + do extensive testing to ensure that your applications will continue to + work when the foreign keys support is enabled by default. It is very + likely that the sqlite team will turn it default-on in the future, and + we plan to do it NO LATER THAN they do so. + + See for details. + + Pragma + SQLite has a set of "Pragma"s to modifiy its operation or to query for + its internal data. These are specific to SQLite and are not likely to + work with other DBD libraries, but you may find some of these are quite + useful. DBD::SQLite actually sets some (like "show_datatypes") for you + when you connect to a database. See + for details. + + Transactions + DBI/DBD::SQLite's transactions may be a bit confusing. They behave + differently according to the status of the "AutoCommit" flag: + + When the AutoCommit flag is on + You're supposed to always use the auto-commit mode, except you + explicitly begin a transaction, and when the transaction ended, + you're supposed to go back to the auto-commit mode. To begin a + transaction, call "begin_work" method, or issue a "BEGIN" statement. + To end it, call "commit/rollback" methods, or issue the + corresponding statements. + + $dbh->{AutoCommit} = 1; + + $dbh->begin_work; # or $dbh->do('BEGIN TRANSACTION'); + + # $dbh->{AutoCommit} is turned off temporarily during a transaction; + + $dbh->commit; # or $dbh->do('COMMIT'); + + # $dbh->{AutoCommit} is turned on again; + + When the AutoCommit flag is off + You're supposed to always use the transactional mode, until you + explicitly turn on the AutoCommit flag. You can explicitly issue a + "BEGIN" statement (only when an actual transaction has not begun + yet) but you're not allowed to call "begin_work" method (if you + don't issue a "BEGIN", it will be issued internally). You can commit + or roll it back freely. Another transaction will automatically + begins if you execute another statement. + + $dbh->{AutoCommit} = 0; + + # $dbh->do('BEGIN TRANSACTION') is not necessary, but possible + + ... + + $dbh->commit; # or $dbh->do('COMMIT'); + + # $dbh->{AutoCommit} stays intact; + + $dbh->{AutoCommit} = 1; # ends the transactional mode + + This "AutoCommit" mode is independent from the autocommit mode of the + internal SQLite library, which always begins by a "BEGIN" statement, and + ends by a "COMMIT" or a . + + Transaction and Database Locking + Transaction by "AutoCommit" or "begin_work" is nice and handy, but + sometimes you may get an annoying "database is locked" error. This + typically happens when someone begins a transaction, and tries to write + to a database while other person is reading from the database (in + another transaction). You might be surprised but SQLite doesn't lock a + database when you just begin a normal (deferred) transaction to maximize + concurrency. It reserves a lock when you issue a statement to write, but + until you actually try to write with a "commit" statement, it allows + other people to read from the database. However, reading from the + database also requires "shared lock", and that prevents to give you the + "exclusive lock" you reserved, thus you get the "database is locked" + error, and other people will get the same error if they try to write + afterwards, as you still have a "pending" lock. "busy_timeout" doesn't + help in this case. + + To avoid this, set a transaction type explicitly. You can issue a "begin + immediate transaction" (or "begin exclusive transaction") for each + transaction, or set "sqlite_use_immediate_transaction" database handle + attribute to true (since 1.30_02) to always use an immediate transaction + (even when you simply use "begin_work" or turn off the "AutoCommit".). + + my $dbh = DBI->connect("dbi:SQLite::memory:", "", "", { + sqlite_use_immediate_transaction => 1, + }); + + Note that this works only when all of the connections use the same + (non-deferred) transaction. See for + locking details. + + "$sth->finish" and Transaction Rollback + As the DBI doc says, you almost certainly do not need to call "finish" + in DBI method if you fetch all rows (probably in a loop). However, there + are several exceptions to this rule, and rolling-back of an unfinished + "SELECT" statement is one of such exceptional cases. + + SQLite prohibits "ROLLBACK" of unfinished "SELECT" statements in a + transaction (See for details). + So you need to call "finish" before you issue a rollback. + + $sth = $dbh->prepare("SELECT * FROM t"); + $dbh->begin_work; + eval { + $sth->execute; + $row = $sth->fetch; + ... + die "For some reason"; + ... + }; + if($@) { + $sth->finish; # You need this for SQLite + $dbh->rollback; + } else { + $dbh->commit; + } + + Processing Multiple Statements At A Time + DBI's statement handle is not supposed to process multiple statements at + a time. So if you pass a string that contains multiple statements (a + "dump") to a statement handle (via "prepare" or "do"), DBD::SQLite only + processes the first statement, and discards the rest. + + Since 1.30_01, you can retrieve those ignored (unprepared) statements + via "$sth->{sqlite_unprepared_statements}". It usually contains nothing + but white spaces, but if you really care, you can check this attribute + to see if there's anything left undone. Also, if you set a + "sqlite_allow_multiple_statements" attribute of a database handle to + true when you connect to a database, "do" method automatically checks + the "sqlite_unprepared_statements" attribute, and if it finds anything + undone (even if what's left is just a single white space), it repeats + the process again, to the end. + + Performance + SQLite is fast, very fast. Matt processed his 72MB log file with it, + inserting the data (400,000+ rows) by using transactions and only + committing every 1000 rows (otherwise the insertion is quite slow), and + then performing queries on the data. + + Queries like count(*) and avg(bytes) took fractions of a second to + return, but what surprised him most of all was: + + SELECT url, count(*) as count + FROM access_log + GROUP BY url + ORDER BY count desc + LIMIT 20 + + To discover the top 20 hit URLs on the site (), and it + returned within 2 seconds. He was seriously considering switching his + log analysis code to use this little speed demon! + + Oh yeah, and that was with no indexes on the table, on a 400MHz PIII. + + For best performance be sure to tune your hdparm settings if you are + using linux. Also you might want to set: + + PRAGMA synchronous = OFF + + Which will prevent sqlite from doing fsync's when writing (which slows + down non-transactional writes significantly) at the expense of some + peace of mind. Also try playing with the cache_size pragma. + + The memory usage of SQLite can also be tuned using the cache_size + pragma. + + $dbh->do("PRAGMA cache_size = 800000"); + + The above will allocate 800M for DB cache; the default is 2M. Your sweet + spot probably lies somewhere in between. + +DRIVER PRIVATE ATTRIBUTES + Database Handle Attributes + sqlite_version + Returns the version of the SQLite library which DBD::SQLite is + using, e.g., "2.8.0". Can only be read. + + sqlite_unicode + If set to a true value, DBD::SQLite will turn the UTF-8 flag on for + all text strings coming out of the database (this feature is + currently disabled for perl < 5.8.5). For more details on the UTF-8 + flag see perlunicode. The default is for the UTF-8 flag to be turned + off. + + Also note that due to some bizarreness in SQLite's type system (see + ), if you want to retain + blob-style behavior for some columns under "$dbh->{sqlite_unicode} = + 1" (say, to store images in the database), you have to state so + explicitly using the 3-argument form of "bind_param" in DBI when + doing updates: + + use DBI qw(:sql_types); + $dbh->{sqlite_unicode} = 1; + my $sth = $dbh->prepare("INSERT INTO mytable (blobcolumn) VALUES (?)"); + + # Binary_data will be stored as is. + $sth->bind_param(1, $binary_data, SQL_BLOB); + + Defining the column type as "BLOB" in the DDL is not sufficient. + + This attribute was originally named as "unicode", and renamed to + "sqlite_unicode" for integrity since version 1.26_06. Old "unicode" + attribute is still accessible but will be deprecated in the near + future. + + sqlite_allow_multiple_statements + If you set this to true, "do" method will process multiple + statements at one go. This may be handy, but with performance + penalty. See above for details. + + sqlite_use_immediate_transaction + If you set this to true, DBD::SQLite tries to issue a "begin + immediate transaction" (instead of "begin transaction") when + necessary. See above for details. + + sqlite_see_if_its_a_number + If you set this to true, DBD::SQLite tries to see if the bind values + are number or not, and does not quote if they are numbers. See above + for details. + + Statement Handle Attributes + sqlite_unprepared_statements + Returns an unprepared part of the statement you pass to "prepare". + Typically this contains nothing but white spaces after a semicolon. + See above for details. + +METHODS + See also to the DBI documentation for the details of other common + methods. + + table_info + $sth = $dbh->table_info(undef, $schema, $table, $type, \%attr); + + Returns all tables and schemas (databases) as specified in "table_info" + in DBI. The schema and table arguments will do a "LIKE" search. You can + specify an ESCAPE character by including an 'Escape' attribute in + \%attr. The $type argument accepts a comma separated list of the + following types 'TABLE', 'VIEW', 'LOCAL TEMPORARY' and 'SYSTEM TABLE' + (by default all are returned). Note that a statement handle is returned, + and not a direct list of tables. + + The following fields are returned: + + TABLE_CAT: Always NULL, as SQLite does not have the concept of catalogs. + + TABLE_SCHEM: The name of the schema (database) that the table or view is + in. The default schema is 'main', temporary tables are in 'temp' and + other databases will be in the name given when the database was + attached. + + TABLE_NAME: The name of the table or view. + + TABLE_TYPE: The type of object returned. Will be one of 'TABLE', 'VIEW', + 'LOCAL TEMPORARY' or 'SYSTEM TABLE'. + + primary_key, primary_key_info + @names = $dbh->primary_key(undef, $schema, $table); + $sth = $dbh->primary_key_info(undef, $schema, $table, \%attr); + + You can retrieve primary key names or more detailed information. As + noted above, SQLite does not have the concept of catalogs, so the first + argument of the mothods is usually "undef", and you'll usually set + "undef" for the second one (unless you want to know the primary keys of + temporary tables). + +DRIVER PRIVATE METHODS + The following methods can be called via the func() method with a little + tweak, but the use of func() method is now discouraged by the DBI author + for various reasons (see DBI's document + for details). So, if you're using DBI + >= 1.608, use these "sqlite_" methods. If you need to use an older DBI, + you can call these like this: + + $dbh->func( ..., "(method name without sqlite_ prefix)" ); + + Exception: "sqlite_trace" should always be called as is, even with + "func()" method (to avoid conflict with DBI's trace() method). + + $dbh->func( ..., "sqlite_trace"); + + $dbh->sqlite_last_insert_rowid() + This method returns the last inserted rowid. If you specify an INTEGER + PRIMARY KEY as the first column in your table, that is the column that + is returned. Otherwise, it is the hidden ROWID column. See the sqlite + docs for details. + + Generally you should not be using this method. Use the DBI + last_insert_id method instead. The usage of this is: + + $h->last_insert_id($catalog, $schema, $table_name, $field_name [, \%attr ]) + + Running "$h->last_insert_id("","","","")" is the equivalent of running + "$dbh->sqlite_last_insert_rowid()" directly. + + $dbh->sqlite_busy_timeout() + Retrieve the current busy timeout. + + $dbh->sqlite_busy_timeout( $ms ) + Set the current busy timeout. The timeout is in milliseconds. + + $dbh->sqlite_create_function( $name, $argc, $code_ref ) + This method will register a new function which will be usable in an SQL + query. The method's parameters are: + + $name + The name of the function. This is the name of the function as it + will be used from SQL. + + $argc + The number of arguments taken by the function. If this number is -1, + the function can take any number of arguments. + + $code_ref + This should be a reference to the function's implementation. + + For example, here is how to define a now() function which returns the + current number of seconds since the epoch: + + $dbh->sqlite_create_function( 'now', 0, sub { return time } ); + + After this, it could be use from SQL as: + + INSERT INTO mytable ( now() ); + + REGEXP function + SQLite includes syntactic support for an infix operator 'REGEXP', but + without any implementation. The "DBD::SQLite" driver automatically + registers an implementation that performs standard perl regular + expression matching, using current locale. So for example you can search + for words starting with an 'A' with a query like + + SELECT * from table WHERE column REGEXP '\bA\w+' + + If you want case-insensitive searching, use perl regex flags, like this + : + + SELECT * from table WHERE column REGEXP '(?i:\bA\w+)' + + The default REGEXP implementation can be overridden through the + "create_function" API described above. + + Note that regexp matching will not use SQLite indices, but will iterate + over all rows, so it could be quite costly in terms of performance. + + $dbh->sqlite_create_collation( $name, $code_ref ) + This method manually registers a new function which will be usable in an + SQL query as a COLLATE option for sorting. Such functions can also be + registered automatically on demand: see section "COLLATION FUNCTIONS" + below. + + The method's parameters are: + + $name + The name of the function exposed to SQL. + + $code_ref + Reference to the function's implementation. The driver will check + that this is a proper sorting function. + + $dbh->sqlite_collation_needed( $code_ref ) + This method manually registers a callback function that will be invoked + whenever an undefined collation sequence is required from an SQL + statement. The callback is invoked as + + $code_ref->($dbh, $collation_name) + + and should register the desired collation using + "sqlite_create_collation". + + An initial callback is already registered by "DBD::SQLite", so for most + common cases it will be simpler to just add your collation sequences in + the %DBD::SQLite::COLLATION hash (see section "COLLATION FUNCTIONS" + below). + + $dbh->sqlite_create_aggregate( $name, $argc, $pkg ) + This method will register a new aggregate function which can then be + used from SQL. The method's parameters are: + + $name + The name of the aggregate function, this is the name under which the + function will be available from SQL. + + $argc + This is an integer which tells the SQL parser how many arguments the + function takes. If that number is -1, the function can take any + number of arguments. + + $pkg + This is the package which implements the aggregator interface. + + The aggregator interface consists of defining three methods: + + new() + This method will be called once to create an object which should be + used to aggregate the rows in a particular group. The step() and + finalize() methods will be called upon the reference return by the + method. + + step(@_) + This method will be called once for each row in the aggregate. + + finalize() + This method will be called once all rows in the aggregate were + processed and it should return the aggregate function's result. When + there is no rows in the aggregate, finalize() will be called right + after new(). + + Here is a simple aggregate function which returns the variance (example + adapted from pysqlite): + + package variance; + + sub new { bless [], shift; } + + sub step { + my ( $self, $value ) = @_; + + push @$self, $value; + } + + sub finalize { + my $self = $_[0]; + + my $n = @$self; + + # Variance is NULL unless there is more than one row + return undef unless $n || $n == 1; + + my $mu = 0; + foreach my $v ( @$self ) { + $mu += $v; + } + $mu /= $n; + + my $sigma = 0; + foreach my $v ( @$self ) { + $sigma += ($x - $mu)**2; + } + $sigma = $sigma / ($n - 1); + + return $sigma; + } + + $dbh->sqlite_create_aggregate( "variance", 1, 'variance' ); + + The aggregate function can then be used as: + + SELECT group_name, variance(score) + FROM results + GROUP BY group_name; + + For more examples, see the DBD::SQLite::Cookbook. + + $dbh->sqlite_progress_handler( $n_opcodes, $code_ref ) + This method registers a handler to be invoked periodically during long + running calls to SQLite. + + An example use for this interface is to keep a GUI updated during a + large query. The parameters are: + + $n_opcodes + The progress handler is invoked once for every $n_opcodes virtual + machine opcodes in SQLite. + + $code_ref + Reference to the handler subroutine. If the progress handler returns + non-zero, the SQLite operation is interrupted. This feature can be + used to implement a "Cancel" button on a GUI dialog box. + + Set this argument to "undef" if you want to unregister a previous + progress handler. + + $dbh->sqlite_commit_hook( $code_ref ) + This method registers a callback function to be invoked whenever a + transaction is committed. Any callback set by a previous call to + "sqlite_commit_hook" is overridden. A reference to the previous callback + (if any) is returned. Registering an "undef" disables the callback. + + When the commit hook callback returns zero, the commit operation is + allowed to continue normally. If the callback returns non-zero, then the + commit is converted into a rollback (in that case, any attempt to + *explicitly* call "$dbh->rollback()" afterwards would yield an error). + + $dbh->sqlite_rollback_hook( $code_ref ) + This method registers a callback function to be invoked whenever a + transaction is rolled back. Any callback set by a previous call to + "sqlite_rollback_hook" is overridden. A reference to the previous + callback (if any) is returned. Registering an "undef" disables the + callback. + + $dbh->sqlite_update_hook( $code_ref ) + This method registers a callback function to be invoked whenever a row + is updated, inserted or deleted. Any callback set by a previous call to + "sqlite_update_hook" is overridden. A reference to the previous callback + (if any) is returned. Registering an "undef" disables the callback. + + The callback will be called as + + $code_ref->($action_code, $database, $table, $rowid) + + where + + $action_code + is an integer equal to either "DBD::SQLite::INSERT", + "DBD::SQLite::DELETE" or "DBD::SQLite::UPDATE" (see "Action Codes"); + + $database + is the name of the database containing the affected row; + + $table + is the name of the table containing the affected row; + + $rowid + is the unique 64-bit signed integer key of the affected row within + that table. + + $dbh->sqlite_set_authorizer( $code_ref ) + This method registers an authorizer callback to be invoked whenever SQL + statements are being compiled by the "prepare" in DBI method. The + authorizer callback should return "DBD::SQLite::OK" to allow the action, + "DBD::SQLite::IGNORE" to disallow the specific action but allow the SQL + statement to continue to be compiled, or "DBD::SQLite::DENY" to cause + the entire SQL statement to be rejected with an error. If the authorizer + callback returns any other value, then then "prepare" call that + triggered the authorizer will fail with an error message. + + An authorizer is used when preparing SQL statements from an untrusted + source, to ensure that the SQL statements do not try to access data they + are not allowed to see, or that they do not try to execute malicious + statements that damage the database. For example, an application may + allow a user to enter arbitrary SQL queries for evaluation by a + database. But the application does not want the user to be able to make + arbitrary changes to the database. An authorizer could then be put in + place while the user-entered SQL is being prepared that disallows + everything except SELECT statements. + + The callback will be called as + + $code_ref->($action_code, $string1, $string2, $database, $trigger_or_view) + + where + + $action_code + is an integer that specifies what action is being authorized (see + "Action Codes"). + + $string1, $string2 + are strings that depend on the action code (see "Action Codes"). + + $database + is the name of the database ("main", "temp", etc.) if applicable. + + $trigger_or_view + is the name of the inner-most trigger or view that is responsible + for the access attempt, or "undef" if this access attempt is + directly from top-level SQL code. + + $dbh->sqlite_backup_from_file( $filename ) + This method accesses the SQLite Online Backup API, and will take a + backup of the named database file, copying it to, and overwriting, your + current database connection. This can be particularly handy if your + current connection is to the special :memory: database, and you wish to + populate it from an existing DB. + + $dbh->sqlite_backup_to_file( $filename ) + This method accesses the SQLite Online Backup API, and will take a + backup of the currently connected database, and write it out to the + named file. + + $dbh->sqlite_enable_load_extension( $bool ) + Calling this method with a true value enables loading (external) sqlite3 + extensions. After the call, you can load extensions like this: + + $dbh->sqlite_enable_load_extension(1); + $sth = $dbh->prepare("select load_extension('libsqlitefunctions.so')") + or die "Cannot prepare: " . $dbh->errstr(); + + $dbh->sqlite_trace( $code_ref ) + This method registers a trace callback to be invoked whenever SQL + statements are being run. + + The callback will be called as + + $code_ref->($statement) + + where + + $statement + is a UTF-8 rendering of the SQL statement text as the statement + first begins executing. + + Additional callbacks might occur as each triggered subprogram is + entered. The callbacks for triggers contain a UTF-8 SQL comment that + identifies the trigger. + + See also "TRACING" in DBI for better tracing options. + + $dbh->sqlite_profile( $code_ref ) + This method registers a profile callback to be invoked whenever a SQL + statement finishes. + + The callback will be called as + + $code_ref->($statement, $elapsed_time) + + where + + $statement + is the original statement text (without bind parameters). + + $elapsed_time + is an estimate of wall-clock time of how long that statement took to + run (in milliseconds). + + This method is considered experimental and is subject to change in + future versions of SQLite. + + See also DBI::Profile for better profiling options. + + DBD::SQLite::compile_options() + Returns an array of compile options (available since sqlite 3.6.23, + bundled in DBD::SQLite 1.30_01), or an empty array if the bundled + library is old or compiled with SQLITE_OMIT_COMPILEOPTION_DIAGS. + +DRIVER CONSTANTS + A subset of SQLite C constants are made available to Perl, because they + may be needed when writing hooks or authorizer callbacks. For accessing + such constants, the "DBD::SQLite" module must be explicitly "use"d at + compile time. For example, an authorizer that forbids any DELETE + operation would be written as follows : + + use DBD::SQLite; + $dbh->sqlite_set_authorizer(sub { + my $action_code = shift; + return $action_code == DBD::SQLite::DELETE ? DBD::SQLite::DENY + : DBD::SQLite::OK; + }); + + The list of constants implemented in "DBD::SQLite" is given below; more + information can be found ad at + . + + Authorizer Return Codes + OK + DENY + IGNORE + + Action Codes + The "set_authorizer" method registers a callback function that is + invoked to authorize certain SQL statement actions. The first parameter + to the callback is an integer code that specifies what action is being + authorized. The second and third parameters to the callback are strings, + the meaning of which varies according to the action code. Below is the + list of action codes, together with their associated strings. + + # constant string1 string2 + # ======== ======= ======= + CREATE_INDEX Index Name Table Name + CREATE_TABLE Table Name undef + CREATE_TEMP_INDEX Index Name Table Name + CREATE_TEMP_TABLE Table Name undef + CREATE_TEMP_TRIGGER Trigger Name Table Name + CREATE_TEMP_VIEW View Name undef + CREATE_TRIGGER Trigger Name Table Name + CREATE_VIEW View Name undef + DELETE Table Name undef + DROP_INDEX Index Name Table Name + DROP_TABLE Table Name undef + DROP_TEMP_INDEX Index Name Table Name + DROP_TEMP_TABLE Table Name undef + DROP_TEMP_TRIGGER Trigger Name Table Name + DROP_TEMP_VIEW View Name undef + DROP_TRIGGER Trigger Name Table Name + DROP_VIEW View Name undef + INSERT Table Name undef + PRAGMA Pragma Name 1st arg or undef + READ Table Name Column Name + SELECT undef undef + TRANSACTION Operation undef + UPDATE Table Name Column Name + ATTACH Filename undef + DETACH Database Name undef + ALTER_TABLE Database Name Table Name + REINDEX Index Name undef + ANALYZE Table Name undef + CREATE_VTABLE Table Name Module Name + DROP_VTABLE Table Name Module Name + FUNCTION undef Function Name + SAVEPOINT Operation Savepoint Name + +COLLATION FUNCTIONS + Definition + SQLite v3 provides the ability for users to supply arbitrary comparison + functions, known as user-defined "collation sequences" or "collating + functions", to be used for comparing two text values. + explains how collations + are used in various SQL expressions. + + Builtin collation sequences + The following collation sequences are builtin within SQLite : + + BINARY + Compares string data using memcmp(), regardless of text encoding. + + NOCASE + The same as binary, except the 26 upper case characters of ASCII are + folded to their lower case equivalents before the comparison is + performed. Note that only ASCII characters are case folded. SQLite + does not attempt to do full UTF case folding due to the size of the + tables required. + + RTRIM + The same as binary, except that trailing space characters are + ignored. + + In addition, "DBD::SQLite" automatically installs the following + collation sequences : + + perl + corresponds to the Perl "cmp" operator + + perllocale + Perl "cmp" operator, in a context where "use locale" is activated. + + Usage + You can write for example + + CREATE TABLE foo( + txt1 COLLATE perl, + txt2 COLLATE perllocale, + txt3 COLLATE nocase + ) + + or + + SELECT * FROM foo ORDER BY name COLLATE perllocale + + Unicode handling + If the attribute "$dbh->{sqlite_unicode}" is set, strings coming from + the database and passed to the collation function will be properly + tagged with the utf8 flag; but this only works if the "sqlite_unicode" + attribute is set before the first call to a perl collation sequence . + The recommended way to activate unicode is to set the parameter at + connection time : + + my $dbh = DBI->connect( + "dbi:SQLite:dbname=foo", "", "", + { + RaiseError => 1, + sqlite_unicode => 1, + } + ); + + Adding user-defined collations + The native SQLite API for adding user-defined collations is exposed + through methods "sqlite_create_collation" and "sqlite_collation_needed". + + To avoid calling these functions every time a $dbh handle is created, + "DBD::SQLite" offers a simpler interface through the + %DBD::SQLite::COLLATION hash : just insert your own collation functions + in that hash, and whenever an unknown collation name is encountered in + SQL, the appropriate collation function will be loaded on demand from + the hash. For example, here is a way to sort text values regardless of + their accented characters : + + use DBD::SQLite; + $DBD::SQLite::COLLATION{no_accents} = sub { + my ( $a, $b ) = map lc, @_; + tr[????????????????????????????] + [aaaaaacdeeeeiiiinoooooouuuuy] for $a, $b; + $a cmp $b; + }; + my $dbh = DBI->connect("dbi:SQLite:dbname=dbfile"); + my $sql = "SELECT ... FROM ... ORDER BY ... COLLATE no_accents"); + my $rows = $dbh->selectall_arrayref($sql); + + The builtin "perl" or "perllocale" collations are predefined in that + same hash. + + The COLLATION hash is a global registry within the current process; + hence there is a risk of undesired side-effects. Therefore, to prevent + action at distance, the hash is implemented as a "write-only" hash, that + will happily accept new entries, but will raise an exception if any + attempt is made to override or delete a existing entry (including the + builtin "perl" and "perllocale"). + + If you really, really need to change or delete an entry, you can always + grab the tied object underneath %DBD::SQLite::COLLATION --- but don't do + that unless you really know what you are doing. Also observe that + changes in the global hash will not modify existing collations in + existing database handles: it will only affect new *requests* for + collations. In other words, if you want to change the behaviour of a + collation within an existing $dbh, you need to call the + "create_collation" method directly. + +FULLTEXT SEARCH + The FTS3 extension module within SQLite allows users to create special + tables with a built-in full-text index (hereafter "FTS3 tables"). The + full-text index allows the user to efficiently query the database for + all rows that contain one or more instances of a specified word + (hereafter a "token"), even if the table contains many large documents. + + Short introduction to FTS3 + The detailed documentation for FTS3 can be found at + . Here is a very short example : + + $dbh->do(<<"") or die DBI::errstr; + CREATE VIRTUAL TABLE fts_example USING fts3(content) + + my $sth = $dbh->prepare("INSERT INTO fts_example(content) VALUES (?))"); + $sth->execute($_) foreach @docs_to_insert; + + my $results = $dbh->selectall_arrayref(<<""); + SELECT docid, snippet(content) FROM fts_example WHERE content MATCH 'foo' + + The key points in this example are : + + * The syntax for creating FTS3 tables is + + CREATE VIRTUAL TABLE USING fts3() + + where "" is a list of column names. Columns may be typed, + but the type information is ignored. If no columns are specified, + the default is a single column named "content". In addition, FTS3 + tables have an implicit column called "docid" (or also "rowid") for + numbering the stored documents. + + * Statements for inserting, updating or deleting records use the same + syntax as for regular SQLite tables. + + * Full-text searches are specified with the "MATCH" operator, and an + operand which may be a single word, a word prefix ending with '*', a + list of words, a "phrase query" in double quotes, or a boolean + combination of the above. + + * The builtin function "snippet(...)" builds a formatted excerpt of + the document text, where the words pertaining to the query are + highlighted. + + There are many more details to building and searching FTS3 tables, so we + strongly invite you to read the full documentation at at + . + + Incompatible change : starting from version 1.31, "DBD::SQLite" uses the + new, recommended "Enhanced Query Syntax" for binary set operators (AND, + OR, NOT, possibly nested with parenthesis). Previous versions of + "DBD::SQLite" used the "Standard Query Syntax" (see + ). Unfortunately this is a + compilation switch, so it cannot be tuned at runtime; however, since + FTS3 was never advertised in versions prior to 1.31, the change should + be invisible to the vast majority of "DBD::SQLite" users. If, however, + there are any applications that nevertheless were built using the + "Standard Query" syntax, they have to be migrated, because the + precedence of the "OR" operator has changed. Conversion from old to new + syntax can be automated through DBD::SQLite::FTS3Transitional, published + in a separate distribution. + + Tokenizers + The behaviour of full-text indexes strongly depends on how documents are + split into *tokens*; therefore FTS3 table declarations can explicitly + specify how to perform tokenization: + + CREATE ... USING fts3(, tokenize=) + + where "" is a sequence of space-separated words that triggers + a specific tokenizer, as explained below. + + SQLite builtin tokenizers + SQLite comes with three builtin tokenizers : + + simple + Under the *simple* tokenizer, a term is a contiguous sequence of + eligible characters, where eligible characters are all alphanumeric + characters, the "_" character, and all characters with UTF + codepoints greater than or equal to 128. All other characters are + discarded when splitting a document into terms. They serve only to + separate adjacent terms. + + All uppercase characters within the ASCII range (UTF codepoints less + than 128), are transformed to their lowercase equivalents as part of + the tokenization process. Thus, full-text queries are + case-insensitive when using the simple tokenizer. + + porter + The *porter* tokenizer uses the same rules to separate the input + document into terms, but as well as folding all terms to lower case + it uses the Porter Stemming algorithm to reduce related English + language words to a common root. + + icu If SQLite is compiled with the SQLITE_ENABLE_ICU pre-processor + symbol defined, then there exists a built-in tokenizer named "icu" + implemented using the ICU library, and taking an ICU locale + identifier as argument (such as "tr_TR" for Turkish as used in + Turkey, or "en_AU" for English as used in Australia). For example: + + CREATE VIRTUAL TABLE thai_text USING fts3(text, tokenize=icu th_TH) + + The ICU tokenizer implementation is very simple. It splits the input + text according to the ICU rules for finding word boundaries and + discards any tokens that consist entirely of white-space. This may + be suitable for some applications in some locales, but not all. If + more complex processing is required, for example to implement + stemming or discard punctuation, use the perl tokenizer as explained + below. + + Perl tokenizers + In addition to the builtin SQLite tokenizers, "DBD::SQLite" implements a + *perl* tokenizer, that can hook to any tokenizing algorithm written in + Perl. This is specified as follows : + + CREATE ... USING fts3(, tokenize=perl '') + + where "" is a fully qualified Perl function name (i.e. + prefixed by the name of the package in which that function is declared). + So for example if the function is "my_func" in the main program, write + + CREATE ... USING fts3(, tokenize=perl 'main::my_func') + + That function should return a code reference that takes a string as + single argument, and returns an iterator (another function), which + returns a tuple "($term, $len, $start, $end, $index)" for each term. + Here is a simple example that tokenizes on words according to the + current perl locale + + sub locale_tokenizer { + return sub { + my $string = shift; + + use locale; + my $regex = qr/\w+/; + my $term_index = 0; + + return sub { # closure + $string =~ /$regex/g or return; # either match, or no more token + my ($start, $end) = ($-[0], $+[0]); + my $len = $end-$start; + my $term = substr($string, $start, $len); + return ($term, $len, $start, $end, $term_index++); + } + }; + } + + There must be three levels of subs, in a kind of "Russian dolls" + structure, because : + + * the external, named sub is called whenever accessing a FTS3 table + with that tokenizer + + * the inner, anonymous sub is called whenever a new string needs to be + tokenized (either for inserting new text into the table, or for + analyzing a query). + + * the innermost, anonymous sub is called repeatedly for retrieving all + terms within that string. + + Instead of writing tokenizers by hand, you can grab one of those already + implemented in the Search::Tokenizer module : + + use Search::Tokenizer; + $dbh->do(<<"") or die DBI::errstr; + CREATE ... USING fts3(, + tokenize=perl 'Search::Tokenizer::unaccent') + + or you can use "new" in Search::Tokenizer to build your own tokenizer. + + Incomplete handling of utf8 characters + The current FTS3 implementation in SQLite is far from complete with + respect to utf8 handling : in particular, variable-length characters are + not treated correctly by the builtin functions "offsets()" and + "snippet()". + + Database space for FTS3 + FTS3 stores a complete copy of the indexed documents, together with the + fulltext index. On a large collection of documents, this can consume + quite a lot of disk space. If copies of documents are also available as + external resources (for example files on the filesystem), that space can + sometimes be spared --- see the tip in the Cookbook. + +R* TREE SUPPORT + The RTREE extension module within SQLite adds support for creating a + R-Tree, a special index for range and multidimensional queries. This + allows users to create tables that can be loaded with (as an example) + geospatial data such as latitude/longitude coordinates for buildings + within a city : + + CREATE VIRTUAL TABLE city_buildings USING rtree( + id, -- Integer primary key + minLong, maxLong, -- Minimum and maximum longitude + minLat, maxLat -- Minimum and maximum latitude + ); + + then query which buildings overlap or are contained within a specified + region: + + # IDs that are contained within query coordinates + my $contained_sql = <<""; + SELECT id FROM try_rtree + WHERE minLong >= ? AND maxLong <= ? + AND minLat >= ? AND maxLat <= ? + + # ... and those that overlap query coordinates + my $overlap_sql = <<""; + SELECT id FROM try_rtree + WHERE maxLong >= ? AND minLong <= ? + AND maxLat >= ? AND minLat <= ? + + my $contained = $dbh->selectcol_arrayref($contained_sql,undef, + $minLong, $maxLong, $minLat, $maxLat); + + my $overlapping = $dbh->selectcol_arrayref($overlap_sql,undef, + $minLong, $maxLong, $minLat, $maxLat); + + For more detail, please see the SQLite R-Tree page + (). Note that custom R-Tree queries + using callbacks, as mentioned in the prior link, have not been + implemented yet. + +FOR DBD::SQLITE EXTENSION AUTHORS + Since 1.30_01, you can retrieve the bundled sqlite C source and/or + header like this: + + use File::ShareDir 'dist_dir'; + use File::Spec::Functions 'catfile'; + + # the whole sqlite3.h header + my $sqlite3_h = catfile(dist_dir('DBD-SQLite'), 'sqlite3.h'); + + # or only a particular header, amalgamated in sqlite3.c + my $what_i_want = 'parse.h'; + my $sqlite3_c = catfile(dist_dir('DBD-SQLite'), 'sqlite3.c'); + open my $fh, '<', $sqlite3_c or die $!; + my $code = do { local $/; <$fh> }; + my ($parse_h) = $code =~ m{( + /\*+[ ]Begin[ ]file[ ]$what_i_want[ ]\*+ + .+? + /\*+[ ]End[ ]of[ ]$what_i_want[ ]\*+/ + )}sx; + open my $out, '>', $what_i_want or die $!; + print $out $parse_h; + close $out; + + You usually want to use this in your extension's "Makefile.PL", and you + may want to add DBD::SQLite to your extension's "CONFIGURE_REQUIRES" to + ensure your extension users use the same C source/header they use to + build DBD::SQLite itself (instead of the ones installed in their + system). + +TO DO + The following items remain to be done. + + Leak Detection + Implement one or more leak detection tests that only run during + AUTOMATED_TESTING and RELEASE_TESTING and validate that none of the C + code we work with leaks. + + Stream API for Blobs + Reading/writing into blobs using "sqlite2_blob_open" / + "sqlite2_blob_close". + + Flags for sqlite3_open_v2 + Support the full API of sqlite3_open_v2 (flags for opening the file). + + Support for custom callbacks for R-Tree queries + Custom queries of a R-Tree index using a callback are possible with the + SQLite C API (), so one could + potentially use a callback that narrowed the result set down based on a + specific need, such as querying for overlapping circles. + +SUPPORT + Bugs should be reported via the CPAN bug tracker at + + + + Note that bugs of bundled sqlite library (i.e. bugs in "sqlite3.[ch]") + should be reported to the sqlite developers at sqlite.org via their bug + tracker or via their mailing list. + +AUTHORS + Matt Sergeant + + Francis J. Lacoste + + Wolfgang Sourdeau + + Adam Kennedy + + Max Maischein + + Laurent Dami + + Kenichi Ishigaki + +COPYRIGHT + The bundled SQLite code in this distribution is Public Domain. + + DBD::SQLite is copyright 2002 - 2007 Matt Sergeant. + + Some parts copyright 2008 Francis J. Lacoste. + + Some parts copyright 2008 Wolfgang Sourdeau. + + Some parts copyright 2008 - 2012 Adam Kennedy. + + Some parts copyright 2009 - 2012 Kenichi Ishigaki. + + Some parts derived from DBD::SQLite::Amalgamation copyright 2008 Audrey + Tang. + + This program is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + + The full text of the license can be found in the LICENSE file included + with this module. diff --git a/xt/meta.t b/xt/meta.t new file mode 100644 index 0000000..2f8b2c7 --- /dev/null +++ b/xt/meta.t @@ -0,0 +1,27 @@ +#!/usr/bin/perl + +# Test that our META.yml file matches the current specification. + +use strict; +BEGIN { + $| = 1; + $^W = 1; +} + +my $MODULE = 'Test::CPAN::Meta 0.17'; + +# Don't run tests for installs +use Test::More; +unless ( $ENV{AUTOMATED_TESTING} or $ENV{RELEASE_TESTING} ) { + plan( skip_all => "Author tests not required for installation" ); +} + +# Load the testing module +eval "use $MODULE"; +if ( $@ ) { + $ENV{RELEASE_TESTING} + ? die( "Failed to load required release-testing module $MODULE" ) + : plan( skip_all => "$MODULE not available for testing" ); +} + +meta_yaml_ok(); diff --git a/xt/pmv.t b/xt/pmv.t new file mode 100644 index 0000000..f285be3 --- /dev/null +++ b/xt/pmv.t @@ -0,0 +1,32 @@ +#!/usr/bin/perl + +# Test that our declared minimum Perl version matches our syntax + +use strict; +BEGIN { + $| = 1; + $^W = 1; +} + +my @MODULES = ( + 'Perl::MinimumVersion 1.27', + 'Test::MinimumVersion 0.101080', +); + +# Don't run tests for installs +use Test::More; +unless ( $ENV{AUTOMATED_TESTING} or $ENV{RELEASE_TESTING} ) { + plan( skip_all => "Author tests not required for installation" ); +} + +# Load the testing modules +foreach my $MODULE ( @MODULES ) { + eval "use $MODULE"; + if ( $@ ) { + $ENV{RELEASE_TESTING} + ? die( "Failed to load required release-testing module $MODULE" ) + : plan( skip_all => "$MODULE not available for testing" ); + } +} + +all_minimum_version_from_metayml_ok(); diff --git a/xt/pod.t b/xt/pod.t new file mode 100644 index 0000000..170cae0 --- /dev/null +++ b/xt/pod.t @@ -0,0 +1,32 @@ +#!/usr/bin/perl + +# Test that the syntax of our POD documentation is valid + +use strict; +BEGIN { + $| = 1; + $^W = 1; +} + +my @MODULES = ( + 'Pod::Simple 3.14', + 'Test::Pod 1.44', +); + +# Don't run tests for installs +use Test::More; +unless ( $ENV{AUTOMATED_TESTING} or $ENV{RELEASE_TESTING} ) { + plan( skip_all => "Author tests not required for installation" ); +} + +# Load the testing modules +foreach my $MODULE ( @MODULES ) { + eval "use $MODULE"; + if ( $@ ) { + $ENV{RELEASE_TESTING} + ? die( "Failed to load required release-testing module $MODULE" ) + : plan( skip_all => "$MODULE not available for testing" ); + } +} + +all_pod_files_ok();