m4_comment([$Id: copy.so,v 10.17 2005/06/16 17:07:07 bostic Exp $])m4_ref_title(Programmer Notes,    Copying or moving databases,, program/cache, program/compatible)m4_idefz(copying databases)m4_idefz(moving databases)m4_p([dnlThere are two issues with copying or moving databases: database page logsequence numbers (LSNs), and database file identification strings.])m4_p([dnlBecause database pages contain references to the database environmentlog records (LSNs), databases cannot be copied or moved from onetransactional database environment to another without first clearing theLSNs.  Note that this is not a concern for non-transactional databaseenvironments and applications, and can be ignored if the database is notbeing used transactionally.  Specifically, databases created and writtennon-transactionally (for example, as part of a bulk load procedure), canbe copied or moved into a transactional database environment withoutresetting the LSNs.  The database's LSNs may be reset in one of threeways: the application can call the m4_refT(dbenv_lsn_reset) to reset theLSNs in place, or a system administrator can reset the LSNs in placeusing the m4_option(r) option to the m4_ref(db_load) utility, or bydumping and reloading the database (using the m4_ref(db_dump) andm4_ref(db_load) utilities).])m4_p([dnlBecause system file identification information (for example, filenames,device and inode numbers, volume and file IDs, and so on) are notnecessarily unique or maintained across system reboots, each m4_dbdatabase file contains a unique 20-byte file identification bytestring.When multiple processes or threads open the same database file in m4_db,it is this bytestring that is used to ensure the same underlying pagesare updated in the database environment cache, no matter which m4_dbhandle is used for the operation.])m4_p([dnlThe database file identification string is not a concern when movingdatabases, and databases may be moved or renamed without resetting theidentification string.  However, when copying a database, you mustensure there are never two databases with the same file identificationbytestring in the same cache at the same time.  Copying databases isfurther complicated because m4_db caches do not discard cached databasepages when database handles are closed.  Cached pages are only discardedwhen the database is removed by calling the m4_ref(dbenv_remove) orm4_refT(dbh_remove)s.])m4_p([dnlBefore physically copying a database file, first ensure that allmodified pages have been written from the cache to the backing databasefile.  This is done using the m4_ref(dbh_sync) or m4_refT(dbh_close)s.])m4_p([dnlBefore using a copy of a database file in a database environment, youmust ensure that all pages from any other database with the samebytestring have been removed from the memory pool cache.  If theenvironment in which you will open the copy of the database has pagesfrom files with identical bytestrings to the copied database, there area few possible solutions:])m4_nlistbeginm4_nlist([dnlRemove the environment, either using system utilities or by calling them4_refT(dbenv_remove).  Obviously, this will not allow you to accessboth the original database and the copy of the database at the sametime.])m4_nlist([dnlCreate a new file that will have a new bytestring.  The simplest way tocreate a new file that will have a new bytestring is to call them4_ref(db_dump) utility to dump out the contents of the database andthen use the m4_ref(db_load) utility to load the dumped output into anew file.  This allows you to access both the original and copy of thedatabase at the same time.])m4_nlist([dnlIf your database is too large to be dumped and reloaded, you can copythe database by other means, and then reset the bytestring in the copieddatabase to a new bytestring.  There are two ways to reset thebytestring in the copy: the application can call them4_refT(dbenv_fileid_reset), or a system administrator can use them4_option(r) option to the m4_ref(db_load) utility.  This allows you toaccess both the original and copy of the database at the same time.])m4_nlistendm4_page_footer