1<!--$Id: checkpoint.so,v 10.22 2003/12/09 18:57:46 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: Checkpoints</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<a name="2"><!--meow--></a>
12<table width="100%"><tr valign=top>
13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></b></td>
14<td align=right><a href="/transapp/deadlock.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/archival.html"><img src="/images/next.gif" alt="Next"></a>
15</td></tr></table>
16<p align=center><b>Checkpoints</b></p>
17<p>The second component of the infrastructure is performing checkpoints of
18the log files.  Performing checkpoints is necessary for two reasons.</p>
19<p>First, you may be able to remove Berkeley DB log files from your database
20environment after a checkpoint.  Change records are written into the log
21files when databases are modified, but the actual changes to the
22database are not necessarily written to disk.  When a checkpoint is
23performed, changes to the database are written into the backing database
24file.  Once the database pages are written, log files can be archived
25and removed from the database environment because they will never be
26needed for anything other than catastrophic failure.  (Log files which
27are involved in active transactions may not be removed, and there must
28always be at least one log file in the database environment.)</p>
29<p>The second reason to perform checkpoints is because checkpoint frequency
30is inversely proportional to the amount of time it takes to run database
31recovery after a system or application failure.  This is because
32recovery after failure has to redo or undo changes only since the last
33checkpoint, as changes before the checkpoint have all been flushed to
34the databases.</p>
35<p>Berkeley DB provides a separate utility, <a href="/utility/db_checkpoint.html">db_checkpoint</a>, which can be
36used to perform checkpoints.  Alternatively, applications can write
37their own checkpoint utility using the underlying <a href="/api_c/txn_checkpoint.html">DB_ENV-&gt;txn_checkpoint</a>
38function.  The following code fragment checkpoints the database
39environment every 60 seconds:</p>
40<blockquote><pre>int
41main(int argc, char *argv)
42{
43	extern int optind;
44	DB *db_cats, *db_color, *db_fruit;
45	DB_ENV *dbenv;
46	pthread_t ptid;
47	int ch;
48<p>
49	while ((ch = getopt(argc, argv, "")) != EOF)
50		switch (ch) {
51		case '?':
52		default:
53			usage();
54		}
55	argc -= optind;
56	argv += optind;
57<p>
58	env_dir_create();
59	env_open(&dbenv);
60<p>
61<b>	/* Start a checkpoint thread. */
62	if ((errno = pthread_create(
63	    &ptid, NULL, checkpoint_thread, (void *)dbenv)) != 0) {
64		fprintf(stderr,
65		    "txnapp: failed spawning checkpoint thread: %s\n",
66		    strerror(errno));
67		exit (1);
68	}</b>
69<p>
70	/* Open database: Key is fruit class; Data is specific type. */
71	db_open(dbenv, &db_fruit, "fruit", 0);
72<p>
73	/* Open database: Key is a color; Data is an integer. */
74	db_open(dbenv, &db_color, "color", 0);
75<p>
76	/*
77	 * Open database:
78	 *	Key is a name; Data is: company name, cat breeds.
79	 */
80	db_open(dbenv, &db_cats, "cats", 1);
81<p>
82	add_fruit(dbenv, db_fruit, "apple", "yellow delicious");
83<p>
84	add_color(dbenv, db_color, "blue", 0);
85	add_color(dbenv, db_color, "blue", 3);
86<p>
87	add_cat(dbenv, db_cats,
88		"Amy Adams",
89		"Oracle",
90		"abyssinian",
91		"bengal",
92		"chartreaux",
93		NULL);
94<p>
95	return (0);
96}
97<p>
98<b>void *
99checkpoint_thread(void *arg)
100{
101	DB_ENV *dbenv;
102	int ret;
103<p>
104	dbenv = arg;
105	dbenv-&gt;errx(dbenv, "Checkpoint thread: %lu", (u_long)pthread_self());
106<p>
107	/* Checkpoint once a minute. */
108	for (;; sleep(60))
109		if ((ret = dbenv-&gt;txn_checkpoint(dbenv, 0, 0, 0)) != 0) {
110			dbenv-&gt;err(dbenv, ret, "checkpoint thread");
111			exit (1);
112		}
113<p>
114	/* NOTREACHED */
115}</b></pre></blockquote>
116<p>Because checkpoints can be quite expensive, choosing how often to
117perform a checkpoint is a common tuning parameter for Berkeley DB
118applications.</p>
119<table width="100%"><tr><td><br></td><td align=right><a href="/transapp/deadlock.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/archival.html"><img src="/images/next.gif" alt="Next"></a>
120</td></tr></table>
121<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
122</body>
123</html>
124