1<!--$Id: copy.so,v 10.17 2005/06/16 17:07:07 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Copying or moving databases</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></b></td> 13<td align=right><a href="/program/cache.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/program/compatible.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Copying or moving databases</b></p> 16<a name="2"><!--meow--></a> 17<a name="3"><!--meow--></a> 18<p>There are two issues with copying or moving databases: database page log 19sequence numbers (LSNs), and database file identification strings.</p> 20<p>Because database pages contain references to the database environment 21log records (LSNs), databases cannot be copied or moved from one 22transactional database environment to another without first clearing the 23LSNs. Note that this is not a concern for non-transactional database 24environments and applications, and can be ignored if the database is not 25being used transactionally. Specifically, databases created and written 26non-transactionally (for example, as part of a bulk load procedure), can 27be copied or moved into a transactional database environment without 28resetting the LSNs. The database's LSNs may be reset in one of three 29ways: the application can call the <a href="/api_c/env_lsn_reset.html">DB_ENV->lsn_reset</a> method to reset the 30LSNs in place, or a system administrator can reset the LSNs in place 31using the <b>-r</b> option to the <a href="/utility/db_load.html">db_load</a> utility, or by 32dumping and reloading the database (using the <a href="/utility/db_dump.html">db_dump</a> and 33<a href="/utility/db_load.html">db_load</a> utilities).</p> 34<p>Because system file identification information (for example, filenames, 35device and inode numbers, volume and file IDs, and so on) are not 36necessarily unique or maintained across system reboots, each Berkeley DB 37database file contains a unique 20-byte file identification bytestring. 38When multiple processes or threads open the same database file in Berkeley DB, 39it is this bytestring that is used to ensure the same underlying pages 40are updated in the database environment cache, no matter which Berkeley DB 41handle is used for the operation.</p> 42<p>The database file identification string is not a concern when moving 43databases, and databases may be moved or renamed without resetting the 44identification string. However, when copying a database, you must 45ensure there are never two databases with the same file identification 46bytestring in the same cache at the same time. Copying databases is 47further complicated because Berkeley DB caches do not discard cached database 48pages when database handles are closed. Cached pages are only discarded 49when the database is removed by calling the <a href="/api_c/env_remove.html">DB_ENV->remove</a> or 50<a href="/api_c/db_remove.html">DB->remove</a> methods.</p> 51<p>Before physically copying a database file, first ensure that all 52modified pages have been written from the cache to the backing database 53file. This is done using the <a href="/api_c/db_sync.html">DB->sync</a> or <a href="/api_c/db_close.html">DB->close</a> methods.</p> 54<p>Before using a copy of a database file in a database environment, you 55must ensure that all pages from any other database with the same 56bytestring have been removed from the memory pool cache. If the 57environment in which you will open the copy of the database has pages 58from files with identical bytestrings to the copied database, there are 59a few possible solutions:</p> 60<ol> 61<p><li>Remove the environment, either using system utilities or by calling the 62<a href="/api_c/env_remove.html">DB_ENV->remove</a> method. Obviously, this will not allow you to access 63both the original database and the copy of the database at the same 64time. 65<p><li>Create a new file that will have a new bytestring. The simplest way to 66create a new file that will have a new bytestring is to call the 67<a href="/utility/db_dump.html">db_dump</a> utility to dump out the contents of the database and 68then use the <a href="/utility/db_load.html">db_load</a> utility to load the dumped output into a 69new file. This allows you to access both the original and copy of the 70database at the same time. 71<p><li>If your database is too large to be dumped and reloaded, you can copy 72the database by other means, and then reset the bytestring in the copied 73database to a new bytestring. There are two ways to reset the 74bytestring in the copy: the application can call the 75<a href="/api_c/env_fileid_reset.html">DB_ENV->fileid_reset</a> method, or a system administrator can use the 76<b>-r</b> option to the <a href="/utility/db_load.html">db_load</a> utility. This allows you to 77access both the original and copy of the database at the same time. 78</ol> 79<table width="100%"><tr><td><br></td><td align=right><a href="/program/cache.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/program/compatible.html"><img src="/images/next.gif" alt="Next"></a> 80</td></tr></table> 81<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 82</body> 83</html> 84
