← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/transapp/archival.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/ref/transapp/archival.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB Reference Guide: Database and log file archival</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a><a name="3"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td>
15
 
<td align=right><a href="../../ref/transapp/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/logfile.html"><img src="../../images/next.gif" alt="Next"></a>
16
 
</td></tr></table>
17
 
<p>
18
 
<h1 align=center>Database and log file archival</h1>
19
 
<p>The third component of the administrative infrastructure, archival for
20
 
catastrophic recovery, concerns the recoverability of the database in
21
 
the face of catastrophic failure.  Recovery after catastrophic failure
22
 
is intended to minimize data loss when physical hardware has been
23
 
destroyed -- for example, loss of a disk that contains databases or log
24
 
files.  Although the application may still experience data loss in this
25
 
case, it is possible to minimize it.
26
 
<p>First, you may want to periodically create snapshots (that is, backups)
27
 
of your databases to make it possible to recover from catastrophic
28
 
failure.  These snapshots are either a standard backup, which creates a
29
 
consistent picture of the databases as of a single instant in time; or
30
 
an on-line backup (also known as a <i>hot</i> backup), which creates
31
 
a consistent picture of the databases as of an unspecified instant
32
 
during the period of time when the snapshot was made.  The advantage of
33
 
a hot backup is that applications may continue to read and write the
34
 
databases while the snapshot is being taken.  The disadvantage of a hot
35
 
backup is that more information must be archived, and recovery based on
36
 
a hot backup is to an unspecified time between the start of the backup
37
 
and when the backup is completed.
38
 
<p>Second, after taking a snapshot, you should periodically archive the
39
 
log files being created in the environment.  It is often helpful to
40
 
think of database archival in terms of full and incremental filesystem
41
 
backups.  A snapshot is a full backup, whereas the periodic archival of
42
 
the current log files is an incremental backup.  For example, it might
43
 
be reasonable to take a full snapshot of a database environment weekly
44
 
or monthly, and archive additional log files daily.  Using both the
45
 
snapshot and the log files, a catastrophic crash at any time can be
46
 
recovered to the time of the most recent log archival; a time long after
47
 
the original snapshot.
48
 
<p>To create a standard backup of your database that can be used to recover
49
 
from catastrophic failure, take the following steps:
50
 
<p><ol>
51
 
<p><li>Commit or abort all ongoing transactions.
52
 
<p><li>Stop writing your databases until the backup has completed.  Read-only
53
 
operations are permitted, but no write operations and no filesystem
54
 
operations may be performed (for example, the <a href="../../api_c/env_remove.html">DB_ENV-&gt;remove</a> and
55
 
<a href="../../api_c/db_open.html">DB-&gt;open</a> methods may not be called).
56
 
<p><li>Force an environment checkpoint (see <a href="../../utility/db_checkpoint.html">db_checkpoint</a> for more
57
 
information).
58
 
<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-s</b> to identify all the database data
59
 
files, and copy them to a backup device such as CD-ROM, alternate disk,
60
 
or tape.
61
 
<p>If the database files are stored in a separate directory from the other
62
 
Berkeley DB files, it may be simpler to archive the directory itself instead
63
 
of the individual files (see <a href="../../api_c/env_set_data_dir.html">DB_ENV-&gt;set_data_dir</a> for additional
64
 
information).  <b>Note: if any of the database files did not have
65
 
an open <a href="../../api_c/db_class.html">DB</a> handle during the lifetime of the current log files,
66
 
<a href="../../utility/db_archive.html">db_archive</a> will not list them in its output!</b>  This is another
67
 
reason it may be simpler to use a separate database file directory and
68
 
archive the entire directory instead of archiving only the files listed
69
 
by <a href="../../utility/db_archive.html">db_archive</a>.
70
 
<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-l</b> to identify all the log files,
71
 
and copy the last one (that is, the one with the highest number) to a
72
 
backup device such as CD-ROM, alternate disk, or tape.
73
 
</ol>
74
 
<a name="4"><!--meow--></a>
75
 
<p>To create a <i>hot</i> backup of your database that can be used to
76
 
recover from catastrophic failure, take the following steps:
77
 
<p><ol>
78
 
<p><li>Archive your databases, as described in the previous step #4.
79
 
