~ubuntu-branches/debian/experimental/postgresql-11/experimental

<!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>34.1. Database Connection Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="libpq.html" title="Chapter 34. libpq - C Library" /><link rel="next" href="libpq-status.html" title="34.2. Connection Status Functions" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq - C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq - C Library">Up</a></td><th width="60%" align="center">Chapter 34. libpq - C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11beta1 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.1. Database Connection Control Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><a href="libpq-connect.html#LIBPQ-CONNSTRING">34.1.1. Connection Strings</a></dt><dt><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></dt></dl></div>

The following functions deal with making a connection to a

PostgreSQL backend server. An

application program can have several backend connections open at

one time. (One reason to do that is to access more than one

database.) Each connection is represented by a

<code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which

is obtained from the function <code class="function">PQconnectdb</code>,

<code class="function">PQconnectdbParams</code>, or

<code class="function">PQsetdbLogin</code>. Note that these functions will always

return a non-null object pointer, unless perhaps there is too

little memory even to allocate the <code class="structname">PGconn</code> object.

The <code class="function">PQstatus</code> function should be called to check

the return value for a successful connection before queries are sent

via the connection object.

<div class="warning"><h3 class="title">Warning</h3>

If untrusted users have access to a database that has not adopted a

<a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.8.6. Usage Patterns">secure schema usage pattern</a>,

begin each session by removing publicly-writable schemas from

<code class="varname">search_path</code>. One can set parameter key

word <code class="literal">options</code> to

value <code class="literal">-csearch_path=</code>. Alternately, one can

