Oracle Berkeley DB Programmer's Reference Guide 11g Release 2 Legal Notice This documentation is distributed under an open source license. You may review the terms of this license at: http:// www.oracle.com/technology/software/products/berkeley-db/htdocs/oslicense.html Oracle, Berkeley DB, and Sleepycat are trademarks or registered trademarks of Oracle. All rights to these marks are reserved. No third-party use is permitted without the express prior written consent of Oracle. Other names may be trademarks of their respective owners. To obtain a copy of this document's original source code, please submit a request to the Oracle Technology Network forum at: http://forums.oracle.com/forums/forum.jspa?forumID=271 Published 3/30/2010 Table of Contents Preface ....................................................................................................... x Conventions Used in this Book .................................................................... x For More Information ......................................................................... x 1. Introduction ............................................................................................ 1 An introduction to data management ............................................................ 1 Mapping the terrain: theory and practice ....................................................... 1 Data access and data management ........................................................ 2 Relational databases .......................................................................... 3 Object-oriented databases .................................................................. 4 Network databases ............................................................................ 4 Clients and servers ........................................................................... 5 What is Berkeley DB? ............................................................................... 6 Data Access Services ......................................................................... 7 Data management services .................................................................. 7 Design ........................................................................................... 8 What Berkeley DB is not ........................................................................... 8 Berkeley DB is not a relational database ................................................. 9 Berkeley DB is not an object-oriented database ....................................... 10 Berkeley DB is not a network database .................................................. 10 Berkeley DB is not a database server .................................................... 10 Do you need Berkeley DB? ........................................................................ 11 What other services does Berkeley DB provide? .............................................. 11 What does the Berkeley DB distribution include? ............................................. 12 Where does Berkeley DB run? .................................................................... 12 The Berkeley DB products ........................................................................ 13 Berkeley DB Data Store ..................................................................... 14 Berkeley DB Concurrent Data Store ...................................................... 14 Berkeley DB Transactional Data Store .................................................... 14 Berkeley DB High Availability .............................................................. 14 2. Access Method Configuration ....................................................................... 15 What are the available access methods? ....................................................... 15 Btree ........................................................................................... 15 Hash ............................................................................................ 15 Queue .......................................................................................... 15 Recno .......................................................................................... 15 Selecting an access method ...................................................................... 15 Hash or Btree? ............................................................................... 16 Queue or Recno? ............................................................................. 17 Logical record numbers ........................................................................... 17 General access method configuration .......................................................... 19 Selecting a page size ....................................................................... 19 Selecting a cache size ...................................................................... 20 Selecting a byte order ...................................................................... 21 Duplicate data items ........................................................................ 22 Non-local memory allocation .............................................................. 23 Btree access method specific configuration ................................................... 23 3/30/2010 DB Reference Guide Page iii Btree comparison ............................................................................ 23 Btree prefix comparison .................................................................... 25 Minimum keys per page .................................................................... 26 Retrieving Btree records by logical record number .................................... 26 Compression .................................................................................. 28 Custom compression .................................................................. 29 Programmer Notes .................................................................... 32 Hash access method specific configuration .................................................... 33 Page fill factor ............................................................................... 33 Specifying a database hash ................................................................ 33 Hash table size ............................................................................... 33 Queue and Recno access method specific configuration ..................................... 34 Managing record-based databases ........................................................ 34 Record Delimiters ..................................................................... 34 Record Length ......................................................................... 34 Record Padding Byte Value .......................................................... 34 Selecting a Queue extent size ............................................................. 35 Flat-text backing files ...................................................................... 35 Logically renumbering records ............................................................ 36 3. Access Method Operations .......................................................................... 38 Database open ...................................................................................... 39 Opening multiple databases in a single file ................................................... 40 Configuring databases sharing a file ...................................................... 41 Caching databases sharing a file .......................................................... 41 Locking in databases based on sharing a file ........................................... 41 Partitioning databases ............................................................................. 42 Specifying partition keys ................................................................... 42 Partitioning callback ........................................................................ 44 Placing partition files ....................................................................... 45 Retrieving records .................................................................................. 46 Storing records ..................................................................................... 46 Deleting records .................................................................................... 47 Database statistics ................................................................................. 47 Database truncation ............................................................................... 47 Database upgrade .................................................................................. 47 Database verification and salvage ............................................................... 48 Flushing the database cache ..................................................................... 48 Database close ...................................................................................... 49 Secondary indexes ................................................................................. 49 Error Handling With Secondary Indexes .................................................. 53 Foreign key indexes ............................................................................... 54 Cursor operations .................................................................................. 57 Retrieving records with a cursor .......................................................... 57 Cursor position flags .................................................................