46
50
=head1 VERSION DIFFERENCES
52
B<NOTE>: 2.0000 introduces Unicode support in the File back end. This
53
necessitates a change in the file format. The version 1.0003 format is
54
still supported, though, so we have added a L</db_version|db_version()>
55
method. If you are using a database in the old format, you will have to
56
upgrade it to get Unicode support.
48
58
B<NOTE>: 1.0020 introduces different engines which are backed by different types
49
59
of storage. There is the original storage (called 'File') and a database storage
50
60
(called 'DBI'). q.v. L</PLUGINS> for more information.
114
When you open an existing database file, the version of the database format
115
will stay the same. But if you are creating a new file, it will be in the
106
120
This is a storage engine that stores the data in a relational database. Funnily
138
B<NOTE>: This has only been tested with MySQL (with disappointing results). I
139
plan on extending this to work with SQLite and PostgreSQL in the next release.
140
Oracle, Sybase, and other engines will come later.
152
B<NOTE>: This has only been tested with MySQL and SQLite (with
153
disappointing results). I plan on extending this to work with PostgreSQL in
154
the near future. Oracle, Sybase, and other engines will come later.
142
156
=head2 Planned engines
296
310
included within the data_sector_size, thus the effective value is 6-10 bytes
297
311
less than what you specified.
313
B<Another note:> If your strings contain any characters beyond the byte
314
range, they will be encoded as UTF-8 before being stored in the file. This
315
will make all non-ASCII characters take up more than one byte each.
299
317
=item * pack_size
301
319
This is the size of the file pointer used throughout the file. The valid values
321
339
See L</LARGEFILE SUPPORT> for more information.
341
=item * external_refs
343
This is a boolean option. When enabled, it allows external references to
344
database entries to hold on to those entries, even when they are deleted.
346
To illustrate, if you retrieve a hash (or array) reference from the
349
$foo_hash = $db->{foo};
351
the hash reference is still tied to the database. So if you
355
C<$foo_hash> will point to a location in the DB that is no longer valid (we
356
call this a stale reference). So if you try to retrieve the data from
359
for(keys %$foo_hash) {
361
you will get an error.
363
The C<external_refs> option causes C<$foo_hash> to 'hang on' to the
364
DB entry, so it will not be deleted from the database if there is still a
365
reference to it in a running program. It will be deleted, instead, when the
366
C<$foo_hash> variable no longer exists, or is overwritten.
368
This has the potential to cause database bloat if your program crashes, so
369
it is not enabled by default. (See also the L</export> method for an
370
alternative workaround.)
325
374
=head1 TIE INTERFACE
327
376
With DBM::Deep you can access your databases using Perl's standard hash/array
328
377
syntax. Because all DBM::Deep objects are I<tied> to hashes or arrays, you can
329
treat them as such. DBM::Deep will intercept all reads/writes and direct them
378
treat them as such (but see L</external_refs>, above, and
379
L</Stale References>, below). DBM::Deep will intercept
380
all reads/writes and direct them
330
381
to the right place -- the DB file. This has nothing to do with the
331
382
L</TIE CONSTRUCTION> section above. This simply tells you how to use DBM::Deep
332
383
using regular hashes and arrays, rather than calling functions like C<get()>
442
493
Deletes one hash key/value pair or array element. Takes one argument: the hash
443
key or array index. Returns true on success, false if not found. For arrays,
444
the remaining elements located after the deleted element are NOT moved over.
445
The deleted element is essentially just undefined, which is exactly how Perl's
494
key or array index. Returns the data that the element used to contain (just
495
like Perl's C<delete> function), which is C<undef> if it did not exist. For
496
arrays, the remaining elements located after the deleted element are NOT
497
moved over. The deleted element is essentially just undefined, which is
446
499
internal arrays work.
448
501
$db->delete("foo"); # for hashes
466
519
extending the size of the datafile. But, that freespace just sits in the
467
520
datafile unless C<optimize()> is called.
522
C<optimize> basically copies everything into a new database, so, if it is
523
in version 1.0003 format, it will be upgraded.
471
527
Unlike simple assignment, C<import()> does not tie the right-hand side. Instead,
485
541
=item * supports( $option )
487
This returns a boolean depending on if this instance of DBM::Dep supports
488
that feature. C<$option> can be one of:
543
This returns a boolean indicating whether this instance of DBM::Deep
544
supports that feature. C<$option> can be one of:
492
548
=item * transactions
556
This returns the version of the database format that the current database
557
is in. This is specified as the earliest version of DBM::Deep that supports
560
For the File back end, this will be 1.0003 or 2.
562
For the DBI back end, it is currently always 1.0020.
688
756
print $db->{key1} . "\n"; # prints "value1"
690
758
This recursively imports the entire C<$struct> object into C<$db>, including
691
all nested hashes and arrays. If the DBM::Deep object contains exsiting data,
759
all nested hashes and arrays. If the DBM::Deep object contains existing data,
692
760
keys are merged with the existing ones, replacing if they already exist.
693
761
The C<import()> method can be called on any database level (not just the base
694
762
level), and works with both hash and array DB types.
779
$db->set_filter( "filter_store_value", \&my_filter_store );
780
$db->set_filter( "filter_fetch_value", \&my_filter_fetch );
847
$db->set_filter( "store_value", \&my_filter_store );
848
$db->set_filter( "fetch_value", \&my_filter_fetch );
782
850
Your filter function will be called only when dealing with SCALAR keys or
783
851
values. When nested hashes and arrays are being stored/fetched, filtering
785
853
argument, and expected to return a single SCALAR value. If you want to
786
854
remove a filter, set the function reference to C<undef>:
788
$db->set_filter( "filter_store_value", undef );
856
$db->set_filter( "store_value", undef );
792
Please read L<DBM::Deep::Manual> for examples of filters.
860
Please read L<DBM::Deep::Cookbook> for examples of filters.
794
862
=head1 ERROR HANDLING
922
As of 1.0000, the file format has changed. Furthermore, DBM::Deep is now
923
designed to potentially change file format between point-releases, if needed to
924
support a requested feature. To aid in this, a migration script is provided
925
within the CPAN distribution called C<utils/upgrade_db.pl>.
990
As of 1.0000, the file format has changed. To aid in upgrades, a migration
991
script is provided within the CPAN distribution, called
992
F<utils/upgrade_db.pl>.
927
994
B<NOTE:> This script is not installed onto your system because it carries a copy
928
995
of every version prior to the current version.
997
As of version 2.0000, databases created by old versions back to 1.0003 can
998
be read, but new features may not be available unless the database is
932
1003
The following are items that are planned to be added in future releases. These
969
1040
This section describes all the known issues with DBM::Deep. These are issues
970
1041
that are either intractable or depend on some feature within Perl working
971
1042
exactly right. It you have found something that is not listed below, please
972
send an e-mail to L<rkinyon@cpan.org>. Likewise, if you think you know of a
1043
send an e-mail to L<bug-DBM-Deep@rt.cpan.org>. Likewise, if you think you
973
1045
way around one of these issues, please let me know.
975
1047
=head2 References
1203
1275
=head1 SEE ALSO
1205
perltie(1), Tie::Hash(3), Digest::MD5(3), Fcntl(3), flock(2), lockf(3), nfs(5),
1206
Digest::SHA256(3), Crypt::Blowfish(3), Compress::Zlib(3)
1277
L<DBM::Deep::Cookbook(3)>
1279
L<perltie(1)>, L<Tie::Hash(3)>, L<Fcntl(3)>, L<flock(2)>, L<lockf(3)>,
added
removed
lib/DBM/Deep.pod