issue <code class="literal">PQexec(<code>conn</code>, "SELECT

pg_catalog.set_config('search_path', '', false)")</code> after

connecting. This consideration is not specific

to libpq; it applies to every interface for

executing arbitrary SQL commands.

</div>

<div class="warning"><h3 class="title">Warning</h3>

On Unix, forking a process with open libpq connections can lead to

unpredictable results because the parent and child processes share

the same sockets and operating system resources. For this reason,

such usage is not recommended, though doing an <code class="function">exec</code> from

the child process to load a new executable is safe.

</div>

On Windows, there is a way to improve performance if a single

database connection is repeatedly started and shutdown. Internally,

libpq calls <code class="function">WSAStartup()</code> and <code class="function">WSACleanup()</code> for connection startup

and shutdown, respectively. <code class="function">WSAStartup()</code> increments an internal

Windows library reference count which is decremented by <code class="function">WSACleanup()</code>.

When the reference count is just one, calling <code class="function">WSACleanup()</code> frees

all resources and all DLLs are unloaded. This is an expensive

operation. To avoid this, an application can manually call

<code class="function">WSAStartup()</code> so resources will not be freed when the last database

connection is closed.

</div>

<div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code><a id="id-1.7.3.8.2.12.1.1.2" class="indexterm"></a></dt><dd>

Makes a new connection to the database server.

PGconn *PQconnectdbParams(const char * const *keywords,

const char * const *values,

int expand_dbname);

</pre>

This function opens a new database connection using the parameters taken

from two <code class="symbol">NULL</code>-terminated arrays. The first,

<code class="literal">keywords</code>, is defined as an array of strings, each one

being a key word. The second, <code class="literal">values</code>, gives the value

for each key word. Unlike <code class="function">PQsetdbLogin</code> below, the parameter

set can be extended without changing the function signature, so use of

this function (or its nonblocking analogs <code class="function">PQconnectStartParams</code>

and <code class="function">PQconnectPoll</code>) is preferred for new application

programming.

The currently recognized parameter key words are listed in

<a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.

When <code class="literal">expand_dbname</code> is non-zero, the

<code>dbname</code> key word value is allowed to be recognized

as a connection string. Only the first occurrence of

<code>dbname</code> is expanded this way, any subsequent

<code>dbname</code> value is processed as plain database name. More

details on the possible connection string formats appear in

<a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.

The passed arrays can be empty to use all default parameters, or can

contain one or more parameter settings. They should be matched in length.

Processing will stop at the first <code class="symbol">NULL</code> element

in the <code class="literal">keywords</code> array.

If any parameter is <code class="symbol">NULL</code> or an empty string, the corresponding

environment variable (see <a class="xref" href="libpq-envars.html" title="34.14. Environment Variables">Section 34.14</a>) is checked.

If the environment variable is not set either, then the indicated

built-in defaults are used.

In general key words are processed from the beginning of these arrays in index

order. The effect of this is that when key words are repeated, the last processed

value is retained. Therefore, through careful placement of the

<code>dbname</code> key word, it is possible to determine what may

be overridden by a <code>conninfo</code> string, and what may not.

</dd><dt id="LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code><a id="id-1.7.3.8.2.12.2.1.2" class="indexterm"></a></dt><dd>

Makes a new connection to the database server.

100

101

102

PGconn *PQconnectdb(const char *conninfo);

103

</pre>

104

105

This function opens a new database connection using the parameters taken

106

from the string <code class="literal">conninfo</code>.

107

108

The passed string can be empty to use all default parameters, or it can

109

contain one or more parameter settings separated by whitespace,

110

or it can contain a <acronym class="acronym">URI</acronym>.

111

See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for details.

112

</dd><dt id="LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code><a id="id-1.7.3.8.2.12.3.1.2" class="indexterm"></a></dt><dd>

113

Makes a new connection to the database server.

114

115

PGconn *PQsetdbLogin(const char *pghost,

116

const char *pgport,

117

const char *pgoptions,

118

const char *pgtty,

119

const char *dbName,

120

const char *login,

121

const char *pwd);

122

</pre>

123

124

This is the predecessor of <code class="function">PQconnectdb</code> with a fixed

125

set of parameters. It has the same functionality except that the

126

missing parameters will always take on default values. Write <code class="symbol">NULL</code> or an

127

empty string for any one of the fixed parameters that is to be defaulted.

128

129

If the <code>dbName</code> contains

130

an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it

131

is taken as a <code>conninfo</code> string in exactly the same way as

132

if it had been passed to <code class="function">PQconnectdb</code>, and the remaining

133

parameters are then applied as specified for <code class="function">PQconnectdbParams</code>.

134

</dd><dt id="LIBPQ-PQSETDB"><code class="function">PQsetdb</code><a id="id-1.7.3.8.2.12.4.1.2" class="indexterm"></a></dt><dd>

135

Makes a new connection to the database server.

136

137

PGconn *PQsetdb(char *pghost,

138

char *pgport,

139

char *pgoptions,

140

char *pgtty,

141

char *dbName);

142

</pre>

143

144

This is a macro that calls <code class="function">PQsetdbLogin</code> with null pointers

145

for the <code>login</code> and <code>pwd</code> parameters. It is provided

146

for backward compatibility with very old programs.

147

</dd><dt id="LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code><a id="id-1.7.3.8.2.12.5.1.2" class="indexterm"></a> <code class="function">PQconnectStart</code><a id="id-1.7.3.8.2.12.5.2.2" class="indexterm"></a> <code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.12.5.3.2" class="indexterm"></a></dt><dd>

148

149

Make a connection to the database server in a nonblocking manner.

150

151

152

PGconn *PQconnectStartParams(const char * const *keywords,

153

const char * const *values,

154

int expand_dbname);

155

156

PGconn *PQconnectStart(const char *conninfo);

157

158

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

159

</pre>

160

161

These three functions are used to open a connection to a database server such

162

that your application's thread of execution is not blocked on remote I/O

163

whilst doing so. The point of this approach is that the waits for I/O to

164

complete can occur in the application's main loop, rather than down inside

165

<code class="function">PQconnectdbParams</code> or <code class="function">PQconnectdb</code>, and so the

166

application can manage this operation in parallel with other activities.

167

168

With <code class="function">PQconnectStartParams</code>, the database connection is made

169

using the parameters taken from the <code class="literal">keywords</code> and

170

<code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>,

171

as described above for <code class="function">PQconnectdbParams</code>.

172

173

With <code class="function">PQconnectStart</code>, the database connection is made

174

using the parameters taken from the string <code class="literal">conninfo</code> as

175

described above for <code class="function">PQconnectdb</code>.

176

177

Neither <code class="function">PQconnectStartParams</code> nor <code class="function">PQconnectStart</code>

178

nor <code class="function">PQconnectPoll</code> will block, so long as a number of

179

restrictions are met:

180

181

The <code class="literal">hostaddr</code> and <code class="literal">host</code> parameters are used appropriately to ensure that

182

name and reverse name queries are not made. See the documentation of

183

these parameters in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for details.

184

</li><li class="listitem">

185

If you call <code class="function">PQtrace</code>, ensure that the stream object

186

into which you trace will not block.

187

</li><li class="listitem">

188

You ensure that the socket is in the appropriate state

189

before calling <code class="function">PQconnectPoll</code>, as described below.

190

</li></ul></div>

191

192

Note: use of <code class="function">PQconnectStartParams</code> is analogous to

193

<code class="function">PQconnectStart</code> shown below.

194

195

To begin a nonblocking connection request, call <code class="literal">conn = PQconnectStart("<code>connection_info_string</code>")</code>.

196

If <code class="varname">conn</code> is null, then libpq has been unable to allocate a new <code class="structname">PGconn</code>

197

structure. Otherwise, a valid <code class="structname">PGconn</code> pointer is returned (though not yet

198

representing a valid connection to the database). On return from

199

<code class="function">PQconnectStart</code>, call <code class="literal">status = PQstatus(conn)</code>. If <code class="varname">status</code> equals

200

<code class="symbol">CONNECTION_BAD</code>, <code class="function">PQconnectStart</code> has failed.

201

202

If <code class="function">PQconnectStart</code> succeeds, the next stage is to poll

203

libpq so that it can proceed with the connection sequence.

204

Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the

205

socket underlying the database connection.

206

Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned

207

<code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to

208

read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or

209

similar system function).

210

Then call <code class="function">PQconnectPoll(conn)</code> again.

211

Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned

212

<code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready

213

to write, then call <code class="function">PQconnectPoll(conn)</code> again.

214

If you have yet to call

215

<code class="function">PQconnectPoll</code>, i.e., just after the call to

216

<code class="function">PQconnectStart</code>, behave as if it last returned

217

<code class="symbol">PGRES_POLLING_WRITING</code>. Continue this loop until

218

<code class="function">PQconnectPoll(conn)</code> returns

219

<code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure

220

has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection

221

has been successfully made.

222

223

At any time during connection, the status of the connection can be

224

checked by calling <code class="function">PQstatus</code>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the

225

connection procedure has failed; if the call returns <code class="function">CONNECTION_OK</code>, then the

226

connection is ready. Both of these states are equally detectable

227

from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur

228

during (and only during) an asynchronous connection procedure. These

229

indicate the current stage of the connection procedure and might be useful

230

to provide feedback to the user for example. These statuses are:

231

232

<div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECTION-STARTED"><code class="symbol">CONNECTION_STARTED</code></dt><dd>

233

Waiting for connection to be made.

234

</dd><dt id="LIBPQ-CONNECTION-MADE"><code class="symbol">CONNECTION_MADE</code></dt><dd>

235

Connection OK; waiting to send.

236

</dd><dt id="LIBPQ-CONNECTION-AWAITING-RESPONSE"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></dt><dd>

237

Waiting for a response from the server.

238