You do not have to halt ongoing transactions or force a
80
 
checkpoint.  In the case of a hot backup, the utility you use to copy
81
 
the databases must read database pages atomically (as described by
82
 
<a href="../../ref/transapp/reclimit.html">Berkeley DB recoverability</a>).
83
 
<p><li>When performing a hot backup, you must additionally archive all of the
84
 
log files.  Note that the order of these two operations is required,
85
 
and the database files must be archived before the log files.  This
86
 
means that if the database files and log files are in the same
87
 
directory, you cannot simply archive the directory; you must make sure
88
 
that the correct order of archival is maintained.
89
 
<p>To archive your log files, run the <a href="../../utility/db_archive.html">db_archive</a> utility using
90
 
the <b>-l</b> option to identify all the database log files, and
91
 
copy them to your backup media.  If the database log files are stored
92
 
in a separate directory from the other database files, it may be simpler
93
 
to archive the directory itself instead of the individual files (see
94
 
the <a href="../../api_c/env_set_lg_dir.html">DB_ENV-&gt;set_lg_dir</a> method for more information).
95
 
</ol>
96
 
<p>Once these steps are completed, your database can be recovered from
97
 
catastrophic failure (see <a href="recovery.html">Recovery procedures</a> for
98
 
more information).
99
 
<p>To update your snapshot so that recovery from catastrophic failure is
100
 
possible up to a new point in time, repeat step 2 under the hot backup
101
 
instructions -- copying all existing log files to a backup device.  This
102
 
is applicable to both standard and hot backups; that is, you can update
103
 
snapshots made either way.  Each time both the database and log files
104
 
are copied to backup media, you may discard all previous database
105
 
snapshots and saved log files.  Archiving additional log files does not
106
 
allow you to discard either previous database snapshots or log files.
107
 
<p>The time to restore from catastrophic failure is a function of the
108
 
number of log records that have been written since the snapshot was
109
 
originally created.  Perhaps more importantly, the more separate pieces
110
 
of backup media you use, the more likely it is that you will have a
111
 
problem reading from one of them.  For these reasons, it is often best
112
 
to make snapshots on a regular basis.
113
 
<p><b>Obviously, the reliability of your archive media will affect the safety
114
 
of your data.  For archival safety, ensure that you have multiple copies
115
 
of your database backups, verify that your archival media is error-free
116
 
and readable, and that copies of your backups are stored offsite!</b>
117
 
<p>The functionality provided by the <a href="../../utility/db_archive.html">db_archive</a> utility is also
118
 
available directly from the Berkeley DB library.  The following code fragment
119
 
prints out a list of log and database files that need to be archived:
120
 
<p><blockquote><pre>void
121
 
log_archlist(DB_ENV *dbenv)
122
 
{
123
 
        int ret;
124
 
        char **begin, **list;
125
 
<p>
126
 
        /* Get the list of database files. */
127
 
        if ((ret = dbenv-&gt;log_archive(dbenv,
128
 
            &list, DB_ARCH_ABS | DB_ARCH_DATA)) != 0) {
129
 
                dbenv-&gt;err(dbenv, ret, "DB_ENV-&gt;log_archive: DB_ARCH_DATA");
130
 
                exit (1);
131
 
        }
132
 
        if (list != NULL) {
133
 
                for (begin = list; *list != NULL; ++list)
134
 
                        printf("database file: %s\n", *list);
135
 
                free (begin);
136
 
        }
137
 
<p>
138
 
        /* Get the list of log files. */
139
 
        if ((ret = dbenv-&gt;log_archive(dbenv,
140
 
            &list, DB_ARCH_ABS | DB_ARCH_LOG)) != 0) {
141
 
                dbenv-&gt;err(dbenv, ret, "DB_ENV-&gt;log_archive: DB_ARCH_LOG");
142
 
                exit (1);
143
 
        }
144
 
        if (list != NULL) {
145
 
                for (begin = list; *list != NULL; ++list)
146
 
                        printf("log file: %s\n", *list);
147
 
                free (begin);
148
 
        }
149
 
}</pre></blockquote>
150
 
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/logfile.html"><img src="../../images/next.gif" alt="Next"></a>
151
 
</td></tr></table>
152
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
153
 
</body>
154
 
</html>