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
|
<!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: Log cursors</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);
</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 3.1.0</span>
</div>
<div id="projectbrief"><!-- 3.1.0 --></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.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></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('cursor_log.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Log cursors </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger cursors provide access to data from a variety of sources, and one of these sources is the records in the transaction log files. Log files may not be present in every WiredTiger database, only databases that have been configured for logging using the <code>log</code> configuration for <a class="el" href="group__wt.html#gacbe8d118f978f5bfc8ccb4c77c9e8813" title="Open a connection to a database. ">wiredtiger_open</a>. In databases with log files, a log cursor provides access to the log records. Although log cursors are read-only, applications may store records in the log using <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#ac85541ca42d7596857d9f50e03c78eb5" title="Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for...">WT_SESSION::log_printf</a>. While the log cursor is open automatic log file archiving, even if enabled, will not reclaim any log files.</p>
<p>Each physical WiredTiger log record represents one or more operations in the database. When a log record represents more than a single operation in the database, all of the operations in a log record will be part of the same transaction, however, there is no corresponding guarantee that all operations in a transaction must appear in the same log record.</p>
<p>The following examples are taken from the complete example program <a class="el" href="ex_log_8c-example.html">ex_log.c</a>.</p>
<p>To open a log cursor on the database:</p>
<div class="fragment"><div class="line"> error_check(session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"log:"</span>, NULL, NULL, &cursor));</div></div><!-- fragment --><p> A log cursor's key is a unique log record identifier, plus a uint32_t operation counter within that log record. When a log record maps one-to-one to a transaction (in other words, the returned log record has the only database operation the transaction made), the operation counter returned for the key will be zero.</p>
<p>The unique log record identifier maps to a WT_LSN data structure, which has two fields: WT_LSN::id, the log file identifier, and WT_LSN::offset, the offset of the log record in the log file.</p>
<p>Here is an example of getting the log cursor's key:</p>
<div class="fragment"><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af19f6f9d9c7fc248ab38879032620b2f">get_key</a>(</div><div class="line"> cursor, &log_file, &log_offset, &opcount));</div></div><!-- fragment --><p> The log cursor's value is comprised of six fields:</p>
<ul>
<li>a <code>uint64_t</code> transaction ID (set for commit records only, otherwise 0),</li>
<li>a <code>uint32_t</code> record type</li>
<li>a <code>uint32_t</code> operation type (set for commit records only, otherwise 0)</li>
<li>a <code>uint32_t</code> file id (if applicable, otherwise 0)</li>
<li>the operation key (commit records only, otherwise empty)</li>
<li>the operation value</li>
</ul>
<p>The transaction ID may not be unique across recovery, that is, closing and reopening the database may result in transaction IDs smaller than previously seen transaction IDs.</p>
<p>The record and operation types are taken from <a class="el" href="group__wt.html#log_types">log_types</a>; typically, the only record or operation type applications are concerned with is <a class="el" href="group__wt.html#ga8cf04a003979e7852209079d4093d783" title="message ">WT_LOGREC_MESSAGE</a>, which is a log record generated by the application.</p>
<p>The file ID may not be unique across recovery, that is, closing and reopening the database may result in file IDs changing. Additionally, there is currently no way to map file IDs to file names or higher-level objects.</p>
<p>Here is an example of getting the log cursor's value:</p>
<div class="fragment"><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01">get_value</a>(cursor, &txnid,</div><div class="line"> &rectype, &optype, &fileid, &logrec_key, &logrec_value));</div></div><!-- fragment --><p> For clarity, imagine a set of three log records:</p>
<ul>
<li>the first with a single operation,</li>
<li>the second with five operations,</li>
<li>the third with a single operation.</li>
</ul>
<p>The log cursor's <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b" title="Return the next record. ">WT_CURSOR::next</a> call will return a total of seven records. The first time the log cursor will return a key with a unique log ID, a unique transaction ID, and an operation counter of 0. The next five returns from the log cursor will have a common log ID, a common transaction ID, and operation counters starting at 1 and ending at 5. The final return from the log cursor will again have a unique log ID, a unique transaction ID, and an operation counter of 0.</p>
<p>Here's a more complete example of walking the log and displaying the results:</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span></div><div class="line">print_record(uint32_t log_file, uint32_t log_offset, uint32_t opcount,</div><div class="line"> uint32_t rectype, uint32_t optype, uint64_t txnid, uint32_t fileid,</div><div class="line"> <a class="code" href="group__wt.html#struct_w_t___i_t_e_m">WT_ITEM</a> *key, <a class="code" href="group__wt.html#struct_w_t___i_t_e_m">WT_ITEM</a> *value)</div><div class="line">{</div><div class="line"> printf(</div><div class="line"> <span class="stringliteral">"LSN [%"</span> PRIu32 <span class="stringliteral">"][%"</span> PRIu32 <span class="stringliteral">"].%"</span> PRIu32</div><div class="line"> <span class="stringliteral">": record type %"</span> PRIu32 <span class="stringliteral">" optype %"</span> PRIu32</div><div class="line"> <span class="stringliteral">" txnid %"</span> PRIu64 <span class="stringliteral">" fileid %"</span> PRIu32,</div><div class="line"> log_file, log_offset, opcount,</div><div class="line"> rectype, optype, txnid, fileid);</div><div class="line"> printf(<span class="stringliteral">" key size %zu value size %zu\n"</span>, key-><a class="code" href="group__wt.html#abd8b1299dfb5c54dc049fa42a4680b55">size</a>, value-><a class="code" href="group__wt.html#abd8b1299dfb5c54dc049fa42a4680b55">size</a>);</div><div class="line"> <span class="keywordflow">if</span> (rectype == <a class="code" href="group__wt.html#ga8cf04a003979e7852209079d4093d783">WT_LOGREC_MESSAGE</a>)</div><div class="line"> printf(<span class="stringliteral">"Application Record: %s\n"</span>, (<span class="keywordtype">char</span> *)value-><a class="code" href="group__wt.html#a57f5e62aa968275d7e398cfa70e49450">data</a>);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">/*</span></div><div class="line"><span class="comment"> * simple_walk_log --</span></div><div class="line"><span class="comment"> * A simple walk of the log.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span></div><div class="line">simple_walk_log(<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html">WT_SESSION</a> *session, <span class="keywordtype">int</span> count_min)</div><div class="line">{</div><div class="line"> <a class="code" href="struct_w_t___c_u_r_s_o_r.html">WT_CURSOR</a> *cursor;</div><div class="line"> <a class="code" href="group__wt.html#struct_w_t___i_t_e_m">WT_ITEM</a> logrec_key, logrec_value;</div><div class="line"> uint64_t txnid;</div><div class="line"> uint32_t fileid, log_file, log_offset, opcount, optype, rectype;</div><div class="line"> <span class="keywordtype">int</span> count, ret;</div><div class="line"></div><div class="line"> error_check(session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"log:"</span>, NULL, NULL, &cursor));</div><div class="line"> count = 0;</div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b">next</a>(cursor)) == 0) {</div><div class="line"> count++;</div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af19f6f9d9c7fc248ab38879032620b2f">get_key</a>(</div><div class="line"> cursor, &log_file, &log_offset, &opcount));</div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01">get_value</a>(cursor, &txnid,</div><div class="line"> &rectype, &optype, &fileid, &logrec_key, &logrec_value));</div><div class="line"> print_record(log_file, log_offset, opcount,</div><div class="line"> rectype, optype, txnid, fileid, &logrec_key, &logrec_value);</div><div class="line"> }</div><div class="line"> scan_end_check(ret == <a class="code" href="group__wt.html#ga3c9e1b494d95cf34404ab7a974af6bf8">WT_NOTFOUND</a>);</div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#aeea071f192cab12245a50fbe71c3460b">close</a>(cursor));</div><div class="line"></div><div class="line"> <span class="keywordflow">if</span> (count < count_min) {</div><div class="line"> fprintf(stderr,</div><div class="line"> <span class="stringliteral">"Expected minimum %d records, found %d\n"</span>,</div><div class="line"> count_min, count);</div><div class="line"> exit (1);</div><div class="line"> }</div><div class="line">}</div></div><!-- fragment --><p> The log cursor's key can be used to search for specific records in the log (assuming the record still exists and has not been archived), by setting the key and calling <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a7e25b2ced2cf3ec68bd5429bf921c79f" title="Return the record matching the key. ">WT_CURSOR::search</a>. However, it is not possible to search for a specific operation within a log record, and the key's operation counter is ignored when the key is set. The result of a search for a log record with more than one operation is always the first operation in the log record.</p>
<p>Here is an example of setting the log cursor's key:</p>
<div class="fragment"><div class="line"> cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#ad1088d719df40babc1f57d086691ebdc">set_key</a>(cursor, save_file, save_offset, 0);</div></div><!-- fragment --><p> Log cursors are read-only, however applications can insert their own log records using <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#ac85541ca42d7596857d9f50e03c78eb5" title="Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for...">WT_SESSION::log_printf</a>. Here is an example of adding an application record into the database log:</p>
<div class="fragment"><div class="line"> error_check(</div><div class="line"> session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#ac85541ca42d7596857d9f50e03c78eb5">log_printf</a>(session, <span class="stringliteral">"Wrote %d records"</span>, record_count));</div></div><!-- fragment --></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.html">Writing WiredTiger applications</a></li>
<li class="footer">Copyright (c) 2008-2018 MongoDB, Inc. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</li>
</ul>
</div>
</body>
</html>
|