</dd><dt id="LIBPQ-CONNECTION-AUTH-OK"><code class="symbol">CONNECTION_AUTH_OK</code></dt><dd>

239

Received authentication; waiting for backend start-up to finish.

240

</dd><dt id="LIBPQ-CONNECTION-SSL-STARTUP"><code class="symbol">CONNECTION_SSL_STARTUP</code></dt><dd>

241

Negotiating SSL encryption.

242

</dd><dt id="LIBPQ-CONNECTION-SETENV"><code class="symbol">CONNECTION_SETENV</code></dt><dd>

243

Negotiating environment-driven parameter settings.

244

</dd><dt id="LIBPQ-CONNECTION-CHECK-WRITABLE"><code class="symbol">CONNECTION_CHECK_WRITABLE</code></dt><dd>

245

Checking if connection is able to handle write transactions.

246

</dd><dt id="LIBPQ-CONNECTION-CONSUME"><code class="symbol">CONNECTION_CONSUME</code></dt><dd>

247

Consuming any remaining response messages on connection.

248

</dd></dl></div>

249

250

Note that, although these constants will remain (in order to maintain

251

compatibility), an application should never rely upon these occurring in a

252

particular order, or at all, or on the status always being one of these

253

documented values. An application might do something like this:

254

255

switch(PQstatus(conn))

256

{

257

case CONNECTION_STARTED:

258

feedback = "Connecting...";

259

break;

260

261

case CONNECTION_MADE:

262

feedback = "Connected to server...";

263

break;

264

265

266

267

default:

268

feedback = "Connecting...";

269

}

270

</pre>

271

272

The <code class="literal">connect_timeout</code> connection parameter is ignored

273

when using <code class="function">PQconnectPoll</code>; it is the application's

274

responsibility to decide whether an excessive amount of time has elapsed.

275

Otherwise, <code class="function">PQconnectStart</code> followed by a

276

<code class="function">PQconnectPoll</code> loop is equivalent to

277

<code class="function">PQconnectdb</code>.

278

279

Note that if <code class="function">PQconnectStart</code> returns a non-null pointer, you must call

280

<code class="function">PQfinish</code> when you are finished with it, in order to dispose of

281

the structure and any associated memory blocks. This must be done even if

282

the connection attempt fails or is abandoned.

283

</dd><dt id="LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.12.6.1.2" class="indexterm"></a></dt><dd>

284

Returns the default connection options.

285

286

PQconninfoOption *PQconndefaults(void);

287

288

typedef struct

289

{

290

char *keyword; /* The keyword of the option */

291

char *envvar; /* Fallback environment variable name */

292

char *compiled; /* Fallback compiled in default value */

293

char *val; /* Option's current value, or NULL */

294

char *label; /* Label for field in connect dialog */

295

char *dispchar; /* Indicates how to display this field

296

in a connect dialog. Values are:

297

"" Display entered value as is

298

"*" Password field - hide value

299

"D" Debug option - don't show by default */

300

int dispsize; /* Field size in characters for dialog */

301

} PQconninfoOption;

302

</pre>

303

304

Returns a connection options array. This can be used to determine

305

all possible <code class="function">PQconnectdb</code> options and their

306

current default values. The return value points to an array of

307

<code class="structname">PQconninfoOption</code> structures, which ends

308

with an entry having a null <code class="structfield">keyword</code> pointer. The

309

null pointer is returned if memory could not be allocated. Note that

310

the current default values (<code class="structfield">val</code> fields)

311

will depend on environment variables and other context. A

312

missing or invalid service file will be silently ignored. Callers

313

must treat the connection options data as read-only.

314

315

After processing the options array, free it by passing it to

316

<code class="function">PQconninfoFree</code>. If this is not done, a small amount of memory

317

is leaked for each call to <code class="function">PQconndefaults</code>.

318

</dd><dt id="LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.12.7.1.2" class="indexterm"></a></dt><dd>

319

Returns the connection options used by a live connection.

320

321

PQconninfoOption *PQconninfo(PGconn *conn);

322

</pre>

323

324

Returns a connection options array. This can be used to determine

325

all possible <code class="function">PQconnectdb</code> options and the

326

values that were used to connect to the server. The return

327

value points to an array of <code class="structname">PQconninfoOption</code>

328

structures, which ends with an entry having a null <code class="structfield">keyword</code>

329

pointer. All notes above for <code class="function">PQconndefaults</code> also

330

apply to the result of <code class="function">PQconninfo</code>.

331

</dd><dt id="LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.12.8.1.2" class="indexterm"></a></dt><dd>

332

Returns parsed connection options from the provided connection string.

333

334

335

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

336

</pre>

337

338

Parses a connection string and returns the resulting options as an

339

array; or returns <code class="symbol">NULL</code> if there is a problem with the connection

340

string. This function can be used to extract

341

the <code class="function">PQconnectdb</code> options in the provided

342

connection string. The return value points to an array of

343

<code class="structname">PQconninfoOption</code> structures, which ends

344

with an entry having a null <code class="structfield">keyword</code> pointer.

345

346

All legal options will be present in the result array, but the

347

<code class="literal">PQconninfoOption</code> for any option not present

348

in the connection string will have <code class="literal">val</code> set to

349

<code class="literal">NULL</code>; default values are not inserted.

350

351

If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set

352

to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining

353

the problem. (It is also possible for <code class="literal">*errmsg</code> to be

354

set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;

355

this indicates an out-of-memory condition.)

356

357

After processing the options array, free it by passing it to

358

<code class="function">PQconninfoFree</code>. If this is not done, some memory

359

is leaked for each call to <code class="function">PQconninfoParse</code>.

360

Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,

361

be sure to free the error string using <code class="function">PQfreemem</code>.

