~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>nextwalfile</> <replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional>

</synopsis>

When used within <varname>restore_command</>, the <literal>%f</> and

<literal>%p</> macros should be specified for <replaceable>nextwalfile</>

and <replaceable>xlogfilepath</> respectively, to provide the actual file

and path required for the restore.

</para>

<para>

If <replaceable>restartwalfile</> is specified, normally by using the

<literal>%r</literal> macro, then all WAL files logically preceding this

file will be removed from <replaceable>archivelocation</>. This minimizes

the number of files that need to be retained, while preserving

crash-restart capability. Use of this parameter is appropriate if the

<replaceable>archivelocation</> is a transient staging area for this

particular standby server, but <emphasis>not</> when the

<replaceable>archivelocation</> is intended as a long-term WAL archive area.

</para>

<para>

<application>pg_standby</application> assumes that

<replaceable>archivelocation</> is a directory readable by the

server-owning user. If <replaceable>restartwalfile</> (or <literal>-k</>)

is specified,

the <replaceable>archivelocation</> directory must be writable too.

</para>

<para>

There are two ways to fail over to a <quote>warm standby</> database server

when the master server fails:

<term>Smart Failover</term>

<para>

In smart failover, the server is brought up after applying all WAL

files available in the archive. This results in zero data loss, even if

the standby server has fallen behind, but if there is a lot of

unapplied WAL it can be a long time before the standby server becomes

ready. To trigger a smart failover, create a trigger file containing

100

the word <literal>smart</>, or just create it and leave it empty.

101

</para>

102

</listitem>

103

</varlistentry>

104

105

<term>Fast Failover</term>

106

107

<para>

108

In fast failover, the server is brought up immediately. Any WAL files

109

in the archive that have not yet been applied will be ignored, and

110

all transactions in those files are lost. To trigger a fast failover,

111

create a trigger file and write the word <literal>fast</> into it.

112

<application>pg_standby</> can also be configured to execute a fast

113

failover automatically if no new WAL file appears within a defined

114

interval.

115

</para>

116

</listitem>

117

</varlistentry>

118

</variablelist>

119

</para>

120

121

</sect2>

122

123

<sect2>

124

<title><application>pg_standby</> Options</title>

125

126

<para>

127

<application>pg_standby</application> accepts the following command-line arguments:

128

129

130

131

132

133

134

<para>

135

Use <literal>cp</> or <literal>copy</> command to restore WAL files

136

from archive. This is the only supported behavior so this option is useless.

137

</para>

138

</listitem>

139

</varlistentry>

140

141

142

143

144

<para>

145

Print lots of debug logging output on <filename>stderr</>.

146

</para>

147

</listitem>

148

</varlistentry>

149

150

151

152

153

<para>

154

Remove files from <replaceable>archivelocation</replaceable> so that

155

no more than this many WAL files before the current one are kept in the

156

archive. Zero (the default) means not to remove any files from

157

<replaceable>archivelocation</replaceable>.

158

This parameter will be silently ignored if

159

<replaceable>restartwalfile</replaceable> is specified, since that

160

specification method is more accurate in determining the correct

161

archive cut-off point.

162

Use of this parameter is <emphasis>deprecated</> as of

163

<productname>PostgreSQL</> 8.3; it is safer and more efficient to

164

specify a <replaceable>restartwalfile</replaceable> parameter. A too

165

small setting could result in removal of files that are still needed

166

for a restart of the standby server, while a too large setting wastes

167

archive space.

168

</para>

169

</listitem>

170

</varlistentry>

171

172

173

<term><option>-r</option> <replaceable>maxretries</></term>

174

175

<para>

176

Set the maximum number of times to retry the copy command if

177

it fails (default 3). After each failure, we wait for

178

<replaceable>sleeptime</> * <replaceable>num_retries</>

179

so that the wait time increases progressively. So by default,

180

we will wait 5 secs, 10 secs, then 15 secs before reporting

181

the failure back to the standby server. This will be

182

interpreted as end of recovery and the standby will come

183

up fully as a result.

184

</para>

185

</listitem>

186

</varlistentry>

187

188

189

<term><option>-s</option> <replaceable>sleeptime</></term>

190

191

<para>

192

Set the number of seconds (up to 60, default 5) to sleep between

193

tests to see if the WAL file to be restored is available in

194

the archive yet. The default setting is not necessarily

195

recommended; consult <xref linkend="warm-standby"> for discussion.

196

</para>

197

</listitem>

198

</varlistentry>

199

200

201

<term><option>-t</option> <replaceable>triggerfile</></term>

202

203

<para>

204

Specify a trigger file whose presence should cause failover.

