-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathbackup_lang_java.html
165 lines (165 loc) · 13.1 KB
/
backup_lang_java.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>WiredTiger: Backups in Java</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 2.8.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li><a href="community.html"><span>Community</span></a></li>
<li><a href="license.html"><span>License</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('backup_lang_java.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Backups in Java </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger cursors provide access to data from a variety of sources. One of these sources is the list of files required to perform a backup of the database. The list may be the files required by all of the objects in the database, or a subset of the objects in the database.</p>
<p>WiredTiger backups are "on-line" or "hot" backups, and applications may continue to read and write the databases while a snapshot is taken.</p>
<h1><a class="anchor" id="backup_process_lang_java"></a>
Backup from an application</h1>
<ol type="1">
<li>Open a cursor on the <code>"backup:"</code> data source, which begins the process of a backup.</li>
<li>Copy each file returned by the Cursor.next method to the backup location, for example, a different directory. Do not reuse backup locations unless all files have first been removed from them, in other words, remove any previous backup information before using a backup location.</li>
<li>Close the cursor; the cursor must not be closed until all of the files have been copied.</li>
</ol>
<p>The directory into which the files are copied may subsequently be specified as an directory to the <code>wiredtiger.open</code> function and accessed as a WiredTiger database home.</p>
<p>Copying the database files for a backup does not require any special alignment or block size (specifically, Linux or Windows filesystems that do not support read/write isolation can be safely read for backups).</p>
<p>The cursor must not be closed until all of the files have been copied, however, there is no requirement the files be copied in any order or in any relationship to the Cursor.next calls, only that all files have been copied before the cursor is closed. For example, applications might aggregate the file names from the cursor and then list the file names as arguments to a file archiver such as the system tar utility.</p>
<p>During the period the backup cursor is open, database checkpoints can be created, but no checkpoints can be deleted. This may result in significant file growth.</p>
<p>The following is a programmatic example of creating a backup:</p>
<div class="fragment"><div class="line"> Cursor cursor;</div>
<div class="line"> String filename;</div>
<div class="line"> <span class="keywordtype">int</span> ret = 0;</div>
<div class="line"> String databasedir = <span class="stringliteral">"/path/database"</span>;</div>
<div class="line"> String backdir = <span class="stringliteral">"/path/database.backup"</span>;</div>
<div class="line"> <span class="keyword">final</span> String sep = File.separator;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">try</span> {</div>
<div class="line"> <span class="comment">/* Create the backup directory. */</span></div>
<div class="line"> <span class="keywordflow">if</span> (!(<span class="keyword">new</span> File(backdir)).mkdir()) {</div>
<div class="line"> System.err.println(progname + <span class="stringliteral">": cannot create backup dir: "</span> +</div>
<div class="line"> backdir);</div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Open the backup data source. */</span></div>
<div class="line"> cursor = session.<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(<span class="stringliteral">"backup:"</span>, null, null);</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Copy the list of files. */</span></div>
<div class="line"> <span class="keywordflow">while</span> ((ret = cursor.next()) == 0 &&</div>
<div class="line"> (filename = cursor.getKeyString()) != null) {</div>
<div class="line"> String src = databasedir + sep + filename;</div>
<div class="line"> String dest = backdir + sep + filename;</div>
<div class="line"> java.nio.file.Files.copy(</div>
<div class="line"> <span class="keyword">new</span> java.io.File(src).toPath(), </div>
<div class="line"> <span class="keyword">new</span> java.io.File(dest).toPath(),</div>
<div class="line"> java.nio.file.StandardCopyOption.REPLACE_EXISTING,</div>
<div class="line"> java.nio.file.StandardCopyOption.COPY_ATTRIBUTES);</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">if</span> (ret == wiredtiger.WT_NOTFOUND)</div>
<div class="line"> ret = 0;</div>
<div class="line"> <span class="keywordflow">if</span> (ret != 0)</div>
<div class="line"> System.err.println(progname +</div>
<div class="line"> <span class="stringliteral">": cursor next(backup:) failed: "</span> +</div>
<div class="line"> wiredtiger.wiredtiger_strerror(ret));</div>
<div class="line"></div>
<div class="line"> ret = cursor.close();</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">catch</span> (Exception ex) {</div>
<div class="line"> System.err.println(progname +</div>
<div class="line"> <span class="stringliteral">": backup failed: "</span> + ex.toString());</div>
<div class="line"> }</div>
</div><!-- fragment --><p> In cases where the backup is desired for a checkpoint other than the most recent, applications can discard all checkpoints subsequent to the checkpoint they want using the Session.checkpoint method. For example:</p>
<div class="fragment"><div class="line"> ret = session.<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#a6550c9079198955c5071583941c85bbf">checkpoint</a>(<span class="stringliteral">"drop=(from=June01),name=June01"</span>);</div>
</div><!-- fragment --> <h1><a class="anchor" id="backup_util_lang_java"></a>
Backup from the command line</h1>
<p>The <a class="el" href="command_line.html#util_backup">wt backup</a> command may also be used to create backups:</p>
<div class="fragment"><div class="line">rm -rf /path/database.backup &&</div>
<div class="line"> mkdir /path/database.backup &&</div>
<div class="line"> wt -h /path/database.source backup /path/database.backup</div>
</div><!-- fragment --><h1><a class="anchor" id="backup_incremental_lang_java"></a>
Incremental backup</h1>
<p>Once a backup has been done, it can be rolled forward incrementally by adding log files to the backup copy. Adding log files to the copy decreases potential data loss from switching to the copy, but increases the recovery time necessary to switch to the copy. To reset the recovery time necessary to switch to the copy, perform a full backup of the database. For example, an application might do a full backup of the database once a week during a quiet period, and then incrementally copy new log files into the backup directory for the rest of the week. Incremental backups may also save time when the tables are very large.</p>
<p>Bulk-loads are not commit-level durable, that is, the creation and bulk-load of an object will not appear in the database log files. For this reason, applications doing incremental backups after a full backup should repeat the full backup step after doing a bulk-load to make the bulk-load durable. In addition, incremental backups after a bulk-load can cause recovery to report errors because there are log records that apply to data files which don't appear in the backup.</p>
<p>By default, WiredTiger automatically removes log files no longer required for recovery. Applications wanting to use log files for incremental backup must first disable automatic log file removal using the <code>log=</code>(archive=false) configuration to <code>wiredtiger.open</code>.</p>
<p>The following is the procedure for incrementally backing up a database and removing log files from the original database home:</p>
<ol type="1">
<li>Perform a full backup of the database (as described above).</li>
<li>Perform a full database checkpoint.</li>
<li>Open a cursor on the <code>"backup:"</code> data source, with the <code>"target=(\"log:\")"</code> target specified, which begins the process of an incremental backup.</li>
<li>Copy each log file returned by the Cursor.next method to the backup directory. It is not an error to copy a log file which has been copied before, but care should be taken to ensure each log file is completely copied as the most recent log file may change in size while being copied.</li>
<li>If all log files have been successfully copied, archive the log files by calling the Session.truncate method with the URI <code>log:</code> and specifying the backup cursor as the start cursor to that method.</li>
<li>Close the backup cursor.</li>
</ol>
<p>Steps 2-6 can be repeated any number of times before step 1 is repeated. These steps can be repeated as long as the backup database directory has not been opened, recovery run and become live. Once the database becomes live, you must repeat all steps 1-6 to another, different backup database directory.</p>
<h1><a class="anchor" id="backup_o_direct_lang_java"></a>
Backup and O_DIRECT</h1>
<p>Many Linux systems do not support mixing <code>O_DIRECT</code> and memory mapping or normal I/O to the same file. If <code>O_DIRECT</code> is configured for data or log files on Linux systems (using the wiredtiger_open <code>direct_io</code> configuration), any program used to copy files during backup should also specify <code>O_DIRECT</code> when configuring its file access. Likewise, when <code>O_DIRECT</code> is not configured by the database application, programs copying files should not configure <code>O_DIRECT</code>. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming_lang_java.html">Writing WiredTiger applications in Java</a></li>
<li class="footer">Copyright (c) 2008-2016 MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>