view release on metacpan or  search on metacpan

lib/DB/Handy.pm  view on Meta::CPAN

The SQL string does not match any known pattern.

=item C<Invalid database name 'E<lt>nameE<gt>'>

A database name was passed to C<new>, C<create_database>, C<use_database>
or C<drop_database> that is not a plain identifier.  Names are restricted
to word characters (C<[A-Za-z0-9_]>) because they are used directly as
directory names; C<..>, C</> and C<\\> are therefore rejected.  The
Windows device names C<con>, C<prn>, C<aux>, C<nul>, C<com0> to C<com9>
and C<lpt0> to C<lpt9> are rejected as well, in any letter case, on every
platform.

=item C<Invalid table name 'E<lt>nameE<gt>'>

A table name that is not a plain identifier was passed to C<create_table>,
C<drop_table>, or to any method that loads a schema.  See
C<Invalid database name> above for the rule.

=item C<Invalid index name 'E<lt>nameE<gt>'>

An index name that is not a plain identifier was passed to C<create_index>
or C<drop_index>.  See C<Invalid database name> above for the rule.

=item C<Database 'E<lt>nameE<gt>' already exists>

C<create_database> was called for a database directory that already exists.

=item C<Database 'E<lt>nameE<gt>' does not exist>

C<connect> or C<drop_database> was called for a database directory that
does not exist.

=item C<Cannot open base_dir: E<lt>reasonE<gt>>

The base directory passed to C<new> (or C<connect>) could not be opened.
Check that the path exists and that the process has read permission.

=item C<Cannot open dat 'E<lt>fileE<gt>': E<lt>reasonE<gt>>

A C<.dat> record file could not be opened for reading or writing.
Check file permissions and disk space.

=item C<Cannot read schema: E<lt>reasonE<gt>>

A C<.sch> schema file exists but could not be read.
Check file permissions.

=item C<Cannot create base_dir: E<lt>reasonE<gt>>

C<new> could not create the base directory.
Check parent-directory write permissions.

=item C<Cannot create database 'E<lt>nameE<gt>': E<lt>reasonE<gt>>

C<create_database> could not create the database subdirectory.
Check disk space and write permissions on C<base_dir>.

=item C<Cannot drop database 'E<lt>nameE<gt>': E<lt>reasonE<gt>>

C<drop_database> could not remove the database directory tree.
Check that no files are locked and that write permission is granted.

=item C<DB::Handy connect failed: E<lt>messageE<gt>>

The low-level C<connect> call failed.  C<$DB::Handy::errstr> contains
the underlying error set by the failing operation.

=item C<DB::Handy: E<lt>messageE<gt>>

A fatal internal error was raised directly via C<die>.
C<RaiseError> must be enabled (the default) for this message to propagate.

=item C<AutoCommit cannot be turned off: DB::Handy has no transactions>

C<connect> was called with C<AutoCommit =E<gt> 0>.  DB::Handy has no
transactions, so the request cannot be honoured and the connection is
refused rather than accepted with a promise it could not keep.

=item C<Value too long for column 'E<lt>colE<gt>': declared E<lt>typeE<gt>(E<lt>nE<gt>), got E<lt>mE<gt> bytes>

An C<INSERT> or C<UPDATE> supplied a value longer than the declared
C<CHAR> or C<VARCHAR> size.  The value is rejected; it is never truncated.

=item C<Integer out of range for column 'E<lt>colE<gt>': 'E<lt>valueE<gt>' ...>

An C<INSERT> or C<UPDATE> supplied a value outside the range the declared
integer type can hold.

=item C<Invalid DATE for column 'E<lt>colE<gt>': 'E<lt>valueE<gt>' (expected YYYY-MM-DD)>

A C<DATE> column was given a value that is not an ISO-8601 calendar date.

=item C<CHECK constraint failed on column 'E<lt>colE<gt>'>

An C<INSERT> or C<UPDATE> supplied a value the column's C<CHECK>
expression rejected.

=item C<FULL OUTER JOIN is not supported ...>

=item C<NATURAL JOIN is not supported ...>

=item C<JOIN ... USING is not supported ...>