362

</dd><dt id="LIBPQ-PQFINISH"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.12.9.1.2" class="indexterm"></a></dt><dd>

363

Closes the connection to the server. Also frees

364

memory used by the <code class="structname">PGconn</code> object.

365

366

void PQfinish(PGconn *conn);

367

</pre>

368

369

Note that even if the server connection attempt fails (as

370

indicated by <code class="function">PQstatus</code>), the application should call <code class="function">PQfinish</code>

371

to free the memory used by the <code class="structname">PGconn</code> object.

372

The <code class="structname">PGconn</code> pointer must not be used again after

373

<code class="function">PQfinish</code> has been called.

374

</dd><dt id="LIBPQ-PQRESET"><code class="function">PQreset</code><a id="id-1.7.3.8.2.12.10.1.2" class="indexterm"></a></dt><dd>

375

Resets the communication channel to the server.

376

377

void PQreset(PGconn *conn);

378

</pre>

379

380

This function will close the connection

381

to the server and attempt to reestablish a new

382

connection to the same server, using all the same

383

parameters previously used. This might be useful for

384

error recovery if a working connection is lost.

385

</dd><dt id="LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.12.11.1.2" class="indexterm"></a> <code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.12.11.2.2" class="indexterm"></a></dt><dd>

386

Reset the communication channel to the server, in a nonblocking manner.

387

388

389

int PQresetStart(PGconn *conn);

390

391

PostgresPollingStatusType PQresetPoll(PGconn *conn);

392

</pre>

393

394

These functions will close the connection to the server and attempt to

395

reestablish a new connection to the same server, using all the same

396

parameters previously used. This can be useful for error recovery if a

397

working connection is lost. They differ from <code class="function">PQreset</code> (above) in that they

398

act in a nonblocking manner. These functions suffer from the same

399

restrictions as <code class="function">PQconnectStartParams</code>, <code class="function">PQconnectStart</code>

400

and <code class="function">PQconnectPoll</code>.

401

402

To initiate a connection reset, call

403

<code class="function">PQresetStart</code>. If it returns 0, the reset has

404

failed. If it returns 1, poll the reset using

405

<code class="function">PQresetPoll</code> in exactly the same way as you

406

would create the connection using <code class="function">PQconnectPoll</code>.

407

</dd><dt id="LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.12.12.1.2" class="indexterm"></a></dt><dd>

408

<code class="function">PQpingParams</code> reports the status of the

409

server. It accepts connection parameters identical to those of

410

<code class="function">PQconnectdbParams</code>, described above. It is not

411

necessary to supply correct user name, password, or database name

412

values to obtain the server status; however, if incorrect values

413

are provided, the server will log a failed connection attempt.

414

415

416

PGPing PQpingParams(const char * const *keywords,

417

const char * const *values,

418

int expand_dbname);

419

</pre>

420

421

The function returns one of the following values:

422

423

<div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPINGPARAMS-PQPING-OK"><code class="literal">PQPING_OK</code></dt><dd>

424

The server is running and appears to be accepting connections.

425

</dd><dt id="LIBPQ-PQPINGPARAMS-PQPING-REJECT"><code class="literal">PQPING_REJECT</code></dt><dd>

426

The server is running but is in a state that disallows connections

427

(startup, shutdown, or crash recovery).

428

</dd><dt id="LIBPQ-PQPINGPARAMS-PQPING-NO-RESPONSE"><code class="literal">PQPING_NO_RESPONSE</code></dt><dd>

429

The server could not be contacted. This might indicate that the

430

server is not running, or that there is something wrong with the

431

given connection parameters (for example, wrong port number), or

432

that there is a network connectivity problem (for example, a

433

firewall blocking the connection request).

434

</dd><dt id="LIBPQ-PQPINGPARAMS-PQPING-NO-ATTEMPT"><code class="literal">PQPING_NO_ATTEMPT</code></dt><dd>

435

No attempt was made to contact the server, because the supplied

436

parameters were obviously incorrect or there was some client-side

437

problem (for example, out of memory).

438

</dd></dl></div>

439

440

</dd><dt id="LIBPQ-PQPING"><code class="function">PQping</code><a id="id-1.7.3.8.2.12.13.1.2" class="indexterm"></a></dt><dd>

441

<code class="function">PQping</code> reports the status of the

442

server. It accepts connection parameters identical to those of

443

<code class="function">PQconnectdb</code>, described above. It is not

444

necessary to supply correct user name, password, or database name

445

values to obtain the server status; however, if incorrect values

446

are provided, the server will log a failed connection attempt.

447

448

449

PGPing PQping(const char *conninfo);

450

</pre>

451

452

The return values are the same as for <code class="function">PQpingParams</code>.

453

</dd></dl></div>

454

<div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">34.1.1. Connection Strings</h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a>

455

Several libpq functions parse a user-specified string to obtain

456

connection parameters. There are two accepted formats for these strings:

457

plain <code class="literal">keyword = value</code> strings

458

and URIs. URIs generally follow

459

<a class="ulink" href="https://tools.ietf.org/html/rfc3986" target="_top">RFC

460

3986</a>, except that multi-host connection strings are allowed

461

as further described below.

462

<div class="sect3" id="id-1.7.3.8.3.5"><div class="titlepage"><div><div><h4 class="title">34.1.1.1. Keyword/Value Connection Strings</h4></div></div></div>

463

In the first format, each parameter setting is in the form

464

<code class="literal">keyword = value</code>. Spaces around the equal sign are

465

optional. To write an empty value, or a value containing spaces, surround it

466

with single quotes, e.g., <code class="literal">keyword = 'a value'</code>. Single

467

quotes and backslashes within

468

the value must be escaped with a backslash, i.e., <code class="literal">\'</code> and

