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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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/html; charset=UTF-8" />
<title>Replication PRAGMAs</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Getting Started with the Oracle Berkeley DB SQL APIs" />
<link rel="up" href="sqlrep.html" title="Chapter 4. Using Replication with the SQL API" />
<link rel="prev" href="sqlrep.html" title="Chapter 4. Using Replication with the SQL API" />
<link rel="next" href="repstatistics.html" title="Displaying Replication Statistics" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Replication PRAGMAs</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="sqlrep.html">Prev</a> </td>
<th width="60%" align="center">Chapter 4. Using Replication with the SQL API</th>
<td width="20%" align="right"> <a accesskey="n" href="repstatistics.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="reppragma"></a>Replication PRAGMAs</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication">PRAGMA replication</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_ack_policy">PRAGMA replication_ack_policy</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_ack_timeout">PRAGMA replication_ack_timeout</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_get_master">PRAGMA replication_get_master</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_initial_master">PRAGMA replication_initial_master</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_local_site">PRAGMA replication_local_site</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_num_sites">PRAGMA replication_num_sites</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_perm_failed">PRAGMA replication_perm_failed</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_priority">PRAGMA replication_priority</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_remote_site">PRAGMA replication_remote_site</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_remove_site">PRAGMA replication_remove_site</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_site_status">PRAGMA replication_site_status</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_verbose_output">PRAGMA replication_verbose_output</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="reppragma.html#pragma_replication_verbose_file">PRAGMA replication_verbose_file</a>
</span>
</dt>
</dl>
</div>
<p>
To control replication when using the Berkeley DB SQL
interface, you use the following PRAGMAs. For an example of
how to use these, see
<a class="xref" href="rep_usageexamples.html" title="Replication Usage Examples">Replication Usage Examples</a>.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication"></a>PRAGMA replication</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication=ON|OFF </pre>
<p>
Enables the local environment to participate in
replication. You only need to specify this PRAGMA
once to turn on replication; all future uses of the
database will automatically enable replication.
</p>
<p>
Before invoking this PRAGMA for a brand new
database (one that has never been opened), you
must invoke the
<code class="literal">replication_local_site</code> PRAGMA
and then either the
<code class="literal">replication_initial_master</code> or
the <code class="literal">replication_remote_site</code>
PRAGMA. These actions define the way this site fits
into the replication group.
</p>
<p>
If you are enabling replication for an existing
database, it must become the initial master for a
new replication group. You must invoke the
<code class="literal">replication_local_site</code> PRAGMA
followed by the
<code class="literal">replication_initial_master</code>
PRAGMA before enabling replication.
</p>
<p>
If you use this PRAGMA to turn off replication,
then replication is completely disabled for the
environment. In order to enable replication again,
you follow the procedure used to enable replication
on an existing database; that is, invoke the
<code class="literal">replication_local_site</code> PRAGMA
followed by the
<code class="literal">replication_initial_master</code>
PRAGMA, followed by
<code class="literal">PRAGMA replication=ON</code>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_ack_policy"></a>PRAGMA replication_ack_policy</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_ack_policy=all|all_available|none|one|quorum </pre>
<p>
Sets the replication group's acknowledgement policy. If
no policy is specified, then this PRAGMA returns the
current acknowledgement policy. This PRAGMA may be
called at any time during the life of the application.
</p>
<p>
Acknowledgement policies are used to describe how
permanent messages will be handled. A message is
considered to be permanent if the master site has
received enough responses (acknowledgements) from its
replicas. Once the master is satisfied that a message is
permanent, it considers the transaction that generated
the message to be complete. Therefore, the
acknowledgement policy you set affects your
application's write throughput, as well as the
durability strength of your transactions.
</p>
<p>
Message acknowledgements must be returned within a set
timeout period. See
<a class="xref" href="reppragma.html#pragma_replication_ack_timeout" title="PRAGMA replication_ack_timeout">PRAGMA replication_ack_timeout</a>
for information on how to manage this timeout.
Also,
<a class="xref" href="reppragma.html#pragma_replication_perm_failed" title="PRAGMA replication_perm_failed">PRAGMA replication_perm_failed</a>
provides useful diagnostic information that you can use
to fine-tune your acknowledgement policy.
</p>
<p>
See
<a class="xref" href="sqlrep.html#permmessage" title="Permanent Message Handling">Permanent Message Handling</a>
for more information on message acknowledgements.
</p>
<p>
Possible permanent acknowledgement policies are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<code class="literal">all</code>
</p>
<p>
All sites belonging to the replication group must
acknowledge the message before the generating
transaction is considered to be complete. This
provides the strongest possible durability
guarantee, but also the slowest possible write
throughput.
</p>
<p>
Note that if any site is shutdown or otherwise
cannot be reached due to networking errors,
this acknowledgement policy will prevent your
application from considering any transactions
durable.
</p>
</li>
<li>
<p>
<code class="literal">all_available</code>
</p>
<p>
All currently connected sites must acknowledge the message.
</p>
</li>
<li>
<p>
<code class="literal">none</code>
</p>
<p>
The master will not wait for any message
acknowledgements before completing the
transaction. This results in the fastest
possible write throughput, but also the weakest
durability guarantee.
</p>
</li>
<li>
<p>
<code class="literal">one</code>
</p>
<p>
At least one site must acknowledge the message
before the transaction is considered to be
complete.
</p>
</li>
<li>
<p>
<code class="literal">quorum</code>
</p>
<p>
The master waits until it has received
acknowledgements from the minimum number of
electable sites sufficient to ensure the record
change is durable in the event of an election.
This is the default acknowledgement policy.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_ack_timeout"></a>PRAGMA replication_ack_timeout</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_ack_timeout=<timeout in microseconds> </pre>
<p>
Sets the replication site's acknowledgement timeout
value. If the acknowledgement policy cannot be met
within this timeout period, then the encompassing
transaction is not considered to be complete. This
PRAGMA may be called at any time during the life of the
application. The default is 1 second (1000000).
</p>
<p>
If no timeout is provided, then this PRAGMA returns
the replication site's current message acknowledgement
timeout value.
</p>
<p>
For information on specifying acknowledgement policies,
see
<a class="xref" href="reppragma.html#pragma_replication_ack_policy" title="PRAGMA replication_ack_policy">PRAGMA replication_ack_policy</a>.
Also,
<a class="xref" href="reppragma.html#pragma_replication_perm_failed" title="PRAGMA replication_perm_failed">PRAGMA replication_perm_failed</a>
provides useful diagnostic information that you can use
to fine-tune your acknowledgement timeouts.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_get_master"></a>PRAGMA replication_get_master</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_get_master </pre>
<p>
Returns a host/port pair representing the current
master. If replication has not yet started, or if the
master is currently not known (such as during an
election), <code class="literal">NULL</code> is returned.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_initial_master"></a>PRAGMA replication_initial_master</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_initial_master=ON|OFF </pre>
<p>
Causes the local environment to start up as a
master site. This PRAGMA must be used once and only
once in the replicated lifetime of a BDB SQL
environment.
</p>
<p>
This PRAGMA is usually invoked for the first site in a
new replication group before the
<code class="literal">replication</code> PRAGMA is invoked
and before BDB SQL initially creates the underlying
BDB environment for a SQL database. Starting
replication on the initial master site establishes
the new replication group so that other sites can
join it.
</p>
<p>
However, you must call this PRAGMA
when enabling replication for a database that
already exists. Doing so causes the existing
database to become the replication master for a new
replication group.
</p>
<p>
Note that subsequent election activity can cause
other sites in the replication group to become
master. Do not assume that the initial master site
will remain master indefinitely, or that it will
rejoin the replication group as master after a
shutdown.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_local_site"></a>PRAGMA replication_local_site</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_local_site="hostname:port" </pre>
<p>
Sets the local site information for replication.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_num_sites"></a>PRAGMA replication_num_sites</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_num_sites</pre>
<p>
Returns the number of sites in the replication group,
or <code class="literal">0</code> if replication has not yet
started. Any input provided to this PRAGMA is ignored.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_perm_failed"></a>PRAGMA replication_perm_failed</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_perm_failed </pre>
<p>
Returns the number of times that a permanent message
has failed the replication group's acknowledgement
policy since the last time this PRAGMA was called. Zero
is returned if replication has not yet started.
</p>
<p>
Every time a permanent message has failed
acknowledgement, a transaction was not considered
durable and the master waited the full acknowldgement
timeout period before returning from its commit. If
you are seeing a high number of permanent message
acknowledgement failures, then that might represent a
significant reduction in your application's
write-throughput.
</p>
<p>
To fix the problem, begin by examining your replicas to
make sure they are operating correctly, as well as your
network to make sure its performance is what you expect.
If all looks well, then you should either reduce your
acknowledgement policy (and accept a lessened
durability guarantee) or increase your acknowledgement
timeout period (which might reduce your write-throughput).
</p>
<p>
To manage your acknowledgement policies, see
<a class="xref" href="reppragma.html#pragma_replication_ack_policy" title="PRAGMA replication_ack_policy">PRAGMA replication_ack_policy</a>.
To manage your acknowledgement timeout policy, see
<a class="xref" href="reppragma.html#pragma_replication_ack_timeout" title="PRAGMA replication_ack_timeout">PRAGMA replication_ack_timeout</a>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_priority"></a>PRAGMA replication_priority</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_priority=<non-0 positive integer> </pre>
<p>
Sets the site's election priority. When holding
elections, if more than one site has the most
up-to-date copy of the data then the site with the
highest priority will become master. This PRAGMA may
be called at any time during the life of the
application. The default is 100.
</p>
<p>
If no priority is provided, then this PRAGMA returns
the site's current priority.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_remote_site"></a>PRAGMA replication_remote_site</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_remote_site="hostname:port" </pre>
<p>
Sets information about a remote helper site in the
replication group.
</p>
<p>
This PRAGMA is needed when a site first joins an
existing replication group to specify a site that
is already in the replication group. It must be
invoked before the <code class="literal">replication</code>
PRAGMA is invoked. This PRAGMA is not needed on
the initial master site or when restarting a site
that is already a member of the replication group.
However, supplying this PRAGMA in those situations
does no harm.
</p>
<p>
Note that the information provided to this PRAGMA
can be superseded by normal replication activity
over the course of the environment's lifetime.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_remove_site"></a>PRAGMA replication_remove_site</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_remove_site="hostname:port" </pre>
<p>
Removes the specified site from the replication group.
Use this PRAGMA if you truly want to remove the
site permanently from the group. It is not
desirable to call this PRAGMA if a site has been
temporarily shut down or disconnected from the rest
of the replication group.
</p>
<p>
Removing a site from the replication group means
that the site is no longer counted towards the
total number of sites belonging to the group. This
is important when the replication group requires
knowledge about whether a quorum has been reached
(such as when, for example, elections are held).
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_site_status"></a>PRAGMA replication_site_status</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_site_status </pre>
<p>
Returns whether the local site is the
<code class="literal">MASTER</code>, <code class="literal">CLIENT</code>,
or <code class="literal">UNKNOWN</code>.
</p>
<p>
<code class="literal">UNKNOWN</code> is returned if replication
has not yet started. CLIENT is another term for
replica.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_verbose_output"></a>PRAGMA replication_verbose_output</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_verbose_output=ON|OFF </pre>
<p>
If set to TRUE, additional logging information
specifically related to replication is created.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="pragma_replication_verbose_file"></a>PRAGMA replication_verbose_file</h3>
</div>
</div>
</div>
<pre class="programlisting">PRAGMA replication_verbose_file="filename" </pre>
<p>
Indicates that verbose replication output should be
sent to the specified file, as opposed to STDOUT.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="sqlrep.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="sqlrep.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="repstatistics.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 4. Using Replication with the SQL API </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Displaying Replication Statistics</td>
</tr>
</table>
</div>
</body>
</html>
|