=item C<Unsupported JOIN condition 'ON E<lt>exprE<gt>' ...>

=item C<Unqualified column in the ON clause of JOIN E<lt>tableE<gt> ...>

=item C<Unsupported WHERE condition in a JOIN query: 'E<lt>partE<gt>' ...>

=item C<Unsupported select item 'E<lt>itemE<gt>' in a JOIN query ...>

=item C<Unknown ORDER BY column 'E<lt>colE<gt>' in a JOIN query>

The query used a JOIN construct the engine cannot execute.  See
L</JOIN> for what a JOIN accepts.  Each of these messages names the
offending text and says what to write instead.  Before 1.09 these
constructs were accepted and quietly answered a different question, so
code that used to "work" may now report an error; see L</BUGS AND
LIMITATIONS>.

=item C<Each SELECT of a set operation must return the same number of columns (E<lt>nE<gt> and E<lt>mE<gt>)>

lib/DB/Handy.pm  view on Meta::CPAN

=item *

B<A database, table or index named after a Windows device is unreachable
from 1.10.>  C<con>, C<prn>, C<aux>, C<nul>, C<com0> to C<com9> and
C<lpt0> to C<lpt9> are rejected in any letter case on every platform, as
described under L</METHODS - Low-level API>.  Windows could never hold
such a name in the first place, but a system that could -- a Unix host,
say -- may carry one created by 1.09 or earlier.  From 1.10 that name is
refused by every method that takes one, C<drop_database> and
C<drop_table> included, so there is no way to reach or remove it through
the API.  Rename the directory or file outside DB::Handy, or delete it
with the tools of the operating system.

=item *

B<C<ORDER BY> by position does not work with C<SELECT *> across a JOIN.>
The combined column list of the joined tables is not known at the point
the sort key is parsed, so the position is reported as an error.  Name
the column instead.  Positions do work with C<SELECT *> on a single
table, and with an explicit select list anywhere.

=item *

B<No FOREIGN KEY constraints or VIEW support.>

=item *

B<No WINDOW functions> (ROW_NUMBER, RANK, LEAD, LAG, etc.).

=item *

B<No BLOB/CLOB> large-object types.

=item *

B<Single-column indexes only.>  Composite (multi-column) indexes are not
supported.

=item *

B<NOT IN with C<NULL> in the value list returns no rows>, as SQL
semantics require.  C<col NOT IN (v1, NULL, v2)> is UNKNOWN for every
row when the value is not found in the non-NULL elements, so no row
matches.  When the column is indexed the engine falls back to a full
table scan before applying this rule.

=item *

B<No query planner.>  All queries have fixed execution plans; there is no
cost-based optimiser.

=item *

B<The return value of C<flock> is not checked.>  Every read takes a
shared lock and every write an exclusive lock on the C<.dat> file and on
each index file, and a write is flushed before the lock is released, so
concurrent access is serialised wherever C<flock> works.  Where it does
not -- NFS with no lock daemon, some network shares, a platform that
implements C<flock> as a no-op -- the call fails silently and the access
proceeds unlocked, so two processes writing the same table at the same
time can interleave.  The failure is ignored on purpose, because raising
an error would make the module unusable on those file systems for the
single-process use it is designed for; assume a single writer if the
data directory is not on a local file system.

=item *

Cannot be used as a drop-in replacement via C<DBI-E<gt>connect>.

=back

=head1 SEE ALSO

L<DBI> - the standard Perl database interface that DB::Handy's API is
modelled after.

L<DBD::SQLite> - a full-featured, embeddable SQL database accessible via DBI,
recommended when transaction support or a richer SQL dialect is needed.

Other modules by the same author:

L<HTTP::Handy>, L<LTSV::LINQ>, L<mb>, L<UTF8::R2>,
L<Jacode>, L<Jacode4e>, L<Jacode4e::RoundTrip>, L<mb::JSON>

=head1 AUTHOR

INABA Hitoshi E<lt>ina.cpan@gmail.comE<gt>

This project was originated by INABA Hitoshi.

=head1 COPYRIGHT AND LICENSE

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

=cut