469

<code class="literal">\\</code>.

470

471

Example:

472

473

host=localhost port=5432 dbname=mydb connect_timeout=10

474

</pre>

475

476

The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.

477

</div><div class="sect3" id="id-1.7.3.8.3.6"><div class="titlepage"><div><div><h4 class="title">34.1.1.2. Connection URIs</h4></div></div></div>

478

The general form for a connection <acronym class="acronym">URI</acronym> is:

479

480

postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]

481

</pre>

482

483

The <acronym class="acronym">URI</acronym> scheme designator can be either

484

<code class="literal">postgresql://</code> or <code class="literal">postgres://</code>. Each

485

of the <acronym class="acronym">URI</acronym> parts is optional. The following examples

486

illustrate valid <acronym class="acronym">URI</acronym> syntax uses:

487

488

postgresql://

489

postgresql://localhost

490

postgresql://localhost:5433

491

postgresql://localhost/mydb

492

postgresql://user@localhost

493

postgresql://user:secret@localhost

494

postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp

495

postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp

496

</pre>

497

Components of the hierarchical part of the <acronym class="acronym">URI</acronym> can also

498

be given as parameters. For example:

499

500

postgresql:///mydb?host=localhost&port=5433

501

</pre>

502

503

Percent-encoding may be used to include symbols with special meaning in any

504

of the <acronym class="acronym">URI</acronym> parts, e.g. replace <code class="literal">=</code> with

505

<code class="literal">%3D</code>.

506

507

508

Any connection parameters not corresponding to key words listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> are ignored and a warning message about them

509

is sent to <code class="filename">stderr</code>.

510

511

For improved compatibility with JDBC connection <acronym class="acronym">URI</acronym>s,

512

instances of parameter <code class="literal">ssl=true</code> are translated into

513

<code class="literal">sslmode=require</code>.

514

515

The host part may be either host name or an IP address. To specify an

516

IPv6 host address, enclose it in square brackets:

517

518

postgresql://[2001:db8::1234]/database

519

</pre>

520

521

The host component is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>. In particular, a Unix-domain socket

522

connection is chosen if the host part is either empty or starts with a

523

slash, otherwise a TCP/IP connection is initiated. Note, however, that the

524

slash is a reserved character in the hierarchical part of the URI. So, to

525

specify a non-standard Unix-domain socket directory, either omit the host

526

specification in the URI and specify the host as a parameter, or

527

percent-encode the path in the host component of the URI:

528

529

postgresql:///dbname?host=/var/lib/postgresql

530

postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

531

</pre>

532

533

It is possible to specify multiple host components, each with an optional

534

port component, in a single URI. A URI of the form

535

<code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>

536

is equivalent to a connection string of the form

537

<code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>. Each

538

host will be tried in turn until a connection is successfully established.

539

</div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">34.1.1.3. Specifying Multiple Hosts</h4></div></div></div>

540

It is possible to specify multiple hosts to connect to, so that they are

541

tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,

542

<code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept a comma-separated

543

list of values. The same number of elements must be given in each option, such

544

that e.g. the first <code class="literal">hostaddr</code> corresponds to the first host name,

545

the second <code class="literal">hostaddr</code> corresponds to the second host name, and so

546

forth. As an exception, if only one <code class="literal">port</code> is specified, it

547

applies to all the hosts.

548

549

In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs

550

separated by commas, in the <code class="literal">host</code> component of the URI. In either

551

format, a single hostname can also translate to multiple network addresses. A

552

common example of this is a host that has both an IPv4 and an IPv6 address.

553

554

When multiple hosts are specified, or when a single hostname is

555

translated to multiple addresses, all the hosts and addresses will be

556

tried in order, until one succeeds. If none of the hosts can be reached,

557

the connection fails. If a connection is established successfully, but

558

authentication fails, the remaining hosts in the list are not tried.

559

560

If a password file is used, you can have different passwords for

561

different hosts. All the other connection options are the same for every

562

host, it is not possible to e.g. specify a different username for

563

different hosts.

564

</div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">34.1.2. Parameter Key Words</h3></div></div></div>

565

The currently recognized parameter key words are:

566

567

568

Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a>

569

If a host name begins with a slash, it specifies Unix-domain

570

communication rather than TCP/IP communication; the value is the

571

name of the directory in which the socket file is stored. If

572

multiple host names are specified, each will be tried in turn in

573

the order given. The default behavior when <code class="literal">host</code> is

574

not specified is to connect to a Unix-domain

575

socket<a id="id-1.7.3.8.4.2.1.1.2.1.3" class="indexterm"></a> in

576

<code class="filename">/tmp</code> (or whatever socket directory was specified

577

when PostgreSQL was built). On machines without

578

Unix-domain sockets, the default is to connect to <code class="literal">localhost</code>.

579

580

A comma-separated list of host names is also accepted, in which case

581

each host name in the list is tried in order. See

582

<a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.

583

</dd><dt id="LIBPQ-CONNECT-HOSTADDR"><code class="literal">hostaddr</code></dt><dd>

584

Numeric IP address of host to connect to. This should be in the

585

standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>. If

586

your machine supports IPv6, you can also use those addresses.

587

TCP/IP communication is

588

always used when a nonempty string is specified for this parameter.

589

590

Using <code class="literal">hostaddr</code> instead of <code class="literal">host</code> allows the

591

application to avoid a host name look-up, which might be important

592

in applications with time constraints. However, a host name is

593

required for GSSAPI or SSPI authentication

594

methods, as well as for <code class="literal">verify-full</code> SSL

595

certificate verification. The following rules are used:

596

597

If <code class="literal">host</code> is specified without <code class="literal">hostaddr</code>,

598

a host name lookup occurs.

599

