diff options
Diffstat (limited to 'docs/programmer_reference/program_copy.html')
| -rw-r--r-- | docs/programmer_reference/program_copy.html | 150 |
1 files changed, 88 insertions, 62 deletions
diff --git a/docs/programmer_reference/program_copy.html b/docs/programmer_reference/program_copy.html index 03baefb6..d9db8746 100644 --- a/docs/programmer_reference/program_copy.html +++ b/docs/programmer_reference/program_copy.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="program_cache.html">Prev</a> </td> - <th width="60%" align="center">Chapter 15. - Programmer Notes - </th> + <th width="60%" align="center">Chapter 15. Programmer Notes </th> <td width="20%" align="right"> <a accesskey="n" href="program_compatible.html">Next</a></td> </tr> </table> @@ -38,68 +36,96 @@ </div> </div> </div> - <p>There are two issues with copying or moving databases: database page log -sequence numbers (LSNs), and database file identification strings.</p> - <p>Because database pages contain references to the database environment -log records (LSNs), databases cannot be copied or moved from one -transactional database environment to another without first clearing the -LSNs. Note that this is not a concern for non-transactional database -environments and applications, and can be ignored if the database is not -being used transactionally. Specifically, databases created and written -non-transactionally (for example, as part of a bulk load procedure), can -be copied or moved into a transactional database environment without -resetting the LSNs. The database's LSNs may be reset in one of three -ways: the application can call the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV->lsn_reset()</a> method to reset the -LSNs in place, or a system administrator can reset the LSNs in place -using the <span class="bold"><strong>-r</strong></span> option to the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility, or by -dumping and reloading the database (using the <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility and the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility).</p> - <p>Because system file identification information (for example, filenames, -device and inode numbers, volume and file IDs, and so on) are not -necessarily unique or maintained across system reboots, each Berkeley DB -database file contains a unique 20-byte file identification bytestring. -When multiple processes or threads open the same database file in Berkeley DB, -it is this bytestring that is used to ensure the same underlying pages -are updated in the database environment cache, no matter which Berkeley DB -handle is used for the operation.</p> - <p>The database file identification string is not a concern when moving -databases, and databases may be moved or renamed without resetting the -identification string. However, when copying a database, you must -ensure there are never two databases with the same file identification -bytestring in the same cache at the same time. Copying databases is -further complicated because Berkeley DB caches do not discard cached database -pages when database handles are closed. Cached pages are only discarded -when the database is removed by calling the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> or -<a href="../api_reference/C/dbremove.html" class="olink">DB->remove()</a> methods.</p> - <p>Before physically copying a database file, first ensure that all -modified pages have been written from the cache to the backing database -file. This is done using the <a href="../api_reference/C/dbsync.html" class="olink">DB->sync()</a> or <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a> methods.</p> - <p>Before using a copy of a database file in a database environment, you -must ensure that all pages from any other database with the same -bytestring have been removed from the memory pool cache. If the -environment in which you will open the copy of the database has pages -from files with identical bytestrings to the copied database, there are -a few possible solutions:</p> + <p> + There are two issues with copying or moving databases: + database page log sequence numbers (LSNs), and database file + identification strings. + </p> + <p> + Because database pages contain references to the database + environment log records (LSNs), databases cannot be copied or + moved from one transactional database environment to another + without first clearing the LSNs. Note that this is not a + concern for non-transactional database environments and + applications, and can be ignored if the database is not being + used transactionally. Specifically, databases created and + written non-transactionally (for example, as part of a bulk + load procedure), can be copied or moved into a transactional + database environment without resetting the LSNs. The + database's LSNs may be reset in one of three ways: the + application can call the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV->lsn_reset()</a> method to reset the + LSNs in place, or a system administrator can reset the LSNs in + place using the <span class="bold"><strong>-r</strong></span> option to + the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility, or by dumping and reloading the database (using + the <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility and the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility). + </p> + <p> + Because system file identification information (for example, + filenames, device and inode numbers, volume and file IDs, and + so on) are not necessarily unique or maintained across system + reboots, each Berkeley DB database file contains a unique + 20-byte file identification bytestring. When multiple + processes or threads open the same database file in Berkeley + DB, it is this bytestring that is used to ensure the same + underlying pages are updated in the database environment + cache, no matter which Berkeley DB handle is used for the + operation. + </p> + <p> + The database file identification string is not a concern + when moving databases, and databases may be moved or renamed + without resetting the identification string. However, when + copying a database, you must ensure there are never two + databases with the same file identification bytestring in the + same cache at the same time. Copying databases is further + complicated because Berkeley DB caches do not discard cached + database pages when database handles are closed. Cached pages + are only discarded when the database is removed by calling the + <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> or <a href="../api_reference/C/dbremove.html" class="olink">DB->remove()</a> methods. + </p> + <p> + Before physically copying a database file, first ensure that + all modified pages have been written from the cache to the + backing database file. This is done using the <a href="../api_reference/C/dbsync.html" class="olink">DB->sync()</a> or + <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a> methods. + </p> + <p> + Before using a copy of a database file in a database + environment, you must ensure that all pages from any other + database with the same bytestring have been removed from the + memory pool cache. If the environment in which you will open + the copy of the database has pages from files with identical + bytestrings to the copied database, there are a few possible + solutions: + </p> <div class="orderedlist"> <ol type="1"> - <li>Remove the environment, either using system utilities or by calling the -<a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. Obviously, this will not allow you to access -both the original database and the copy of the database at the same -time.</li> <li> - Create a new file that will have a new bytestring. The simplest way to - create a new file that will have a new bytestring is to call the - <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility to dump out the contents of the database and then use the - <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility to load the dumped output into a new file. This allows you - to access both the original and copy of the database at the same time. -</li> + Remove the environment, either using system + utilities or by calling the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. Obviously, + this will not allow you to access both the original + database and the copy of the database at the same + time. + </li> <li> - If your database is too large to be dumped and reloaded, you can copy - the database by other means, and then reset the bytestring in the - copied database to a new bytestring. There are two ways to reset the - bytestring in the copy: the application can call the <a href="../api_reference/C/envfileid_reset.html" class="olink">DB_ENV->fileid_reset()</a> - method, or a system administrator can use the <span class="bold"><strong>-r</strong></span> option to the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility. This allows you - to access both the original and copy of the database at the same time. -</li> + Create a new file that will have a new bytestring. + The simplest way to create a new file that will have a new + bytestring is to call the <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility to dump out the + contents of the database and then use the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility to + load the dumped output into a new file. This allows you to + access both the original and copy of the database at the + same time. + </li> + <li> + If your database is too large to be dumped and + reloaded, you can copy the database by other means, and + then reset the bytestring in the copied database to a new + bytestring. There are two ways to reset the bytestring in + the copy: the application can call the <a href="../api_reference/C/envfileid_reset.html" class="olink">DB_ENV->fileid_reset()</a> + method, or a system administrator can use the <span class="bold"><strong>-r</strong></span> option to the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility. + This allows you to access both the original and copy of + the database at the same time. + </li> </ol> </div> </div> |