3
BerkeleyDB - Perl extension for Berkeley DB version 2 or 3
9
$env = new BerkeleyDB::Env [OPTIONS] ;
11
$db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
12
$db = new BerkeleyDB::Hash [OPTIONS] ;
14
$db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
15
$db = new BerkeleyDB::Btree [OPTIONS] ;
17
$db = tie %hash, 'BerkeleyDB::Recno', [OPTIONS] ;
18
$db = new BerkeleyDB::Recno [OPTIONS] ;
20
$db = tie %hash, 'BerkeleyDB::Queue', [OPTIONS] ;
21
$db = new BerkeleyDB::Queue [OPTIONS] ;
23
$db = new BerkeleyDB::Unknown [OPTIONS] ;
25
$status = BerkeleyDB::db_remove [OPTIONS]
27
$hash{$key} = $value ;
28
$value = $hash{$key} ;
33
$status = $db->db_get()
34
$status = $db->db_put() ;
35
$status = $db->db_del() ;
36
$status = $db->db_sync() ;
37
$status = $db->db_close() ;
38
$hash_ref = $db->db_stat() ;
39
$status = $db->db_key_range();
41
$status = $db->status() ;
42
$boolean = $db->byteswapped() ;
44
($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
45
($flag, $old_offset, $old_length) = $db->partial_clear() ;
47
$cursor = $db->db_cursor([$flags]) ;
48
$newcursor = $cursor->c_dup([$flags]);
49
$status = $cursor->c_get() ;
50
$status = $cursor->c_put() ;
51
$status = $cursor->c_del() ;
52
$status = $cursor->c_count() ;
53
$status = $cursor->status() ;
54
$status = $cursor->c_close() ;
56
$cursor = $db->db_join() ;
57
$status = $cursor->c_get() ;
58
$status = $cursor->c_close() ;
60
$status = $env->txn_checkpoint()
61
$hash_ref = $env->txn_stat()
62
$status = $env->setmutexlocks()
64
$txn = $env->txn_begin() ;
65
$status = $txn->txn_prepare()
66
$status = $txn->txn_commit()
67
$status = $txn->txn_abort()
68
$status = $txn->txn_id()
71
$BerkeleyDB::db_version
74
$old_filter = $db->filter_store_key ( sub { ... } ) ;
75
$old_filter = $db->filter_store_value( sub { ... } ) ;
76
$old_filter = $db->filter_fetch_key ( sub { ... } ) ;
77
$old_filter = $db->filter_fetch_value( sub { ... } ) ;
79
# deprecated, but supported
80
$txn_mgr = $env->TxnMgr();
81
$status = $txn_mgr->txn_checkpoint()
82
$hash_ref = $txn_mgr->txn_stat()
83
$txn = $txn_mgr->txn_begin() ;
87
B<NOTE: This document is still under construction. Expect it to be
88
incomplete in places.>
90
This Perl module provides an interface to most of the functionality
91
available in Berkeley DB versions 2 and 3. In general it is safe to assume
92
that the interface provided here to be identical to the Berkeley DB
93
interface. The main changes have been to make the Berkeley DB API work
94
in a Perl way. Note that if you are using Berkeley DB 2.x, the new
95
features available in Berkeley DB 3.x are not available via this module.
97
The reader is expected to be familiar with the Berkeley DB
98
documentation. Where the interface provided here is identical to the
99
Berkeley DB library and the... TODO
101
The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are
102
particularly relevant.
104
The interface to Berkeley DB is implemented with a number of Perl
109
The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB
110
function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and
111
B<DBENV-E<gt>open> in Berkeley DB 3.x. Its purpose is to initialise a
112
number of sub-systems that can then be used in a consistent way in all
113
the databases you make use of the environment.
115
If you don't intend using transactions, locking or logging, then you
116
shouldn't need to make use of B<BerkeleyDB::Env>.
120
$env = new BerkeleyDB::Env
122
[ -Server => $name, ]
123
[ -CacheSize => $number, ]
124
[ -Config => { name => value, name => value }, ]
125
[ -ErrFile => filename or filehandle, ]
126
[ -ErrPrefix => "string", ]
127
[ -Flags => number, ]
128
[ -LockDetect => number, ]
129
[ -Verbose => boolean, ]
133
All the parameters to the BerkeleyDB::Env constructor are optional.
137
If present, this parameter should point to an existing directory. Any
138
files that I<aren't> specified with an absolute path in the sub-systems
139
that are initialised by the BerkeleyDB::Env class will be assumed to
140
live in the B<Home> directory.
142
For example, in the code fragment below the database "fred.db" will be
143
opened in the directory "/home/databases" because it was specified as a
144
relative path, but "joe.db" will be opened in "/other" because it was
145
part of an absolute path.
147
$env = new BerkeleyDB::Env
148
-Home => "/home/databases"
151
$db1 = new BerkeleyDB::Hash
152
-Filename = "fred.db",
156
$db2 = new BerkeleyDB::Hash
157
-Filename = "/other/joe.db",
163
If present, this parameter should be the hostname of a server that is running
164
the Berkeley DB RPC server. All databases will be accessed via the RPC server.
168
If present, this parameter sets the size of the environments shared memory
173
This is a variation on the C<-Home> parameter, but it allows finer
174
control of where specific types of files will be stored.
176
The parameter expects a reference to a hash. Valid keys are:
177
B<DB_DATA_DIR>, B<DB_LOG_DIR> and B<DB_TMP_DIR>
179
The code below shows an example of how it can be used.
181
$env = new BerkeleyDB::Env
182
-Config => { DB_DATA_DIR => "/home/databases",
183
DB_LOG_DIR => "/home/logs",
184
DB_TMP_DIR => "/home/tmp"
190
Expects either the name of a file or a reference to a filehandle. Any
191
errors generated internally by Berkeley DB will be logged to this file.
195
Allows a prefix to be added to the error messages before they are sent
200
The B<Flags> parameter specifies both which sub-systems to initialise,
201
as well as a number of environment-wide options.
202
See the Berkeley DB documentation for more details of these options.
204
Any of the following can be specified by OR'ing them:
208
If any of the files specified do not already exist, create them.
212
Initialise the Concurrent Access Methods
216
Initialise the Locking sub-system.
220
Initialise the Logging sub-system.
234
B<DB_INIT_MPOOL> is also specified.
254
B<DB_USE_ENVIRON_ROOT>
258
Specifies what to do when a lock conflict occurs. The value should be one of
270
Add extra debugging information to the messages sent to B<-ErrFile>.
276
The environment class has the following methods:
280
=item $env->errPrefix("string") ;
282
This method is identical to the B<-ErrPrefix> flag. It allows the
283
error prefix string to be changed dynamically.
285
=item $txn = $env->TxnMgr()
287
Constructor for creating a B<TxnMgr> object.
288
See L<"TRANSACTIONS"> for more details of using transactions.
290
This method is deprecated. Access the transaction methods using the B<txn_>
291
methods below from the environment object directly.
293
=item $env->txn_begin()
297
=item $env->txn_stat()
301
=item $env->txn_checkpoint()
307
Returns the status of the last BerkeleyDB::Env method.
309
=item $env->setmutexlocks()
311
Only available in Berkeley Db 3.0 or greater. Calls
312
B<db_env_set_mutexlocks> when used with Berkeley DB 3.1.x. When used with
313
Berkeley DB 3.0 or 3.2 and better it calls B<DBENV-E<gt>set_mutexlocks>.
321
=head1 THE DATABASE CLASSES
323
B<BerkeleyDB> supports the following database formats:
327
=item B<BerkeleyDB::Hash>
329
This database type allows arbitrary key/value pairs to be stored in data
330
files. This is equivalent to the functionality provided by other
331
hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
332
the files created using B<BerkeleyDB::Hash> are not compatible with any
333
of the other packages mentioned.
335
A default hashing algorithm, which will be adequate for most applications,
336
is built into BerkeleyDB. If you do need to use your own hashing algorithm
337
it is possible to write your own in Perl and have B<BerkeleyDB> use
340
=item B<BerkeleyDB::Btree>
342
The Btree format allows arbitrary key/value pairs to be stored in a
345
As with the B<BerkeleyDB::Hash> format, it is possible to provide a
346
user defined Perl routine to perform the comparison of keys. By default,
347
though, the keys are stored in lexical order.
349
=item B<BerkeleyDB::Recno>
354
=item B<BerkeleyDB::Queue>
358
=item B<BerkeleyDB::Unknown>
360
This isn't a database format at all. It is used when you want to open an
361
existing Berkeley DB database without having to know what type is it.
366
Each of the database formats described above is accessed via a
367
corresponding B<BerkeleyDB> class. These will be described in turn in
370
=head1 BerkeleyDB::Hash
372
Equivalent to calling B<db_open> with type B<DB_HASH> in Berkeley DB 2.x and
373
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_HASH> in
376
Two forms of constructor are supported:
378
$db = new BerkeleyDB::Hash
379
[ -Filename => "filename", ]
380
[ -Subname => "sub-database name", ]
382
[ -Property => flags,]
384
[ -Cachesize => number,]
385
[ -Lorder => number,]
386
[ -Pagesize => number,]
389
# BerkeleyDB::Hash specific
390
[ -Ffactor => number,]
392
[ -Hash => code reference,]
393
[ -DupCompare => code reference,]
397
[$db =] tie %hash, 'BerkeleyDB::Hash',
398
[ -Filename => "filename", ]
399
[ -Subname => "sub-database name", ]
401
[ -Property => flags,]
403
[ -Cachesize => number,]
404
[ -Lorder => number,]
405
[ -Pagesize => number,]
408
# BerkeleyDB::Hash specific
409
[ -Ffactor => number,]
411
[ -Hash => code reference,]
412
[ -DupCompare => code reference,]
415
When the "tie" interface is used, reading from and writing to the database
416
is achieved via the tied hash. In this case the database operates like
417
a Perl associative array that happens to be stored on disk.
419
In addition to the high-level tied hash interface, it is possible to
420
make use of the underlying methods provided by Berkeley DB
424
In addition to the standard set of options (see L<COMMON OPTIONS>)
425
B<BerkeleyDB::Hash> supports these options:
431
Used to specify extra flags when opening a database. The following
432
flags may be specified by logically OR'ing together one or more of the
437
When creating a new database, this flag enables the storing of duplicate
438
keys in the database. If B<DB_DUPSORT> is not specified as well, the
439
duplicates are stored in the order they are created in the database.
443
Enables the sorting of duplicate keys in the database. Ignored if
444
B<DB_DUP> isn't also specified.
450
See the Berkeley DB documentation for details of these options.
454
Allows you to provide a user defined hash function. If not specified,
455
a default hash function is used. Here is a template for a user-defined
462
# return the hash value for $data
466
tie %h, "BerkeleyDB::Hash",
467
-Filename => $filename,
471
See L<""> for an example.
475
Used in conjunction with the B<DB_DUPOSRT> flag.
479
my ($key, $key2) = @_ ;
481
# return 0 if $key1 eq $key2
482
# -1 if $key1 lt $key2
483
# 1 if $key1 gt $key2
484
return (-1 , 0 or 1) ;
487
tie %h, "BerkeleyDB::Hash",
488
-Filename => $filename,
489
-Property => DB_DUP|DB_DUPSORT,
490
-DupCompare => \&compare,
498
B<BerkeleyDB::Hash> only supports the standard database methods.
499
See L<COMMON DATABASE METHODS>.
501
=head2 A Simple Tied Hash Example
513
Note that the like ordinary associative arrays, the order of the keys
514
retrieved from a Hash database are in an apparently random order.
516
=head2 Another Simple Hash Example
518
Do the same as the previous example but not using tie.
522
=head2 Duplicate keys
524
The code below is a variation on the examples above. This time the hash has
525
been inverted. The key this time is colour and the value is the fruit name.
526
The B<DB_DUP> flag has been specified to allow duplicates.
539
=head2 Sorting Duplicate Keys
541
In the previous example, when there were duplicate keys, the values are
542
sorted in the order they are stored in. The code below is
543
identical to the previous example except the B<DB_DUPSORT> flag is
548
Notice that in the output below the duplicate values are sorted.
557
=head2 Custom Sorting Duplicate Keys
563
=head2 Changing the hash
571
=head1 BerkeleyDB::Btree
573
Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and
574
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in
577
Two forms of constructor are supported:
580
$db = new BerkeleyDB::Btree
581
[ -Filename => "filename", ]
582
[ -Subname => "sub-database name", ]
584
[ -Property => flags,]
586
[ -Cachesize => number,]
587
[ -Lorder => number,]
588
[ -Pagesize => number,]
591
# BerkeleyDB::Btree specific
592
[ -Minkey => number,]
593
[ -Compare => code reference,]
594
[ -DupCompare => code reference,]
595
[ -Prefix => code reference,]
599
[$db =] tie %hash, 'BerkeleyDB::Btree',
600
[ -Filename => "filename", ]
601
[ -Subname => "sub-database name", ]
603
[ -Property => flags,]
605
[ -Cachesize => number,]
606
[ -Lorder => number,]
607
[ -Pagesize => number,]
610
# BerkeleyDB::Btree specific
611
[ -Minkey => number,]
612
[ -Compare => code reference,]
613
[ -DupCompare => code reference,]
614
[ -Prefix => code reference,]
618
In addition to the standard set of options (see L<COMMON OPTIONS>)
619
B<BerkeleyDB::Btree> supports these options:
625
Used to specify extra flags when opening a database. The following
626
flags may be specified by logically OR'ing together one or more of the
631
When creating a new database, this flag enables the storing of duplicate
632
keys in the database. If B<DB_DUPSORT> is not specified as well, the
633
duplicates are stored in the order they are created in the database.
637
Enables the sorting of duplicate keys in the database. Ignored if
638
B<DB_DUP> isn't also specified.
646
Allow you to override the default sort order used in the database. See
647
L<"Changing the sort order"> for an example.
651
my ($key, $key2) = @_ ;
653
# return 0 if $key1 eq $key2
654
# -1 if $key1 lt $key2
655
# 1 if $key1 gt $key2
656
return (-1 , 0 or 1) ;
659
tie %h, "BerkeleyDB::Hash",
660
-Filename => $filename,
661
-Compare => \&compare,
668
my ($key, $key2) = @_ ;
670
# return number of bytes of $key2 which are
671
# necessary to determine that it is greater than $key1
675
tie %h, "BerkeleyDB::Hash",
676
-Filename => $filename,
683
my ($key, $key2) = @_ ;
685
# return 0 if $key1 eq $key2
686
# -1 if $key1 lt $key2
687
# 1 if $key1 gt $key2
688
return (-1 , 0 or 1) ;
691
tie %h, "BerkeleyDB::Hash",
692
-Filename => $filename,
693
-DupCompare => \&compare,
700
B<BerkeleyDB::Btree> supports the following database methods.
701
See also L<COMMON DATABASE METHODS>.
703
All the methods below return 0 to indicate success.
707
=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])
709
Given a key, C<$key>, this method returns the proportion of keys less than
710
C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
711
proportion greater than C<$key> in C<$greater>.
713
The proportion is returned as a double in the range 0.0 to 1.0.
717
=head2 A Simple Btree Example
719
The code below is a simple example of using a btree database.
723
Here is the output from the code above. The keys have been sorted using
724
Berkeley DB's default sorting algorithm.
731
=head2 Changing the sort order
733
It is possible to supply your own sorting algorithm if the one that Berkeley
734
DB used isn't suitable. The code below is identical to the previous example
735
except for the case insensitive compare function.
739
Here is the output from the code above.
745
There are a few point to bear in mind if you want to change the
746
ordering in a BTREE database:
752
The new compare function must be specified when you create the database.
756
You cannot change the ordering once the database has been created. Thus
757
you must use the same compare function every time you access the
766
=head1 BerkeleyDB::Recno
768
Equivalent to calling B<db_open> with type B<DB_RECNO> in Berkeley DB 2.x and
769
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_RECNO> in
772
Two forms of constructor are supported:
774
$db = new BerkeleyDB::Recno
775
[ -Filename => "filename", ]
776
[ -Subname => "sub-database name", ]
778
[ -Property => flags,]
780
[ -Cachesize => number,]
781
[ -Lorder => number,]
782
[ -Pagesize => number,]
785
# BerkeleyDB::Recno specific
789
[ -Source => filename,]
793
[$db =] tie @arry, 'BerkeleyDB::Recno',
794
[ -Filename => "filename", ]
795
[ -Subname => "sub-database name", ]
797
[ -Property => flags,]
799
[ -Cachesize => number,]
800
[ -Lorder => number,]
801
[ -Pagesize => number,]
804
# BerkeleyDB::Recno specific
808
[ -Source => filename,]
810
=head2 A Recno Example
812
Here is a simple example that uses RECNO (if you are using a version
813
of Perl earlier than 5.004_57 this example won't work -- see
814
L<Extra RECNO Methods> for a workaround).
818
Here is the output from the script:
820
The array contains 5 entries
823
Element 1 Exists with value blue
824
The last element is green
825
The 2nd last element is yellow
827
=head1 BerkeleyDB::Queue
829
Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with
830
type B<DB_QUEUE> in Berkeley DB 3.x. This database format isn't available if
831
you use Berkeley DB 2.x.
833
Two forms of constructor are supported:
835
$db = new BerkeleyDB::Queue
836
[ -Filename => "filename", ]
837
[ -Subname => "sub-database name", ]
839
[ -Property => flags,]
841
[ -Cachesize => number,]
842
[ -Lorder => number,]
843
[ -Pagesize => number,]
846
# BerkeleyDB::Queue specific
849
[ -ExtentSize => number, ]
853
[$db =] tie @arry, 'BerkeleyDB::Queue',
854
[ -Filename => "filename", ]
855
[ -Subname => "sub-database name", ]
857
[ -Property => flags,]
859
[ -Cachesize => number,]
860
[ -Lorder => number,]
861
[ -Pagesize => number,]
864
# BerkeleyDB::Queue specific
869
=head1 BerkeleyDB::Unknown
871
This class is used to open an existing database.
873
Equivalent to calling B<db_open> with type B<DB_UNKNOWN> in Berkeley DB 2.x and
874
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_UNKNOWN> in
877
The constructor looks like this:
879
$db = new BerkeleyDB::Unknown
880
[ -Filename => "filename", ]
881
[ -Subname => "sub-database name", ]
883
[ -Property => flags,]
885
[ -Cachesize => number,]
886
[ -Lorder => number,]
887
[ -Pagesize => number,]
894
=head1 COMMON OPTIONS
896
All database access class constructors support the common set of
897
options defined below. All are optional.
903
The database filename. If no filename is specified, a temporary file will
904
be created and removed once the program terminates.
908
Specifies the name of the sub-database to open.
909
This option is only valid if you are using Berkeley DB 3.x.
913
Specify how the database will be opened/created. The valid flags are:
917
Create any underlying files, as necessary. If the files do not already
918
exist and the B<DB_CREATE> flag is not specified, the call will fail.
922
Not supported by BerkeleyDB.
926
Opens the database in read-only mode.
930
Not supported by BerkeleyDB.
934
If the database file already exists, remove all the data before
939
Determines the file protection when the database is created. Defaults
950
When working under a Berkeley DB environment, this parameter
952
Defaults to no environment.
960
=head1 COMMON DATABASE METHODS
962
All the database interfaces support the common set of methods defined
965
All the methods below return 0 to indicate success.
967
=head2 $status = $db->db_get($key, $value [, $flags])
969
Given a key (C<$key>) this method reads the value associated with it
970
from the database. If it exists, the value read from the database is
971
returned in the C<$value> parameter.
973
The B<$flags> parameter is optional. If present, it must be set to B<one>
974
of the following values:
980
When the B<DB_GET_BOTH> flag is specified, B<db_get> checks for the
981
existence of B<both> the C<$key> B<and> C<$value> in the database.
983
=item B<DB_SET_RECNO>
989
In addition, the following value may be set by logically OR'ing it into
990
the B<$flags> parameter:
1001
=head2 $status = $db->db_put($key, $value [, $flags])
1003
Stores a key/value pair in the database.
1005
The B<$flags> parameter is optional. If present it must be set to B<one>
1006
of the following values:
1012
This flag is only applicable when accessing a B<BerkeleyDB::Recno>
1018
=item B<DB_NOOVERWRITE>
1020
If this flag is specified and C<$key> already exists in the database,
1021
the call to B<db_put> will return B<DB_KEYEXIST>.
1025
=head2 $status = $db->db_del($key [, $flags])
1027
Deletes a key/value pair in the database associated with C<$key>.
1028
If duplicate keys are enabled in the database, B<db_del> will delete
1029
B<all> key/value pairs with key C<$key>.
1031
The B<$flags> parameter is optional and is currently unused.
1033
=head2 $status = $db->db_sync()
1035
If any parts of the database are in memory, write them to the database.
1037
=head2 $cursor = $db->db_cursor([$flags])
1039
Creates a cursor object. This is used to access the contents of the
1040
database sequentially. See L<CURSORS> for details of the methods
1041
available when working with cursors.
1043
The B<$flags> parameter is optional. If present it must be set to B<one>
1044
of the following values:
1054
=head2 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
1058
=head2 ($flag, $old_offset, $old_length) = $db->partial_clear() ;
1062
=head2 $db->byteswapped()
1068
Returns the type of the database. The possible return code are B<DB_HASH>
1069
for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree>
1070
database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method
1071
is typically used when a database has been opened with
1072
B<BerkeleyDB::Unknown>.
1074
=item $ref = $db->db_stat()
1076
Returns a reference to an associative array containing information about
1077
the database. The keys of the associative array correspond directly to the
1078
names of the fields defined in the Berkeley DB documentation. For example,
1079
in the DB documentation, the field B<bt_version> stores the version of the
1080
Btree database. Assuming you called B<db_stat> on a Btree database the
1081
equivalent field would be accessed as follows:
1083
$version = $ref->{'bt_version'} ;
1085
If you are using Berkeley DB 3.x, this method will work will all database
1086
formats. When DB 2.x is used, it only works with B<BerkeleyDB::Btree>.
1088
=head2 $status = $db->status()
1090
Returns the status of the last C<$db> method called.
1094
A cursor is used whenever you want to access the contents of a database
1095
in sequential order.
1096
A cursor object is created with the C<db_cursor>
1098
A cursor object has the following methods available:
1100
=head2 $newcursor = $cursor->c_dup($flags)
1102
Creates a duplicate of C<$cursor>. This method needs Berkeley DB 3.0.x or better.
1104
The C<$flags> parameter is optional and can take the following value:
1110
When present this flag will position the new cursor at the same place as the
1115
=head2 $status = $cursor->c_get($key, $value, $flags)
1117
Reads a key/value pair from the database, returning the data in C<$key>
1118
and C<$value>. The key/value pair actually read is controlled by the
1119
C<$flags> parameter, which can take B<one> of the following values:
1125
Set the cursor to point to the first key/value pair in the
1126
database. Return the key/value pair in C<$key> and C<$value>.
1130
Set the cursor to point to the last key/value pair in the database. Return
1131
the key/value pair in C<$key> and C<$value>.
1135
If the cursor is already pointing to a key/value pair, it will be
1136
incremented to point to the next key/value pair and return its contents.
1138
If the cursor isn't initialised, B<DB_NEXT> works just like B<DB_FIRST>.
1140
If the cursor is already positioned at the last key/value pair, B<c_get>
1141
will return B<DB_NOTFOUND>.
1143
=item B<DB_NEXT_DUP>
1145
This flag is only valid when duplicate keys have been enabled in
1147
If the cursor is already pointing to a key/value pair and the key of
1148
the next key/value pair is identical, the cursor will be incremented to
1149
point to it and their contents returned.
1153
If the cursor is already pointing to a key/value pair, it will be
1154
decremented to point to the previous key/value pair and return its
1157
If the cursor isn't initialised, B<DB_PREV> works just like B<DB_LAST>.
1159
If the cursor is already positioned at the first key/value pair, B<c_get>
1160
will return B<DB_NOTFOUND>.
1164
If the cursor has been set to point to a key/value pair, return their
1166
If the key/value pair referenced by the cursor has been deleted, B<c_get>
1167
will return B<DB_KEYEMPTY>.
1171
Set the cursor to point to the key/value pair referenced by B<$key>
1172
and return the value in B<$value>.
1174
=item B<DB_SET_RANGE>
1176
This flag is a variation on the B<DB_SET> flag. As well as returning
1177
the value, it also returns the key, via B<$key>.
1178
When used with a B<BerkeleyDB::Btree> database the key matched by B<c_get>
1179
will be the shortest key (in length) which is greater than or equal to
1180
the key supplied, via B<$key>. This allows partial key searches.
1181
See ??? for an example of how to use this flag.
1183
=item B<DB_GET_BOTH>
1185
Another variation on B<DB_SET>. This one returns both the key and
1188
=item B<DB_SET_RECNO>
1192
=item B<DB_GET_RECNO>
1198
In addition, the following value may be set by logically OR'ing it into
1199
the B<$flags> parameter:
1209
=head2 $status = $cursor->c_put($key, $value, $flags)
1211
Stores the key/value pair in the database. The position that the data is
1212
stored in the database is controlled by the C<$flags> parameter, which
1213
must take B<one> of the following values:
1219
When used with a Btree or Hash database, a duplicate of the key referenced
1220
by the current cursor position will be created and the contents of
1221
B<$value> will be associated with it - B<$key> is ignored.
1222
The new key/value pair will be stored immediately after the current
1224
Obviously the database has to have been opened with B<DB_DUP>.
1226
When used with a Recno ... TODO
1231
When used with a Btree or Hash database, a duplicate of the key referenced
1232
by the current cursor position will be created and the contents of
1233
B<$value> will be associated with it - B<$key> is ignored.
1234
The new key/value pair will be stored immediately before the current
1236
Obviously the database has to have been opened with B<DB_DUP>.
1238
When used with a Recno ... TODO
1242
If the cursor has been initialised, replace the value of the key/value
1243
pair stored in the database with the contents of B<$value>.
1245
=item B<DB_KEYFIRST>
1247
Only valid with a Btree or Hash database. This flag is only really
1248
used when duplicates are enabled in the database and sorted duplicates
1249
haven't been specified.
1250
In this case the key/value pair will be inserted as the first entry in
1251
the duplicates for the particular key.
1255
Only valid with a Btree or Hash database. This flag is only really
1256
used when duplicates are enabled in the database and sorted duplicates
1257
haven't been specified.
1258
In this case the key/value pair will be inserted as the last entry in
1259
the duplicates for the particular key.
1263
=head2 $status = $cursor->c_del([$flags])
1265
This method deletes the key/value pair associated with the current cursor
1266
position. The cursor position will not be changed by this operation, so
1267
any subsequent cursor operation must first initialise the cursor to
1268
point to a valid key/value pair.
1270
If the key/value pair associated with the cursor have already been
1271
deleted, B<c_del> will return B<DB_KEYEMPTY>.
1273
The B<$flags> parameter is not used at present.
1275
=head2 $status = $cursor->c_del($cnt [, $flags])
1277
Stores the number of duplicates at the current cursor position in B<$cnt>.
1279
The B<$flags> parameter is not used at present. This method needs
1280
Berkeley DB 3.1 or better.
1282
=head2 $status = $cursor->status()
1284
Returns the status of the last cursor method as a dual type.
1286
=head2 Cursor Examples
1290
Iterating from first to last, then in reverse.
1292
examples of each of the flags.
1296
Join support for BerkeleyDB is in progress. Watch this space.
1306
A DBM Filter is a piece of code that is be used when you I<always>
1307
want to make the same transformation to all keys and/or values in a DBM
1308
database. All of the database classes (BerkeleyDB::Hash,
1309
BerkeleyDB::Btree and BerkeleyDB::Recno) support DBM Filters.
1311
There are four methods associated with DBM Filters. All work
1312
identically, and each is used to install (or uninstall) a single DBM
1313
Filter. Each expects a single parameter, namely a reference to a sub.
1314
The only difference between them is the place that the filter is
1321
=item B<filter_store_key>
1323
If a filter has been installed with this method, it will be invoked
1324
every time you write a key to a DBM database.
1326
=item B<filter_store_value>
1328
If a filter has been installed with this method, it will be invoked
1329
every time you write a value to a DBM database.
1332
=item B<filter_fetch_key>
1334
If a filter has been installed with this method, it will be invoked
1335
every time you read a key from a DBM database.
1337
=item B<filter_fetch_value>
1339
If a filter has been installed with this method, it will be invoked
1340
every time you read a value from a DBM database.
1344
You can use any combination of the methods, from none, to all four.
1346
All filter methods return the existing filter, if present, or C<undef>
1349
To delete a filter pass C<undef> to it.
1353
When each filter is called by Perl, a local copy of C<$_> will contain
1354
the key or value to be filtered. Filtering is achieved by modifying
1355
the contents of C<$_>. The return code from the filter is ignored.
1357
=head2 An Example -- the NULL termination problem.
1359
Consider the following scenario. You have a DBM database that you need
1360
to share with a third-party C application. The C application assumes
1361
that I<all> keys and values are NULL terminated. Unfortunately when
1362
Perl writes to DBM databases it doesn't use NULL termination, so your
1363
Perl application will have to manage NULL termination itself. When you
1364
write to the database you will have to use something like this:
1366
$hash{"$key\0"} = "$value\0" ;
1368
Similarly the NULL needs to be taken into account when you are considering
1369
the length of existing keys/values.
1371
It would be much better if you could ignore the NULL terminations issue
1372
in the main application code and have a mechanism that automatically
1373
added the terminating NULL to all keys and values whenever you write to
1374
the database and have them removed when you read from the database. As I'm
1375
sure you have already guessed, this is a problem that DBM Filters can
1380
Hopefully the contents of each of the filters should be
1381
self-explanatory. Both "fetch" filters remove the terminating NULL,
1382
and both "store" filters add a terminating NULL.
1385
=head2 Another Example -- Key is a C int.
1387
Here is another real-life example. By default, whenever Perl writes to
1388
a DBM database it always writes the key and value as strings. So when
1391
$hash{12345} = "something" ;
1393
the key 12345 will get stored in the DBM database as the 5 byte string
1394
"12345". If you actually want the key to be stored in the DBM database
1395
as a C int, you will have to use C<pack> when writing, and C<unpack>
1398
Here is a DBM Filter that does it:
1402
This time only two filters have been used -- we only need to manipulate
1403
the contents of the key, so it wasn't necessary to install any value
1406
=head1 Using BerkeleyDB with MLDBM
1408
Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM
1409
module. The code fragment below shows how to open associate MLDBM with
1410
BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace
1411
BerkeleyDB::Btree with BerkeleyDB::Hash.
1415
use MLDBM qw(BerkeleyDB::Btree) ;
1418
my $filename = 'testmldbm' ;
1422
tie %o, 'MLDBM', -Filename => $filename,
1424
or die "Cannot open database '$filename: $!\n";
1426
See the MLDBM documentation for information on how to use the module
1427
and for details of its limitations.
1435
=head2 Sharing Databases With C Applications
1437
There is no technical reason why a Berkeley DB database cannot be
1438
shared by both a Perl and a C application.
1440
The vast majority of problems that are reported in this area boil down
1441
to the fact that C strings are NULL terminated, whilst Perl strings
1442
are not. See L<An Example -- the NULL termination problem.> in the DBM
1443
FILTERS section for a generic way to work around this problem.
1446
=head2 The untie Gotcha
1450
=head1 COMMON QUESTIONS
1452
This section attempts to answer some of the more common questions that
1456
=head2 Relationship with DB_File
1458
Before Berkeley DB 2.x was written there was only one Perl module that
1459
interfaced to Berkeley DB. That module is called B<DB_File>. Although
1460
B<DB_File> can be build with Berkeley DB 1.x, 2.x or 3.x, it only provides
1461
an interface to the functionality available in Berkeley DB 1.x. That
1462
means that it doesn't support transactions, locking or any of the other
1463
new features available in DB 2.x or 3.x.
1465
=head2 How do I store Perl data structures with BerkeleyDB?
1467
See L<Using BerkeleyDB with MLDBM>.
1471
See the Changes file.
1475
The most recent version of B<BerkeleyDB> can always be found
1476
on CPAN (see L<perlmod/CPAN> for details), in the directory
1477
F<modules/by-module/BerkeleyDB>.
1479
The official web site for Berkeley DB is F<http://www.sleepycat.com>.
1483
Copyright (c) 1997-2001 Paul Marquess. All rights reserved. This program
1484
is free software; you can redistribute it and/or modify it under the
1485
same terms as Perl itself.
1487
Although B<BerkeleyDB> is covered by the Perl license, the library it
1488
makes use of, namely Berkeley DB, is not. Berkeley DB has its own
1489
copyright and its own license. Please take the time to read it.
1491
Here are few words taken from the Berkeley DB FAQ (at
1492
F<http://www.sleepycat.com>) regarding the license:
1494
Do I have to license DB to use it in Perl scripts?
1496
No. The Berkeley DB license requires that software that uses
1497
Berkeley DB be freely redistributable. In the case of Perl, that
1498
software is Perl, and not your scripts. Any Perl scripts that you
1499
write are your property, including scripts that make use of Berkeley
1500
DB. Neither the Perl license nor the Berkeley DB license
1501
place any restriction on what you may do with them.
1503
If you are in any doubt about the license situation, contact either the
1504
Berkeley DB authors or the author of BerkeleyDB.
1505
See L<"AUTHOR"> for details.
1510
Paul Marquess E<lt>Paul.Marquess@btinternet.comE<gt>.
1512
Questions about Berkeley DB may be addressed to E<lt>db@sleepycat.comE<gt>.
1516
perl(1), DB_File, Berkeley DB.
added
removed
db/perl.BerkeleyDB/BerkeleyDB.pod.P