</li><li class="listitem">

600

If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,

601

the value for <code class="literal">hostaddr</code> gives the server network address.

602

The connection attempt will fail if the authentication

603

method requires a host name.

604

</li><li class="listitem">

605

If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,

606

the value for <code class="literal">hostaddr</code> gives the server network address.

607

The value for <code class="literal">host</code> is ignored unless the

608

authentication method requires it, in which case it will be

609

used as the host name.

610

</li></ul></div>

611

Note that authentication is likely to fail if <code class="literal">host</code>

612

is not the name of the server at network address <code class="literal">hostaddr</code>.

613

Also, note that <code class="literal">host</code> rather than <code class="literal">hostaddr</code>

614

is used to identify the connection in a password file (see

615

<a class="xref" href="libpq-pgpass.html" title="34.15. The Password File">Section 34.15</a>).

616

617

A comma-separated list of <code class="literal">hostaddr</code> values is also

618

accepted, in which case each host in the list is tried in order. See

619

<a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.

620

621

Without either a host name or host address,

622

libpq will connect using a

623

local Unix-domain socket; or on machines without Unix-domain

624

sockets, it will attempt to connect to <code class="literal">localhost</code>.

625

</dd><dt id="LIBPQ-CONNECT-PORT"><code class="literal">port</code></dt><dd>

626

Port number to connect to at the server host, or socket file

627

name extension for Unix-domain

628

connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>

629

If multiple hosts were given in the <code class="literal">host</code> or

630

<code class="literal">hostaddr</code> parameters, this parameter may specify a list

631

of ports of equal length, or it may specify a single port number to

632

be used for all hosts.

633

</dd><dt id="LIBPQ-CONNECT-DBNAME"><code class="literal">dbname</code></dt><dd>

634

The database name. Defaults to be the same as the user name.

635

In certain contexts, the value is checked for extended

636

formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for more details on

637

those.

638

</dd><dt id="LIBPQ-CONNECT-USER"><code class="literal">user</code></dt><dd>

639

PostgreSQL user name to connect as.

640

Defaults to be the same as the operating system name of the user

641

running the application.

642

</dd><dt id="LIBPQ-CONNECT-PASSWORD"><code class="literal">password</code></dt><dd>

643

Password to be used if the server demands password authentication.

644

</dd><dt id="LIBPQ-CONNECT-PASSFILE"><code class="literal">passfile</code></dt><dd>

645

Specifies the name of the file used to store passwords

646

(see <a class="xref" href="libpq-pgpass.html" title="34.15. The Password File">Section 34.15</a>).

647

Defaults to <code class="filename">~/.pgpass</code>, or

648

<code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.

649

(No error is reported if this file does not exist.)

650

</dd><dt id="LIBPQ-CONNECT-CONNECT-TIMEOUT"><code class="literal">connect_timeout</code></dt><dd>

651

Maximum wait for connection, in seconds (write as a decimal integer

652

string). Zero or not specified means wait indefinitely. It is not

653

recommended to use a timeout of less than 2 seconds.

654

This timeout applies separately to each connection attempt.

655

For example, if you specify two hosts and <code class="literal">connect_timeout</code>

656

is 5, each host will time out if no connection is made within 5

657

seconds, so the total time spent waiting for a connection might be

658

up to 10 seconds.

659

</dd><dt id="LIBPQ-CONNECT-CLIENT-ENCODING"><code class="literal">client_encoding</code></dt><dd>

660

This sets the <code class="varname">client_encoding</code>

661

configuration parameter for this connection. In addition to

662

the values accepted by the corresponding server option, you

663

can use <code class="literal">auto</code> to determine the right

664

encoding from the current locale in the client

665

(<code class="envar">LC_CTYPE</code> environment variable on Unix

666

systems).

667

</dd><dt id="LIBPQ-CONNECT-OPTIONS"><code class="literal">options</code></dt><dd>

668

Specifies command-line options to send to the server at connection

669

start. For example, setting this to <code class="literal">-c geqo=off</code> sets the

670

session's value of the <code class="varname">geqo</code> parameter to

671

<code class="literal">off</code>. Spaces within this string are considered to

672

separate command-line arguments, unless escaped with a backslash

673

