-
Notifications
You must be signed in to change notification settings - Fork 4
/
BerkeleyDB.pod.P
executable file
·2514 lines (1678 loc) · 73.6 KB
/
BerkeleyDB.pod.P
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=head1 NAME
BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4, 5 or 6
=head1 SYNOPSIS
use BerkeleyDB;
$env = new BerkeleyDB::Env [OPTIONS] ;
$db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
$db = new BerkeleyDB::Hash [OPTIONS] ;
$db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
$db = new BerkeleyDB::Btree [OPTIONS] ;
$db = tie @array, 'BerkeleyDB::Recno', [OPTIONS] ;
$db = new BerkeleyDB::Recno [OPTIONS] ;
$db = tie @array, 'BerkeleyDB::Queue', [OPTIONS] ;
$db = new BerkeleyDB::Queue [OPTIONS] ;
$db = new BerkeleyDB::Heap [OPTIONS] ;
$db = new BerkeleyDB::Unknown [OPTIONS] ;
$status = BerkeleyDB::db_remove [OPTIONS]
$status = BerkeleyDB::db_rename [OPTIONS]
$status = BerkeleyDB::db_verify [OPTIONS]
$hash{$key} = $value ;
$value = $hash{$key} ;
each %hash ;
keys %hash ;
values %hash ;
$env = $db->Env()
$status = $db->db_get()
$status = $db->db_exists() ;
$status = $db->db_put() ;
$status = $db->db_del() ;
$status = $db->db_sync() ;
$status = $db->db_close() ;
$status = $db->db_pget()
$hash_ref = $db->db_stat() ;
$status = $db->db_key_range();
$type = $db->type() ;
$status = $db->status() ;
$boolean = $db->byteswapped() ;
$status = $db->truncate($count) ;
$status = $db->compact($start, $stop, $c_data, $flags, $end);
$status = $db->get_blob_threshold($t1) ;
$status = $db->get_blob_dir($dir) ;
$bool = $env->cds_enabled();
$bool = $db->cds_enabled();
$lock = $db->cds_lock();
$lock->cds_unlock();
($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
($flag, $old_offset, $old_length) = $db->partial_clear() ;
$cursor = $db->db_cursor([$flags]) ;
$newcursor = $cursor->c_dup([$flags]);
$status = $cursor->c_get() ;
$status = $cursor->c_put() ;
$status = $cursor->c_del() ;
$status = $cursor->c_count() ;
$status = $cursor->c_pget() ;
$status = $cursor->status() ;
$status = $cursor->c_close() ;
$stream = $cursor->db_stream() ;
$cursor = $db->db_join() ;
$status = $cursor->c_get() ;
$status = $cursor->c_close() ;
$status = $stream->size($S);
$status = $stream->read($data, $offset, $size);
$status = $stream->write($data, $offset);
$status = $env->txn_checkpoint()
$hash_ref = $env->txn_stat()
$status = $env->set_mutexlocks()
$status = $env->set_flags()
$status = $env->set_timeout()
$status = $env->lock_detect()
$status = $env->lsn_reset()
$status = $env->get_blob_threshold($t1) ;
$status = $env->get_blob_dir($dir) ;
$txn = $env->txn_begin() ;
$db->Txn($txn);
$txn->Txn($db1, $db2,...);
$status = $txn->txn_prepare()
$status = $txn->txn_commit()
$status = $txn->txn_abort()
$status = $txn->txn_id()
$status = $txn->txn_discard()
$status = $txn->set_timeout()
$status = $env->set_lg_dir();
$status = $env->set_lg_bsize();
$status = $env->set_lg_max();
$status = $env->set_data_dir() ;
$status = $env->set_tmp_dir() ;
$status = $env->set_verbose() ;
$db_env_ptr = $env->DB_ENV() ;
$BerkeleyDB::Error
$BerkeleyDB::db_version
# DBM Filters
$old_filter = $db->filter_store_key ( sub { ... } ) ;
$old_filter = $db->filter_store_value( sub { ... } ) ;
$old_filter = $db->filter_fetch_key ( sub { ... } ) ;
$old_filter = $db->filter_fetch_value( sub { ... } ) ;
# deprecated, but supported
$txn_mgr = $env->TxnMgr();
$status = $txn_mgr->txn_checkpoint()
$hash_ref = $txn_mgr->txn_stat()
$txn = $txn_mgr->txn_begin() ;
=head1 DESCRIPTION
B<NOTE: This document is still under construction. Expect it to be
incomplete in places.>
This Perl module provides an interface to most of the functionality
available in Berkeley DB versions 2, 3, 5 and 6. In general it is safe to assume
that the interface provided here to be identical to the Berkeley DB
interface. The main changes have been to make the Berkeley DB API work
in a Perl way. Note that if you are using Berkeley DB 2.x, the new
features available in Berkeley DB 3.x or later are not available via
this module.
The reader is expected to be familiar with the Berkeley DB
documentation. Where the interface provided here is identical to the
Berkeley DB library and the... TODO
The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are
particularly relevant.
The interface to Berkeley DB is implemented with a number of Perl
classes.
=head1 The BerkeleyDB::Env Class
The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB
function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and
B<DBENV-E<gt>open> in Berkeley DB 3.x (or later). Its purpose is to initialise a
number of sub-systems that can then be used in a consistent way in all
the databases you make use of in the environment.
If you don't intend using transactions, locking or logging, then you
shouldn't need to make use of B<BerkeleyDB::Env>.
Note that an environment consists of a number of files that Berkeley DB
manages behind the scenes for you. When you first use an environment, it
needs to be explicitly created. This is done by including C<DB_CREATE>
with the C<Flags> parameter, described below.
=head2 Synopsis
$env = new BerkeleyDB::Env
[ -Home => $path, ]
[ -Server => $name, ]
[ -CacheSize => $number, ]
[ -Config => { name => value, name => value }, ]
[ -ErrFile => filename, ]
[ -MsgFile => filename, ]
[ -ErrPrefix => "string", ]
[ -Flags => number, ]
[ -SetFlags => bitmask, ]
[ -LockDetect => number, ]
[ -TxMax => number, ]
[ -LogConfig => number, ]
[ -MaxLockers => number, ]
[ -MaxLocks => number, ]
[ -MaxObjects => number, ]
[ -SharedMemKey => number, ]
[ -Verbose => boolean, ]
[ -BlobThreshold=> $number, ]
[ -BlobDir => directory, ]
[ -Encrypt => { Password => "string",
Flags => number }, ]
All the parameters to the BerkeleyDB::Env constructor are optional.
=over 5
=item -Home
If present, this parameter should point to an existing directory. Any
files that I<aren't> specified with an absolute path in the sub-systems
that are initialised by the BerkeleyDB::Env class will be assumed to
live in the B<Home> directory.
For example, in the code fragment below the database "fred.db" will be
opened in the directory "/home/databases" because it was specified as a
relative path, but "joe.db" will be opened in "/other" because it was
part of an absolute path.
$env = new BerkeleyDB::Env
-Home => "/home/databases"
...
$db1 = new BerkeleyDB::Hash
-Filename => "fred.db",
-Env => $env
...
$db2 = new BerkeleyDB::Hash
-Filename => "/other/joe.db",
-Env => $env
...
=item -Server
If present, this parameter should be the hostname of a server that is running
the Berkeley DB RPC server. All databases will be accessed via the RPC server.
=item -Encrypt
If present, this parameter will enable encryption of all data before
it is written to the database. This parameters must be given a hash
reference. The format is shown below.
-Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }
Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.
This option requires Berkeley DB 4.1 or better.
=item -Cachesize
If present, this parameter sets the size of the environments shared memory
buffer pool.
=item -TxMax
If present, this parameter sets the number of simultaneous
transactions that are allowed. Default 100. This default is
definitely too low for programs using the MVCC capabilities.
=item -LogConfig
If present, this parameter is used to configure log options.
=item -MaxLockers
If present, this parameter is used to configure the maximum number of
processes doing locking on the database. Default 1000.
=item -MaxLocks
If present, this parameter is used to configure the maximum number of
locks on the database. Default 1000. This is often lower than required.
=item -MaxObjects
If present, this parameter is used to configure the maximum number of
locked objects. Default 1000. This is often lower than required.
=item -SharedMemKey
If present, this parameter sets the base segment ID for the shared memory
region used by Berkeley DB.
This option requires Berkeley DB 3.1 or better.
Use C<$env-E<gt>get_shm_key($id)> to find out the base segment ID used
once the environment is open.
=item -ThreadCount
If present, this parameter declares the approximate number of threads that
will be used in the database environment. This parameter is only necessary
when the $env->failchk method will be used. It does not actually set the
maximum number of threads but rather is used to determine memory sizing.
This option requires Berkeley DB 4.4 or better. It is only supported on
Unix/Linux.
=item -BlobThreshold
Sets the size threshold that will be used to decide when data is stored as
a BLOB. This option must be set for a blobs to be used.
This option requires Berkeley DB 6.0 or better.
=item -BlobDir
The directory where the BLOB objects are stored.
If not specified blob files are stores in the environment directoy.
This option requires Berkeley DB 6.0 or better.
=item -Config
This is a variation on the C<-Home> parameter, but it allows finer
control of where specific types of files will be stored.
The parameter expects a reference to a hash. Valid keys are:
B<DB_DATA_DIR>, B<DB_LOG_DIR> and B<DB_TMP_DIR>
The code below shows an example of how it can be used.
$env = new BerkeleyDB::Env
-Config => { DB_DATA_DIR => "/home/databases",
DB_LOG_DIR => "/home/logs",
DB_TMP_DIR => "/home/tmp"
}
...
=item -ErrFile
Expects a filename or filehandle. Any errors generated internally by
Berkeley DB will be logged to this file. A useful debug setting is to
open environments with either
-ErrFile => *STDOUT
or
-ErrFile => *STDERR
=item -ErrPrefix
Allows a prefix to be added to the error messages before they are sent
to B<-ErrFile>.
=item -Flags
The B<Flags> parameter specifies both which sub-systems to initialise,
as well as a number of environment-wide options.
See the Berkeley DB documentation for more details of these options.
Any of the following can be specified by OR'ing them:
B<DB_CREATE>
If any of the files specified do not already exist, create them.
B<DB_INIT_CDB>
Initialise the Concurrent Access Methods
B<DB_INIT_LOCK>
Initialise the Locking sub-system.
B<DB_INIT_LOG>
Initialise the Logging sub-system.
B<DB_INIT_MPOOL>
Initialize the shared memory buffer pool subsystem. This subsystem should be used whenever an application is using any Berkeley DB access method.
B<DB_INIT_TXN>
Initialize the transaction subsystem. This subsystem should be used when recovery and atomicity of multiple operations are important. The DB_INIT_TXN flag implies the DB_INIT_LOG flag.
B<DB_MPOOL_PRIVATE>
Create a private memory pool; see memp_open. Ignored unless DB_INIT_MPOOL is also specified.
B<DB_INIT_MPOOL> is also specified.
B<DB_NOMMAP>
Do not map this database into process memory.
B<DB_RECOVER>
Run normal recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.
The db_appinit function returns successfully if DB_RECOVER is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery.
B<DB_PRIVATE>
B<DB_RECOVER_FATAL>
Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.
The db_appinit function returns successfully if DB_RECOVER_FATAL is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery.
B<DB_THREAD>
Ensure that handles returned by the Berkeley DB subsystems are useable by multiple threads within a single process, i.e., that the system is free-threaded.
B<DB_TXN_NOSYNC>
On transaction commit, do not synchronously flush the log; see txn_open. Ignored unless DB_INIT_TXN is also specified.
B<DB_USE_ENVIRON>
The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, environment information will be used in file naming for all users only if the DB_USE_ENVIRON flag is set.
B<DB_USE_ENVIRON_ROOT>
The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, if the DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with a user-ID matching that of the superuser (specifically, users for whom the getuid(2) system call returns the user-ID 0).
=item -SetFlags
Calls ENV->set_flags with the supplied bitmask. Use this when you need to make
use of DB_ENV->set_flags before DB_ENV->open is called.
Only valid when Berkeley DB 3.x or better is used.
=item -LockDetect
Specifies what to do when a lock conflict occurs. The value should be one of
B<DB_LOCK_DEFAULT>
Use the default policy as specified by db_deadlock.
B<DB_LOCK_OLDEST>
Abort the oldest transaction.
B<DB_LOCK_RANDOM>
Abort a random transaction involved in the deadlock.
B<DB_LOCK_YOUNGEST>
Abort the youngest transaction.
=item -Verbose
Add extra debugging information to the messages sent to B<-ErrFile>.
=back
=head2 Methods
The environment class has the following methods:
=over 5
=item $env->errPrefix("string") ;
This method is identical to the B<-ErrPrefix> flag. It allows the
error prefix string to be changed dynamically.
=item $env->set_flags(bitmask, 1|0);
=item $txn = $env->TxnMgr()
Constructor for creating a B<TxnMgr> object.
See L<"TRANSACTIONS"> for more details of using transactions.
This method is deprecated. Access the transaction methods using the B<txn_>
methods below from the environment object directly.
=item $env->txn_begin()
TODO
=item $env->txn_stat()
TODO
=item $env->txn_checkpoint()
TODO
=item $env->status()
Returns the status of the last BerkeleyDB::Env method.
=item $env->DB_ENV()
Returns a pointer to the underlying DB_ENV data structure that Berkeley
DB uses.
=item $env->get_shm_key($id)
Writes the base segment ID for the shared memory region used by the
Berkeley DB environment into C<$id>. Returns 0 on success.
This option requires Berkeley DB 4.2 or better.
Use the C<-SharedMemKey> option when opening the environmet to set the
base segment ID.
=item $env->set_isalive()
Set the callback that determines if the thread of control, identified by
the pid and tid arguments, is still running. This method should only be
used in combination with $env->failchk.
This option requires Berkeley DB 4.4 or better.
=item $env->failchk($flags)
The $env->failchk method checks for threads of control (either a true
thread or a process) that have exited while manipulating Berkeley DB
library data structures, while holding a logical database lock, or with an
unresolved transaction (that is, a transaction that was never aborted or
committed).
If $env->failchk determines a thread of control exited while holding
database read locks, it will release those locks. If $env->failchk
determines a thread of control exited with an unresolved transaction, the
transaction will be aborted.
Applications calling the $env->failchk method must have already called the
$env->set_isalive method, on the same DB environment, and must have
configured their database environment using the -ThreadCount flag. The
ThreadCount flag cannot be used on an environment that wasn't previously
initialized with it.
This option requires Berkeley DB 4.4 or better.
=item $env->stat_print
Prints statistical information.
If the C<MsgFile> option is specified the output will be sent to the
file. Otherwise output is sent to standard output.
This option requires Berkeley DB 4.3 or better.
=item $env->lock_stat_print
Prints locking subsystem statistics.
If the C<MsgFile> option is specified the output will be sent to the
file. Otherwise output is sent to standard output.
This option requires Berkeley DB 4.3 or better.
=item $env->mutex_stat_print
Prints mutex subsystem statistics.
If the C<MsgFile> option is specified the output will be sent to the
file. Otherwise output is sent to standard output.
This option requires Berkeley DB 4.4 or better.
=item $status = $env->get_blob_threshold($t1) ;
Sets the parameter $t1 to the threshold value (in bytes) that is used to
determine when a data item is stored as a Blob.
=item $status = $env->get_blob_dir($dir) ;
Sets the $dir parameter to the directory where blob files are stored.
=item $env->set_timeout($timeout, $flags)
=item $env->status()
Returns the status of the last BerkeleyDB::Env method.
=back
=head2 Examples
TODO.
=head1 Global Classes
$status = BerkeleyDB::db_remove [OPTIONS]
$status = BerkeleyDB::db_rename [OPTIONS]
$status = BerkeleyDB::db_verify [OPTIONS]
=head1 THE DATABASE CLASSES
B<BerkeleyDB> supports the following database formats:
=over 5
=item B<BerkeleyDB::Hash>
This database type allows arbitrary key/value pairs to be stored in data
files. This is equivalent to the functionality provided by other
hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
the files created using B<BerkeleyDB::Hash> are not compatible with any
of the other packages mentioned.
A default hashing algorithm, which will be adequate for most applications,
is built into BerkeleyDB. If you do need to use your own hashing algorithm
it is possible to write your own in Perl and have B<BerkeleyDB> use
it instead.
=item B<BerkeleyDB::Btree>
The Btree format allows arbitrary key/value pairs to be stored in a
B+tree.
As with the B<BerkeleyDB::Hash> format, it is possible to provide a
user defined Perl routine to perform the comparison of keys. By default,
though, the keys are stored in lexical order.
=item B<BerkeleyDB::Recno>
TODO.
=item B<BerkeleyDB::Queue>
TODO.
=item B<BerkeleyDB::Heap>
TODO.
=item B<BerkeleyDB::Unknown>
This isn't a database format at all. It is used when you want to open an
existing Berkeley DB database without having to know what type is it.
=back
Each of the database formats described above is accessed via a
corresponding B<BerkeleyDB> class. These will be described in turn in
the next sections.
=head1 BerkeleyDB::Hash
Equivalent to calling B<db_open> with type B<DB_HASH> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_HASH> in
Berkeley DB 3.x or greater.
Two forms of constructor are supported:
$db = new BerkeleyDB::Hash
[ -Filename => "filename", ]
[ -Subname => "sub-database name", ]
[ -Flags => flags,]
[ -Property => flags,]
[ -Mode => number,]
[ -Cachesize => number,]
[ -Lorder => number,]
[ -Pagesize => number,]
[ -Env => $env,]
[ -Txn => $txn,]
[ -Encrypt => { Password => "string",
Flags => number }, ],
[ -BlobThreshold=> $number, ]
[ -BlobDir => directory, ]
# BerkeleyDB::Hash specific
[ -Ffactor => number,]
[ -Nelem => number,]
[ -Hash => code reference,]
[ -DupCompare => code reference,]
and this
[$db =] tie %hash, 'BerkeleyDB::Hash',
[ -Filename => "filename", ]
[ -Subname => "sub-database name", ]
[ -Flags => flags,]
[ -Property => flags,]
[ -Mode => number,]
[ -Cachesize => number,]
[ -Lorder => number,]
[ -Pagesize => number,]
[ -Env => $env,]
[ -Txn => $txn,]
[ -Encrypt => { Password => "string",
Flags => number }, ],
[ -BlobThreshold=> $number, ]
[ -BlobDir => directory, ]
# BerkeleyDB::Hash specific
[ -Ffactor => number,]
[ -Nelem => number,]
[ -Hash => code reference,]
[ -DupCompare => code reference,]
When the "tie" interface is used, reading from and writing to the database
is achieved via the tied hash. In this case the database operates like
a Perl associative array that happens to be stored on disk.
In addition to the high-level tied hash interface, it is possible to
make use of the underlying methods provided by Berkeley DB
=head2 Options
In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Hash> supports these options:
=over 5
=item -Property
Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:
B<DB_DUP>
When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.
B<DB_DUPSORT>
Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.
=item -Ffactor
=item -Nelem
See the Berkeley DB documentation for details of these options.
=item -Hash
Allows you to provide a user defined hash function. If not specified,
a default hash function is used. Here is a template for a user-defined
hash function
sub hash
{
my ($data) = shift ;
...
# return the hash value for $data
return $hash ;
}
tie %h, "BerkeleyDB::Hash",
-Filename => $filename,
-Hash => \&hash,
...
See L<""> for an example.
=item -DupCompare
Used in conjunction with the B<DB_DUPOSRT> flag.
sub compare
{
my ($key, $key2) = @_ ;
...
# return 0 if $key1 eq $key2
# -1 if $key1 lt $key2
# 1 if $key1 gt $key2
return (-1 , 0 or 1) ;
}
tie %h, "BerkeleyDB::Hash",
-Filename => $filename,
-Property => DB_DUP|DB_DUPSORT,
-DupCompare => \&compare,
...
=back
=head2 Methods
B<BerkeleyDB::Hash> only supports the standard database methods.
See L<COMMON DATABASE METHODS>.
=head2 A Simple Tied Hash Example
## simpleHash
here is the output:
Banana Exists
orange -> orange
tomato -> red
banana -> yellow
Note that the like ordinary associative arrays, the order of the keys
retrieved from a Hash database are in an apparently random order.
=head2 Another Simple Hash Example
Do the same as the previous example but not using tie.
## simpleHash2
=head2 Duplicate keys
The code below is a variation on the examples above. This time the hash has
been inverted. The key this time is colour and the value is the fruit name.
The B<DB_DUP> flag has been specified to allow duplicates.
##dupHash
here is the output:
orange -> orange
yellow -> banana
red -> apple
red -> tomato
green -> banana
green -> apple
=head2 Sorting Duplicate Keys
In the previous example, when there were duplicate keys, the values are
sorted in the order they are stored in. The code below is
identical to the previous example except the B<DB_DUPSORT> flag is
specified.
##dupSortHash
Notice that in the output below the duplicate values are sorted.
orange -> orange
yellow -> banana
red -> apple
red -> tomato
green -> apple
green -> banana
=head2 Custom Sorting Duplicate Keys
Another variation
TODO
=head2 Changing the hash
TODO
=head2 Using db_stat
TODO
=head1 BerkeleyDB::Btree
Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in
Berkeley DB 3.x or greater.
Two forms of constructor are supported:
$db = new BerkeleyDB::Btree
[ -Filename => "filename", ]
[ -Subname => "sub-database name", ]
[ -Flags => flags,]
[ -Property => flags,]
[ -Mode => number,]
[ -Cachesize => number,]
[ -Lorder => number,]
[ -Pagesize => number,]
[ -Env => $env,]
[ -Txn => $txn,]
[ -Encrypt => { Password => "string",
Flags => number }, ],
[ -BlobThreshold=> $number, ]
[ -BlobDir => directory, ]
# BerkeleyDB::Btree specific
[ -Minkey => number,]
[ -Compare => code reference,]
[ -DupCompare => code reference,]
[ -Prefix => code reference,]
and this
[$db =] tie %hash, 'BerkeleyDB::Btree',
[ -Filename => "filename", ]
[ -Subname => "sub-database name", ]
[ -Flags => flags,]
[ -Property => flags,]
[ -Mode => number,]
[ -Cachesize => number,]
[ -Lorder => number,]
[ -Pagesize => number,]
[ -Env => $env,]
[ -Txn => $txn,]
[ -Encrypt => { Password => "string",
Flags => number }, ],
[ -BlobThreshold=> $number, ]
[ -BlobDir => directory, ]
# BerkeleyDB::Btree specific
[ -Minkey => number,]
[ -Compare => code reference,]
[ -DupCompare => code reference,]
[ -Prefix => code reference,]
=head2 Options
In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Btree> supports these options:
=over 5
=item -Property
Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:
B<DB_DUP>
When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.
B<DB_DUPSORT>
Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.
=item Minkey
TODO
=item Compare
Allow you to override the default sort order used in the database. See
L<"Changing the sort order"> for an example.
sub compare
{
my ($key, $key2) = @_ ;
...
# return 0 if $key1 eq $key2
# -1 if $key1 lt $key2
# 1 if $key1 gt $key2
return (-1 , 0 or 1) ;
}
tie %h, "BerkeleyDB::Hash",
-Filename => $filename,
-Compare => \&compare,
...
=item Prefix
sub prefix
{
my ($key, $key2) = @_ ;
...
# return number of bytes of $key2 which are
# necessary to determine that it is greater than $key1
return $bytes ;
}
tie %h, "BerkeleyDB::Hash",
-Filename => $filename,
-Prefix => \&prefix,
...
=item DupCompare
sub compare
{
my ($key, $key2) = @_ ;
...
# return 0 if $key1 eq $key2
# -1 if $key1 lt $key2
# 1 if $key1 gt $key2
return (-1 , 0 or 1) ;
}
tie %h, "BerkeleyDB::Hash",
-Filename => $filename,
-DupCompare => \&compare,
...
=item set_bt_compress
Enabled compression of the btree data. The callback interface is not
supported at present. Need Berkeley DB 4.8 or better.
=back
=head2 Methods
B<BerkeleyDB::Btree> supports the following database methods.
See also L<COMMON DATABASE METHODS>.
All the methods below return 0 to indicate success.
=over 5
=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])
Given a key, C<$key>, this method returns the proportion of keys less than
C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
proportion greater than C<$key> in C<$greater>.