205

It is recommended that you use a structured file name to

206

avoid confusion as to which server is being triggered

207

when multiple servers exist on the same system; for example

208

<filename>/tmp/pgsql.trigger.5432</>.

209

</para>

210

</listitem>

211

</varlistentry>

212

213

214

<term><option>-w</option> <replaceable>maxwaittime</></term>

215

216

<para>

217

Set the maximum number of seconds to wait for the next WAL file,

218

after which a fast failover will be performed.

219

A setting of zero (the default) means wait forever.

220

The default setting is not necessarily recommended;

221

consult <xref linkend="warm-standby"> for discussion.

222

</para>

223

</listitem>

224

</varlistentry>

225

226

</variablelist>

227

</para>

228

229

</sect2>

230

231

<sect2>

232

<title>Examples</title>

233

234

<para>On Linux or Unix systems, you might use:

235

236

237

archive_command = 'cp %p .../archive/%f'

238

239

restore_command = 'pg_standby -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'

240

241

recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'

242

</programlisting>

243

where the archive directory is physically located on the standby server,

244

so that the <varname>archive_command</> is accessing it across NFS,

245

but the files are local to the standby (enabling use of <literal>ln</>).

246

This will:

247

248

249

<para>

250

produce debugging output in <filename>standby.log</>

251

</para>

252

</listitem>

253

254

<para>

255

sleep for 2 seconds between checks for next WAL file availability

256

</para>

257

</listitem>

258

259

<para>

260

stop waiting only when a trigger file called

261

<filename>/tmp/pgsql.trigger.5442</> appears,

262

and perform failover according to its content

263

</para>

264

</listitem>

265

266

<para>

267

remove the trigger file when recovery ends

268

</para>

269

</listitem>

270

271

<para>

272

remove no-longer-needed files from the archive directory

273

</para>

274

</listitem>

275

</itemizedlist>

276

</para>

277

278

<para>On Windows, you might use:

279

280

281

archive_command = 'copy %p ...\\archive\\%f'

282

283

restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'

284

285

recovery_end_command = 'del C:\pgsql.trigger.5442'

286

</programlisting>

287

Note that backslashes need to be doubled in the

288

<varname>archive_command</>, but <emphasis>not</emphasis> in the

289

<varname>restore_command</> or <varname>recovery_end_command</>.

290

This will:

291

292

293

<para>

294

use the <literal>copy</> command to restore WAL files from archive

295

</para>

296

</listitem>

297

298

<para>

299

produce debugging output in <filename>standby.log</>

300

</para>

301

</listitem>

302

303

<para>

304

sleep for 5 seconds between checks for next WAL file availability

305

</para>

306

</listitem>

307

308

<para>

309

stop waiting only when a trigger file called

310

<filename>C:\pgsql.trigger.5442</> appears,

311

and perform failover according to its content

312

</para>

313

</listitem>

314

315

<para>

316

remove the trigger file when recovery ends

317

</para>

318

</listitem>

319

320

<para>

321

remove no-longer-needed files from the archive directory

322

</para>

323

</listitem>

324

</itemizedlist>

325

</para>

326

327

<para>

328

The <literal>copy</> command on Windows sets the final file size

329

before the file is completely copied, which would ordinarily confuse

330

<application>pg_standby</application>. Therefore

331

<application>pg_standby</application> waits <literal>sleeptime</>

332

seconds once it sees the proper file size. GNUWin32's <literal>cp</>

333

sets the file size only after the file copy is complete.

334

</para>

335

336

<para>

337

Since the Windows example uses <literal>copy</> at both ends, either

338

or both servers might be accessing the archive directory across the

339

network.

340

</para>

341

342

</sect2>

343

344

<sect2>

345

<title>Supported Server Versions</title>

346

347

<para>

348

<application>pg_standby</application> is designed to work with

349

<productname>PostgreSQL</> 8.2 and later.

350

</para>

351

<para>

352

<productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,

353

which is designed to let <application>pg_standby</application> know the

354

last file it needs to keep. With <productname>PostgreSQL</> 8.2, the

355

<literal>-k</literal> option must be used if archive cleanup is

356

required. This option remains available in 8.3, but its use is deprecated.

357

</para>

358

<para>

359

<productname>PostgreSQL</> 8.4 provides the

360

<varname>recovery_end_command</> option. Without this option

361

a leftover trigger file can be hazardous.

362

</para>

363

</sect2>

364

365

<sect2>

366

<title>Author</title>

367

368

<para>

369

Simon Riggs <email>simon@2ndquadrant.com</email>

370

</para>

371

</sect2>

372

373

</sect1>

Older »