(<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal

674

backslash. For a detailed discussion of the available

675

options, consult <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>.

676

</dd><dt id="LIBPQ-CONNECT-APPLICATION-NAME"><code class="literal">application_name</code></dt><dd>

677

Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>

678

configuration parameter.

679

</dd><dt id="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME"><code class="literal">fallback_application_name</code></dt><dd>

680

Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.

681

This value will be used if no value has been given for

682

<code class="literal">application_name</code> via a connection parameter or the

683

<code class="envar">PGAPPNAME</code> environment variable. Specifying

684

a fallback name is useful in generic utility programs that

685

wish to set a default application name but allow it to be

686

overridden by the user.

687

</dd><dt id="LIBPQ-KEEPALIVES"><code class="literal">keepalives</code></dt><dd>

688

Controls whether client-side TCP keepalives are used. The default

689

value is 1, meaning on, but you can change this to 0, meaning off,

690

if keepalives are not wanted. This parameter is ignored for

691

connections made via a Unix-domain socket.

692

</dd><dt id="LIBPQ-KEEPALIVES-IDLE"><code class="literal">keepalives_idle</code></dt><dd>

693

Controls the number of seconds of inactivity after which TCP should

694

send a keepalive message to the server. A value of zero uses the

695

system default. This parameter is ignored for connections made via a

696

Unix-domain socket, or if keepalives are disabled.

697

It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or

698

an equivalent socket option is available, and on Windows; on other

699

systems, it has no effect.

700

</dd><dt id="LIBPQ-KEEPALIVES-INTERVAL"><code class="literal">keepalives_interval</code></dt><dd>

701

Controls the number of seconds after which a TCP keepalive message

702

that is not acknowledged by the server should be retransmitted. A

703

value of zero uses the system default. This parameter is ignored for

704

connections made via a Unix-domain socket, or if keepalives are disabled.

705

It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or

706

an equivalent socket option is available, and on Windows; on other

707

systems, it has no effect.

708

</dd><dt id="LIBPQ-KEEPALIVES-COUNT"><code class="literal">keepalives_count</code></dt><dd>

709

Controls the number of TCP keepalives that can be lost before the

710

client's connection to the server is considered dead. A value of

711

zero uses the system default. This parameter is ignored for

712

connections made via a Unix-domain socket, or if keepalives are disabled.

713

It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or

714

an equivalent socket option is available; on other systems, it has no

715

effect.

716

</dd><dt id="LIBPQ-CONNECT-TTY"><code class="literal">tty</code></dt><dd>

717

Ignored (formerly, this specified where to send server debug output).

718

</dd><dt id="LIBPQ-SCRAM-CHANNEL-BINDING"><code class="literal">scram_channel_binding</code></dt><dd>

719

Specifies the channel binding type to use with SCRAM

720

authentication. While <acronym class="acronym">SCRAM</acronym> alone prevents

721

the replay of transmitted hashed passwords, channel binding also

722

prevents man-in-the-middle attacks.

723

724

The list of channel binding types supported by the server are

725

listed in <a class="xref" href="sasl-authentication.html" title="53.3. SASL Authentication">Section 53.3</a>. An empty value

726

specifies that the client will not use channel binding. If this

727

parameter is not specified, <code class="literal">tls-unique</code> is used,

728

if supported by both server and client.

729

Channel binding is only supported on SSL connections. If the

730

connection is not using SSL, then this setting is ignored.

731

732

This parameter is mainly intended for protocol testing. In normal

733

use, there should not be a need to choose a channel binding type other

734

than the default one.

735

</dd><dt id="LIBPQ-CONNECT-REPLICATION"><code class="literal">replication</code></dt><dd>

736

This option determines whether the connection should use the

737

replication protocol instead of the normal protocol. This is what

738

PostgreSQL replication connections as well as tools such as

739

pg_basebackup use internally, but it can

740

also be used by third-party applications. For a description of the

741

replication protocol, consult <a class="xref" href="protocol-replication.html" title="53.4. Streaming Replication Protocol">Section 53.4</a>.

742

743

The following values, which are case-insensitive, are supported:

744

745

<code class="literal">true</code>, <code class="literal">on</code>,

746

747

</dt><dd>

748

The connection goes into physical replication mode.

749

</dd><dt><code class="literal">database</code></dt><dd>

750

The connection goes into logical replication mode, connecting to

751

the database specified in the <code class="literal">dbname</code> parameter.

752

</dd><dt>

753

<code class="literal">false</code>, <code class="literal">off</code>,

754

755

</dt><dd>

756

The connection is a regular one, which is the default behavior.

757

</dd></dl></div>

758

759

In physical or logical replication mode, only the simple query protocol

760

can be used.

761

</dd><dt id="LIBPQ-CONNECT-SSLMODE"><code class="literal">sslmode</code></dt><dd>

762

This option determines whether or with what priority a secure

763

<acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the

764

server. There are six modes:

765

766

<div class="variablelist"><dl class="variablelist"><dt><code class="literal">disable</code></dt><dd>

767

only try a non-<acronym class="acronym">SSL</acronym> connection

768

</dd><dt><code class="literal">allow</code></dt><dd>

769

first try a non-<acronym class="acronym">SSL</acronym> connection; if that

770

fails, try an <acronym class="acronym">SSL</acronym> connection

771

</dd><dt><code class="literal">prefer</code> (default)</dt><dd>

772

first try an <acronym class="acronym">SSL</acronym> connection; if that fails,

773

try a non-<acronym class="acronym">SSL</acronym> connection

774

</dd><dt><code class="literal">require</code></dt><dd>

775

only try an <acronym class="acronym">SSL</acronym> connection. If a root CA

776

file is present, verify the certificate in the same way as

777

if <code class="literal">verify-ca</code> was specified

778

</dd><dt><code class="literal">verify-ca</code></dt><dd>

779

only try an <acronym class="acronym">SSL</acronym> connection, and verify that

780

the server certificate is issued by a trusted

781

certificate authority (<acronym class="acronym">CA</acronym>)

782

</dd><dt><code class="literal">verify-full</code></dt><dd>

783

only try an <acronym class="acronym">SSL</acronym> connection, verify that the

784

server certificate is issued by a

785

trusted <acronym class="acronym">CA</acronym> and that the requested server host name

786

matches that in the certificate

787

</dd></dl></div>

788

789

See <a class="xref" href="libpq-ssl.html" title="34.18. SSL Support">Section 34.18</a> for a detailed description of how

790

these options work.

791

792

<code class="literal">sslmode</code> is ignored for Unix domain socket

793

communication.

794

If PostgreSQL is compiled without SSL support,

795

using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or

796

<code class="literal">verify-full</code> will cause an error, while

797

options <code class="literal">allow</code> and <code class="literal">prefer</code> will be

798

accepted but libpq will not actually attempt

799

an <acronym class="acronym">SSL</acronym>

800

connection.<a id="id-1.7.3.8.4.2.1.20.2.2.10" class="indexterm"></a>

801

</dd><dt id="LIBPQ-CONNECT-REQUIRESSL"><code class="literal">requiressl</code></dt><dd>

802

This option is deprecated in favor of the <code class="literal">sslmode</code>

803

setting.

804

805

If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server

806

is required (this is equivalent to <code class="literal">sslmode</code>

807

<code class="literal">require</code>). libpq will then refuse

808

to connect if the server does not accept an

809

<acronym class="acronym">SSL</acronym> connection. If set to 0 (default),

810

libpq will negotiate the connection type with

811

the server (equivalent to <code class="literal">sslmode</code>

812

<code class="literal">prefer</code>). This option is only available if

813

PostgreSQL is compiled with SSL support.

814

</dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><code class="literal">sslcompression</code></dt><dd>

815

If set to 1, data sent over SSL connections will be compressed. If

816

set to 0, compression will be disabled. The default is 0. This

817

parameter is ignored if a connection without SSL is made.

818

819

SSL compression is nowadays considered insecure and its use is no

820

longer recommended. OpenSSL 1.1.0 disables

821

compression by default, and many operating system distributions

822

disable it in prior versions as well, so setting this parameter to on

823

will not have any effect if the server does not accept compression.

824

On the other hand, OpenSSL before 1.0.0

825

does not support disabling compression, so this parameter is ignored

826

with those versions, and whether compression is used depends on the

827

server.

828

829

If security is not a primary concern, compression can improve

830

throughput if the network is the bottleneck. Disabling compression

831

can improve response time and throughput if CPU performance is the

832

limiting factor.

833

</dd><dt id="LIBPQ-CONNECT-SSLCERT"><code class="literal">sslcert</code></dt><dd>

834

This parameter specifies the file name of the client SSL

835

certificate, replacing the default

836

<code class="filename">~/.postgresql/postgresql.crt</code>.

837

This parameter is ignored if an SSL connection is not made.

838

</dd><dt id="LIBPQ-CONNECT-SSLKEY"><code class="literal">sslkey</code></dt><dd>

839

This parameter specifies the location for the secret key used for

840

the client certificate. It can either specify a file name that will

841

be used instead of the default

842

<code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key

843

obtained from an external “engine” (engines are

844

OpenSSL loadable modules). An external engine

845

specification should consist of a colon-separated engine name and

846

an engine-specific key identifier. This parameter is ignored if an

847

SSL connection is not made.

848

</dd><dt id="LIBPQ-CONNECT-SSLROOTCERT"><code class="literal">sslrootcert</code></dt><dd>

849

This parameter specifies the name of a file containing SSL

850

certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).

851

If the file exists, the server's certificate will be verified

852

to be signed by one of these authorities. The default is

853

<code class="filename">~/.postgresql/root.crt</code>.

854

</dd><dt id="LIBPQ-CONNECT-SSLCRL"><code class="literal">sslcrl</code></dt><dd>

855

This parameter specifies the file name of the SSL certificate

856

revocation list (CRL). Certificates listed in this file, if it

857

exists, will be rejected while attempting to authenticate the

858

server's certificate. The default is

859

<code class="filename">~/.postgresql/root.crl</code>.

860

</dd><dt id="LIBPQ-CONNECT-REQUIREPEER"><code class="literal">requirepeer</code></dt><dd>

861

This parameter specifies the operating-system user name of the

862

server, for example <code class="literal">requirepeer=postgres</code>.

863

When making a Unix-domain socket connection, if this

864

parameter is set, the client checks at the beginning of the

865

connection that the server process is running under the specified

866

user name; if it is not, the connection is aborted with an error.

867

This parameter can be used to provide server authentication similar

868

to that available with SSL certificates on TCP/IP connections.

869

(Note that if the Unix-domain socket is in

870

<code class="filename">/tmp</code> or another publicly writable location,

871

any user could start a server listening there. Use this parameter

872

to ensure that you are connected to a server run by a trusted user.)

873

This option is only supported on platforms for which the

874

<code class="literal">peer</code> authentication method is implemented; see

875

<a class="xref" href="auth-peer.html" title="20.9. Peer Authentication">Section 20.9</a>.

876

</dd><dt id="LIBPQ-CONNECT-KRBSRVNAME"><code class="literal">krbsrvname</code></dt><dd>

877

Kerberos service name to use when authenticating with GSSAPI.

878

This must match the service name specified in the server

879

configuration for Kerberos authentication to succeed. (See also

880

<a class="xref" href="gssapi-auth.html" title="20.6. GSSAPI Authentication">Section 20.6</a>.)

881

</dd><dt id="LIBPQ-CONNECT-GSSLIB"><code class="literal">gsslib</code></dt><dd>

882

GSS library to use for GSSAPI authentication. Only used on Windows.

883

Set to <code class="literal">gssapi</code> to force libpq to use the GSSAPI

884

library for authentication instead of the default SSPI.

885

</dd><dt id="LIBPQ-CONNECT-SERVICE"><code class="literal">service</code></dt><dd>

886

Service name to use for additional parameters. It specifies a service

887

name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.

888

This allows applications to specify only a service name so connection parameters

889

can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="34.16. The Connection Service File">Section 34.16</a>.

890

</dd><dt id="LIBPQ-CONNECT-TARGET-SESSION-ATTRS"><code class="literal">target_session_attrs</code></dt><dd>

891

If this parameter is set to <code class="literal">read-write</code>, only a

892

connection in which read-write transactions are accepted by default

893

is considered acceptable. The query

894

<code class="literal">SHOW transaction_read_only</code> will be sent upon any

895

successful connection; if it returns <code class="literal">on</code>, the connection

896

will be closed. If multiple hosts were specified in the connection

897

string, any remaining servers will be tried just as if the connection

898

attempt had failed. The default value of this parameter,

899

<code class="literal">any</code>, regards all connections as acceptable.

900

</dd></dl></div>

901

</div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. libpq - C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 34.2. Connection Status Functions</td></tr></table></div></body></html>

b'\\ No newline at end of file'

Older »