You are on page 1of 1332

PostgreSQL 8.0.0 Documentation

The PostgreSQL Global Development Group

PostgreSQL 8.0.0 Documentation by The PostgreSQL Global Development Group Copyright © 1996-2005 by The PostgreSQL Global Development Group

Legal Notice

PostgreSQL is Copyright © 1996-2005 by the PostgreSQL Global Development Group and is distributed under the terms of the license of the University of California below.

Postgres95 is Copyright © 1994-5 by the Regents of the University of California.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PRO- VIDED HEREUNDER IS ON AN “AS-IS” BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Table of Contents

Preface

i

1.

What is PostgreSQL?

i

2.

A Brief History of PostgreSQL

ii

2.1. The Berkeley POSTGRES Project

ii

2.2. Postgres95

ii

2.3. PostgreSQL

iii

3.

Conventions

iii

4.

Further Information

iv

5.

Bug Reporting Guidelines

iv

5.1. Identifying Bugs

iv

5.2. What to report

v

5.3. Where to report bugs

vii

I. Tutorial

 

1

1. Getting Started

1

 

1.1. Installation

1

1.2. Architectural Fundamentals

1

1.3. Creating a Database

2

1.4. Accessing a Database

3

2. The SQL Language

6

 

2.1. Introduction

6

2.2. Concepts

6

2.3. Creating a New Table

6

2.4. Populating a Table With Rows

7

2.5. Querying a Table

8

2.6. Joins Between Tables

10

2.7. Aggregate Functions

12

 

2.8. Updates

13

 

2.9. Deletions

14

3. Advanced Features

15

 

3.1. Introduction

15

 

3.2. Views

15

 

3.3. Foreign Keys

15

3.4. Transactions

16

3.5. Inheritance

18

3.6. Conclusion

19

II. The SQL Language

 

21

4.

SQL Syntax

23

4.1.

Lexical Structure

23

 

4.1.1. Identifiers and Key Words

23

4.1.2. Constants

24

4.1.2.1. String Constants

24

4.1.2.2. Dollar-Quoted String Constants

25

4.1.2.3. Bit-String Constants

26

4.1.2.4. Numeric Constants

26

4.1.2.5. Constants of Other Types

27

4.1.3. Operators

27

4.1.4. Special Characters

28

4.1.5. Comments

28

4.1.6.

Lexical Precedence

29

4.2.

Value Expressions

30

4.2.1. Column References

31

4.2.2. Positional Parameters

31

4.2.3. Subscripts

31

4.2.4. Field Selection

32

4.2.5. Operator Invocations

32

4.2.6. Function Calls

32

4.2.7. Aggregate Expressions

33

4.2.8. Type Casts

33

4.2.9. Scalar Subqueries

34

4.2.10.

Array Constructors

34

4.2.11.

Row Constructors

36

4.2.12.

Expression Evaluation Rules

37

5. Data Definition

38

5.1. Table Basics

38

5.2. Default Values

39

5.3. Constraints

40

 

5.3.1. Check Constraints

40

5.3.2. Not-Null Constraints

42

5.3.3. Unique Constraints

42

5.3.4. Primary Keys

43

5.3.5. Foreign Keys

44

5.4. System Columns

46

5.5. Inheritance

 

48

5.6. Modifying Tables

50

 

5.6.1. Adding a Column

50

5.6.2. Removing a Column

51

5.6.3. Adding a Constraint

51

5.6.4. Removing a Constraint

51

5.6.5. Changing a Column’s Default Value

52

5.6.6. Changing a Column’s Data Type

52

5.6.7. Renaming a Column

52

5.6.8. Renaming a Table

53

5.7. Privileges

 

53

5.8. Schemas

54

 

5.8.1. Creating a Schema

54

5.8.2. The Public Schema

55

5.8.3. The Schema Search Path

55

5.8.4. Schemas and Privileges

56

5.8.5. The System Catalog Schema

57

5.8.6. Usage Patterns

57

5.8.7. Portability

57

5.9. Other Database Objects

58

5.10. Dependency Tracking

58

6. Data Manipulation

 

60

6.1.

Inserting Data

60

6.2.

Updating Data

61

6.3.

Deleting Data

61

7. Queries

63

7.1.

Overview

63

7.2.

Table Expressions

63

7.2.1.

The FROM Clause

64

 

7.2.1.1. Joined Tables

64

7.2.1.2. Table and Column Aliases

67

7.2.1.3. Subqueries

68

7.2.1.4. Table Functions

68

 

7.2.2. The WHERE Clause

69

7.2.3. The GROUP BY and HAVING Clauses

70

7.3.

Select Lists

 

72

 

7.3.1. Select-List Items

72

7.3.2. Column Labels

73

7.3.3. DISTINCT

73

7.4. Combining Queries

74

7.5. Sorting Rows

 

74

7.6. LIMIT and OFFSET

75

8. Data Types

 

77

8.1.

Numeric Types

78

 

8.1.1. Integer Types

79

8.1.2. Arbitrary Precision Numbers

79

8.1.3. Floating-Point Types

80

8.1.4. Serial Types

81

8.2. Monetary Types

82

8.3. Character Types

82

8.4. Binary Data Types

84

8.5. Date/Time Types

86

 

8.5.1. Date/Time Input

87

 

8.5.1.1. Dates

87

8.5.1.2. Times

88

8.5.1.3. Time Stamps

88

8.5.1.4. Intervals

89

8.5.1.5. Special Values

90

 

8.5.2. Date/Time Output

90

8.5.3. Time Zones

91

8.5.4. Internals

92

8.6. Boolean Type

 

92

8.7. Geometric Types

93

 

8.7.1. Points

93

8.7.2. Line Segments

94

8.7.3. Boxes

94

8.7.4. Paths

94

8.7.5. Polygons

94

8.7.6. Circles

95

8.8.

Network Address Types

95

 

8.8.1. inet

95

8.8.2. cidr

96

8.8.3. inet vs. cidr

96

8.8.4. macaddr

97

8.9.

Bit String Types

97

8.10. Arrays

 

98

 

8.10.1.

Declaration of Array Types

98

8.10.2.

Array Value Input

98

8.10.3.

Accessing Arrays

100

8.10.4.

Modifying Arrays

101

8.10.5.

Searching in Arrays

104

8.10.6.

Array Input and Output Syntax

104

8.11. Composite Types

105

8.11.1. Declaration of Composite Types

106

8.11.2. Composite Value Input

107

8.11.3. Accessing Composite Types

107

8.11.4. Modifying Composite Types

108

8.11.5. Composite Type Input and Output Syntax

108

8.12. Object Identifier Types

109

8.13. Pseudo-Types

111

9. Functions and Operators

113

9.1. Logical Operators

113

9.2. Comparison Operators

113

9.3. Mathematical Functions and Operators

115

9.4. String Functions and Operators

118

9.5. Binary String Functions and Operators

126

9.6. Bit String Functions and Operators

127

9.7. Pattern Matching

128

9.7.1. LIKE

128

9.7.2. SIMILAR TO Regular Expressions

129

9.7.3. POSIX Regular Expressions

130

 

9.7.3.1. Regular Expression Details

131

9.7.3.2. Bracket Expressions

133

9.7.3.3. Regular Expression Escapes

134

9.7.3.4. Regular Expression Metasyntax

136

9.7.3.5. Regular Expression Matching Rules

138

9.7.3.6. Limits and Compatibility

139

9.7.3.7. Basic Regular Expressions

139

9.8. Data Type Formatting Functions

140

9.9. Date/Time Functions and Operators

145

9.9.1. EXTRACT, date_part

148

9.9.2. date_trunc

151

9.9.3. AT TIME ZONE

151

9.9.4. Current Date/Time

152

9.10. Geometric Functions and Operators

153

9.11. Network Address Functions and Operators

157

9.12. Sequence Manipulation Functions

158

9.13. Conditional Expressions

160

9.13.1. CASE

160

9.13.2. COALESCE

161

9.13.3. NULLIF

162

9.14. Array Functions and Operators

162

9.15. Aggregate Functions

163

9.16. Subquery Expressions

165

9.16.1. EXISTS

165

9.16.2. IN

166

9.16.3. NOT IN

166

9.16.4. ANY/SOME

167

9.16.5. ALL

168

9.16.6. Row-wise Comparison

168

9.17. Row and Array Comparisons

169

9.17.1.

IN

169

9.17.2.

NOT IN

169

 

9.17.3. ANY/SOME (array)

170

9.17.4. ALL (array)

170

9.17.5.

Row-wise Comparison

170

 

9.18. Set Returning Functions

170

9.19. System Information Functions

171

9.20. System Administration Functions

176

10. Type Conversion

 

179

 

10.1.

Overview

179

10.2.

Operators

180

10.3.

Functions

183

10.4.

Value Storage

185

10.5.

UNION, CASE, and ARRAY Constructs

186

11. Indexes

188

 

11.1.

Introduction

188

11.2.

Index Types

189

11.3.

Multicolumn Indexes

190

11.4.

Unique Indexes

190

11.5.

Indexes on Expressions

191

11.6.

Operator Classes

192

11.7.

Partial Indexes

193

11.8.

Examining Index Usage

195

12. Concurrency Control

 

197

 

12.1. Introduction

197

12.2. Transaction Isolation

197

 

12.2.1. Read Committed Isolation Level

198

12.2.2. Serializable Isolation Level

199

12.2.2.1. Serializable Isolation versus True Serializability

200

 

12.3. Explicit Locking

200

 

12.3.1. Table-Level Locks

201

12.3.2. Row-Level Locks

202

12.3.3. Deadlocks

203

 

12.4. Data Consistency Checks at the Application Level

203

12.5. Locking and Indexes

204

13. Performance Tips

 

206

 

13.1. Using EXPLAIN

206

13.2. Statistics Used by the Planner

209

13.3. Controlling the Planner with Explicit JOIN Clauses

210

13.4. Populating a Database

212

 

13.4.1. Disable Autocommit

212

13.4.2. Use COPY

212

13.4.3. Remove Indexes

213

13.4.4. Increase maintenance_work_mem

213

13.4.5. Increase checkpoint_segments

213

13.4.6. Run ANALYZE Afterwards

213

III. Server Administration

 

214

14.

Installation Instructions

216

 

14.1. Short Version

 

216

14.2. Requirements

216

14.3. Getting The Source

218

14.4. If You Are Upgrading

218

14.5.

Installation Procedure

219

14.6. Post-Installation Setup

225

14.6.1. Shared Libraries

225

14.6.2. Environment Variables

226

14.7. Supported Platforms

226

15. Client-Only Installation on Windows

232

16. Server Run-time Environment

233

16.1. The PostgreSQL User Account

233

16.2. Creating a Database Cluster

233

16.3. Starting the Database Server

234

16.3.1. Server Start-up Failures

235

16.3.2. Client Connection Problems

236

16.4. Run-time Configuration

237

16.4.1. File Locations

238

16.4.2. Connections and Authentication

239

 

16.4.2.1. Connection Settings

239

16.4.2.2. Security and Authentication

240

16.4.3.

Resource Consumption

241

16.4.3.1. Memory

241

16.4.3.2. Free Space Map

242

16.4.3.3. Kernel Resource Usage

242

16.4.3.4. Cost-Based Vacuum Delay

243

16.4.3.5. Background Writer

243

16.4.4.

Write Ahead Log

244

16.4.4.1. Settings

244

16.4.4.2. Checkpoints

245

16.4.4.3. Archiving

246

16.4.5.

Query Planning

246

16.4.5.1. Planner Method Configuration

246

16.4.5.2. Planner Cost Constants

247

16.4.5.3. Genetic Query Optimizer

248

16.4.5.4. Other Planner Options

248

16.4.6.

Error Reporting and Logging

249

16.4.6.1. Where to log

249

16.4.6.2. When To Log

251

16.4.6.3. What To Log

252

16.4.7.

Runtime Statistics

254

16.4.7.1. Statistics Monitoring

254

16.4.7.2. Query and Index Statistics Collector

254

16.4.8.

Client Connection Defaults

255

16.4.8.1. Statement Behavior

255

16.4.8.2. Locale and Formatting

256

16.4.8.3. Other Defaults

257

16.4.9.

Lock Management

258

16.4.10.

Version and Platform Compatibility

258

16.4.10.1. Previous PostgreSQL Versions

258

16.4.10.2. Platform and Client Compatibility

259

16.4.11. Preset Options

259

16.4.12. Customized Options

260

16.4.13. Developer Options

261

16.4.14. Short Options

262

16.5. Managing Kernel Resources

263

16.5.1.

Shared Memory and Semaphores

263

 

16.5.2. Resource Limits

267

16.5.3. Linux Memory Overcommit

268

16.6. Shutting Down the Server

269

16.7. Secure TCP/IP Connections with SSL

270

16.8. Secure TCP/IP Connections with SSH Tunnels

270

17. Database Users and Privileges

272

17.1. Database Users

272

17.2. User Attributes

273

17.3. Groups

 

273

17.4. Privileges

274

17.5. Functions and Triggers

274

18. Managing Databases

 

276

18.1. Overview

276

18.2. Creating a Database

276

18.3. Template Databases

277

18.4. Database Configuration

278

18.5. Destroying a Database

279

18.6. Tablespaces

 

279

19. Client Authentication

281

19.1. The pg_hba.conf file

281

19.2. Authentication methods

285

 

19.2.1. Trust authentication

285

19.2.2. Password authentication

286

19.2.3. Kerberos authentication

286

19.2.4. Ident-based authentication

287

19.2.4.1. Ident Authentication over TCP/IP

287

19.2.4.2. Ident Authentication over Local Sockets

288

19.2.4.3. Ident Maps

288

19.2.5.

PAM authentication

289

19.3. Authentication problems

289

20. Localization

 

290

20.1. Locale Support

290

 

20.1.1. Overview

290

20.1.2. Behavior

291

20.1.3. Problems

291

20.2. Character Set Support

292

 

20.2.1. Supported Character Sets

292

20.2.2. Setting the Character Set

293

20.2.3. Automatic Character Set Conversion Between Server and Client

294

20.2.4. Further Reading

296

21. Routine Database Maintenance Tasks

297

21.1. Routine Vacuuming

297

 

21.1.1. Recovering disk space

297

21.1.2. Updating planner statistics

298

21.1.3. Preventing transaction ID wraparound failures

299

21.2. Routine Reindexing

301

21.3. Log File Maintenance

301

22. Backup and Restore

 

303

22.1.

SQL Dump

303

22.1.1. Restoring the dump

303

22.1.2. Using pg_dumpall

304

22.1.3.

Handling large databases

304

 

22.1.4.

Caveats

305

22.2. File system level backup

305

22.3. On-line backup and point-in-time recovery (PITR)

306

 

22.3.1. Setting up WAL archiving

307

22.3.2. Making a Base Backup

309

22.3.3.

Recovering with an On-line Backup

310

22.3.3.1. Recovery Settings

311

22.3.4.

Timelines

312

22.3.5.

Caveats

313

22.4. Migration Between Releases

313

23. Monitoring Database Activity

315

23.1. Standard Unix Tools

315

23.2. The Statistics Collector

315

 

23.2.1. Statistics Collection Configuration

316

23.2.2. Viewing Collected Statistics

316

23.3. Viewing Locks

 

320

24. Monitoring Disk Usage

321

24.1. Determining Disk Usage

321

24.2. Disk Full Failure

322

25. Write-Ahead Logging (WAL)

323

25.1. Benefits of WAL

323

25.2. WAL Configuration

323

25.3. Internals

 

325

26. Regression Tests

326

26.1. Running the Tests

326

26.2. Test Evaluation

327

 

26.2.1. Error message differences

327

26.2.2. Locale differences

327

26.2.3. Date and time differences

328

26.2.4. Floating-point differences

328

26.2.5. Row ordering differences

328

26.2.6. The “random” test

329

26.3. Platform-specific comparison files

329

IV. Client Interfaces

 

331

27.

libpq - C Library

333

27.1. Database Connection Control Functions

333

27.2. Connection Status Functions

339

27.3. Command Execution Functions

342

 

27.3.1. Main Functions

342

27.3.2. Retrieving Query Result Information

348

27.3.3. Retrieving Result Information for Other Commands

351

27.3.4. Escaping Strings for Inclusion in SQL Commands

352

27.3.5. Escaping Binary Strings for Inclusion in SQL Commands

353

27.4. Asynchronous Command Processing

354

27.5. Cancelling Queries in Progress

357

27.6. The Fast-Path Interface

358

27.7. Asynchronous Notification

359

27.8. Functions Associated with the COPY Command

360

 

27.8.1. Functions for Sending COPY Data

361

27.8.2. Functions for Receiving COPY Data

362

27.8.3.

Obsolete Functions for COPY

363

27.9.

Control Functions

365

27.10. Notice Processing

365

27.11. Environment Variables

366

27.12. The Password File

368

27.13. SSL Support

368

27.14. Behavior in Threaded Programs

368

27.15. Building libpq Programs

369

27.16. Example Programs

370

28. Large Objects

379

 

28.1. History

379

28.2. Implementation Features

379

28.3. Client Interfaces

379

 

28.3.1. Creating a Large Object

379

28.3.2. Importing a Large Object

380

28.3.3. Exporting a Large Object

380

28.3.4. Opening an Existing Large Object

380

28.3.5. Writing Data to a Large Object

380

28.3.6. Reading Data from a Large Object

381

28.3.7. Seeking in a Large Object

381

28.3.8. Obtaining the Seek Position of a Large Object

381

28.3.9. Closing a Large Object Descriptor

381

28.3.10. Removing a Large Object

381

28.4. Server-Side Functions

382

28.5. Example Program

382

29. ECPG - Embedded SQL in C

388

29.1. The Concept

388

29.2. Connecting to the Database Server

388

29.3. Closing a Connection

389

29.4. Running SQL Commands

390

29.5. Choosing a Connection

391

29.6. Using Host Variables

391

 

29.6.1. Overview

391

29.6.2. Declare Sections

392

29.6.3. SELECT INTO and FETCH INTO

392

29.6.4. Indicators

393

29.7. Dynamic SQL

394

29.8. Using SQL Descriptor Areas

394

29.9. Error Handling

396

 

29.9.1. Setting Callbacks

396

29.9.2. sqlca

398

29.9.3. SQLSTATE vs SQLCODE

399

29.10. Including Files

401

29.11. Processing Embedded SQL Programs

402

29.12. Library Functions

402

29.13. Internals

403

30. The Information Schema

406

30.1. The Schema

406

30.2. Data Types

406

30.3. information_schema_catalog_name

406

30.4. applicable_roles

407

30.5. check_constraints

407

30.6.

column_domain_usage

407

30.7. column_privileges

408

30.8. column_udt_usage

409

30.9. columns

409

30.10. constraint_column_usage

413

30.11. constraint_table_usage

414

30.12. data_type_privileges

414

30.13. domain_constraints

415

30.14. domain_udt_usage

415

30.15. domains

416

30.16. element_types

419

30.17. enabled_roles

421

30.18. key_column_usage

422

30.19. parameters

422

30.20. referential_constraints

425

30.21. role_column_grants

426

30.22. role_routine_grants

426

30.23. role_table_grants

427

30.24. role_usage_grants

428

30.25. routine_privileges

428

30.26. routines

429

30.27. schemata

433

30.28. sql_features

434

30.29. sql_implementation_info

434

30.30. sql_languages

435

30.31. sql_packages

436

30.32. sql_sizing

436

30.33. sql_sizing_profiles

437

30.34. table_constraints

437

30.35. table_privileges

438

30.36. tables

438

30.37. triggers

439

30.38. usage_privileges

440

30.39. view_column_usage

441

30.40. view_table_usage

442

30.41. views

442

V. Server Programming

444

31. Extending SQL

446

31.1. How Extensibility Works

446

31.2. The PostgreSQL Type System

446

31.2.1. Base Types

446

31.2.2. Composite Types

446

31.2.3. Domains

447

31.2.4. Pseudo-Types

447

31.2.5. Polymorphic Types

447

31.3. User-Defined Functions

447

31.4. Query Language (SQL) Functions

448

31.4.1. SQL Functions on Base Types

449

31.4.2. SQL Functions on Composite Types

450

31.4.3. SQL Functions as Table Sources

453

31.4.4. SQL Functions Returning Sets

454

31.4.5.

Polymorphic SQL Functions

455

31.5. Function Overloading

456

31.6. Function Volatility Categories

456

31.7. Procedural Language Functions

457

31.8. Internal Functions

458

31.9. C-Language Functions

458

 

31.9.1. Dynamic Loading

458

31.9.2. Base Types in C-Language Functions

459

31.9.3. Calling Conventions Version 0 for C-Language Functions

462

31.9.4. Calling Conventions Version 1 for C-Language Functions

464

31.9.5. Writing Code

466

31.9.6. Compiling and Linking Dynamically-Loaded Functions

467

31.9.7. Extension Building Infrastructure

469

31.9.8. Composite-Type Arguments in C-Language Functions

471

31.9.9. Returning Rows (Composite Types) from C-Language Functions

472

31.9.10. Returning Sets from C-Language Functions

473

31.9.11. Polymorphic Arguments and Return Types

478

31.10. User-Defined Aggregates

479

31.11. User-Defined Types

481

31.12. User-Defined Operators

484

31.13. Operator Optimization Information

485

 

31.13.1. COMMUTATOR

485

31.13.2. NEGATOR

486

31.13.3. RESTRICT

486

31.13.4. JOIN

487

31.13.5. HASHES

487

31.13.6. MERGES (SORT1, SORT2, LTCMP, GTCMP)

488

31.14. Interfacing Extensions To Indexes

489

 

31.14.1. Index Methods and Operator Classes

490

31.14.2. Index Method Strategies

490

31.14.3. Index Method Support Routines

491

31.14.4. An Example

492

31.14.5. Cross-Data-Type Operator Classes

495

31.14.6. System Dependencies on Operator Classes

495

31.14.7. Special Features of Operator Classes

496

32. Triggers

497

32.1. Overview of Trigger Behavior

497

32.2. Visibility of Data Changes

498

32.3. Writing Trigger Functions in C

499

32.4. A Complete Example

501

33. The Rule System

 

505

33.1. The Query Tree

505

33.2. Views and the Rule System

507

 

33.2.1. How SELECT Rules Work

507

33.2.2. View Rules in Non-SELECT Statements

512

33.2.3. The Power of Views in PostgreSQL

513

33.2.4. Updating a View

513

33.3. Rules on INSERT, UPDATE, and DELETE

513

 

33.3.1.

How Update Rules Work

514

 

33.3.1.1. A First Rule Step by Step

515

 

33.3.2.

Cooperation with Views

518

33.4. Rules and Privileges

523

33.5.

Rules and Command Status

524

33.6.

Rules versus Triggers

525

34. Procedural Languages

 

528

34.1.

Installing Procedural Languages

528

35. PL/pgSQL - SQL Procedural Language

530

35.1. Overview

 

530

 

35.1.1. Advantages of Using PL/pgSQL

531

35.1.2. Supported Argument and Result Data Types

531

35.2. Tips for Developing in PL/pgSQL

532

 

35.2.1.

Handling of Quotation Marks

532

35.3. Structure of PL/pgSQL

534

35.4. Declarations

 

535

 

35.4.1. Aliases for Function Parameters

535

35.4.2. Copying Types

537

35.4.3.

Row Types

537

35.4.4. Record Types

538

35.4.5. RENAME

538

35.5. Expressions

 

538

35.6. Basic Statements

539

 

35.6.1. Assignment

540

35.6.2. SELECT INTO

540

35.6.3. Executing an Expression or Query With No Result

541

35.6.4. Doing Nothing At All

541

35.6.5. Executing Dynamic Commands

542

35.6.6. Obtaining the Result Status

543

35.7. Control Structures

544

 

35.7.1.

Returning From a Function

544

 

35.7.1.1. RETURN

544

35.7.1.2. RETURN NEXT

544

 

35.7.2.

Conditionals

545

 

35.7.2.1. IF-THEN

545

35.7.2.2. IF-THEN-ELSE

546

35.7.2.3. IF-THEN-ELSE IF

546

35.7.2.4. IF-THEN-ELSIF-ELSE

546

35.7.2.5. IF-THEN-ELSEIF-ELSE

547

 

35.7.3.

Simple Loops

547

 

35.7.3.1. LOOP

547

35.7.3.2. EXIT

547

35.7.3.3. WHILE

548

35.7.3.4. FOR (integer variant)

549

 

35.7.4.

Looping Through Query Results

549

35.7.5.

Trapping Errors

550

35.8. Cursors

551

 

35.8.1.

Declaring Cursor Variables

551

35.8.2.

Opening Cursors

552

 

35.8.2.1. OPEN FOR SELECT

552

35.8.2.2. OPEN FOR EXECUTE

552

35.8.2.3. Opening a Bound Cursor

553

 

35.8.3.

Using Cursors

553

 

35.8.3.1. FETCH

553

35.8.3.2. CLOSE

553

35.8.3.3. Returning Cursors

554

35.9.

Errors and Messages

555

35.10. Trigger Procedures

556

35.11. Porting from Oracle PL/SQL

561

35.11.1. Porting Examples

561

35.11.2. Other Things to Watch For

567

35.11.2.1. Implicit Rollback after Exceptions

567

35.11.2.2. EXECUTE

567

35.11.2.3. Optimizing PL/pgSQL Functions

567

35.11.3.

Appendix

568

36. PL/Tcl - Tcl Procedural Language

571

36.1. Overview

571

36.2. PL/Tcl Functions and Arguments

571

36.3. Data Values in PL/Tcl

572

36.4. Global Data in PL/Tcl

573

36.5. Database Access from PL/Tcl

573

36.6. Trigger Procedures in PL/Tcl

575

36.7. Modules and the unknown command

577

36.8. Tcl Procedure Names

577

37. PL/Perl - Perl Procedural Language

578

37.1. PL/Perl Functions and Arguments

578

37.2. Database Access from PL/Perl

580

37.3. Data Values in PL/Perl

581

37.4. Global Values in PL/Perl

581

37.5. Trusted and Untrusted PL/Perl

582

37.6. PL/Perl Triggers

583

37.7. Limitations and Missing Features

584

38. PL/Python - Python Procedural Language

585

38.1. PL/Python Functions

585

38.2. Trigger Functions

586

38.3. Database Access

586

39. Server Programming Interface

588

39.1. Interface Functions

588

SPI_connect

588

SPI_finish

590

SPI_push

591

SPI_pop

592

SPI_execute

593

SPI_exec

596

SPI_prepare

597

SPI_getargcount

599

SPI_getargtypeid

600

SPI_is_cursor_plan

601

SPI_execute_plan

602

SPI_execp

604

SPI_cursor_open

605

SPI_cursor_find

606

SPI_cursor_fetch

607

SPI_cursor_move

608

SPI_cursor_close

609

SPI_saveplan

610

39.2. Interface Support Functions

611

SPI_fname

611

 

SPI_fnumber

612

SPI_getvalue

613

SPI_getbinval

614

SPI_gettype

615

SPI_gettypeid

616

SPI_getrelname

617

39.3. Memory Management

618

SPI_palloc

618

SPI_repalloc

620

SPI_pfree

621

SPI_copytuple

622

SPI_returntuple

623

SPI_modifytuple

624

SPI_freetuple

626

SPI_freetuptable

627

SPI_freeplan

628

39.4. Visibility of Data Changes

629

39.5. Examples

629

VI. Reference

632

I. SQL Commands

634

ABORT

635

ALTER AGGREGATE

637

ALTER CONVERSION

639

ALTER DATABASE

640

ALTER DOMAIN

642

ALTER FUNCTION

644

ALTER GROUP

646

ALTER INDEX

648

ALTER LANGUAGE

650

ALTER OPERATOR

651

ALTER OPERATOR CLASS

652

ALTER

SCHEMA

653

ALTER SEQUENCE

654

ALTER TABLE

656

ALTER TABLESPACE

662

ALTER TRIGGER

664

ALTER TYPE

665

ALTER USER

666

ANALYZE

669

BEGIN

671

CHECKPOINT

673

CLOSE

674

CLUSTER

675

COMMENT

678

COMMIT

681

COPY

682

CREATE AGGREGATE

689

CREATE CAST

692

CREATE CONSTRAINT TRIGGER

695

CREATE CONVERSION

696

CREATE DATABASE

698

CREATE DOMAIN

700

CREATE FUNCTION

702

CREATE GROUP

706

CREATE INDEX

708

CREATE LANGUAGE

711

CREATE OPERATOR

713

CREATE OPERATOR CLASS

716

CREATE RULE

719

CREATE SCHEMA

722

CREATE SEQUENCE

724

CREATE TABLE

727

CREATE TABLE AS

737

CREATE TABLESPACE

739

CREATE TRIGGER

741

CREATE TYPE

744

CREATE USER

750

CREATE VIEW

753

DEALLOCATE

756

DECLARE

757

DELETE

760

DROP AGGREGATE

762

DROP CAST

763

DROP CONVERSION

764

DROP DATABASE

765

DROP DOMAIN

766

DROP FUNCTION

767

DROP GROUP

768

DROP INDEX

769

DROP LANGUAGE

770

DROP OPERATOR

771

DROP OPERATOR CLASS

773

DROP RULE

774

DROP SCHEMA

775

DROP SEQUENCE

776

DROP TABLE

777

DROP TABLESPACE

779

DROP TRIGGER

780

DROP TYPE

781

DROP USER

782

DROP VIEW

784

END

785

EXECUTE

786

EXPLAIN

788

FETCH

791

GRANT

795

INSERT

800

LISTEN

803

LOAD

805

LOCK

806

MOVE

809

NOTIFY

811

PREPARE

813

REINDEX

815

RELEASE SAVEPOINT

818

RESET

820

REVOKE

821

ROLLBACK

824

ROLLBACK TO SAVEPOINT

825

SAVEPOINT

827

SELECT

829

SELECT INTO

840

SET

842

SET CONSTRAINTS

845

SET SESSION AUTHORIZATION

846

SET TRANSACTION

848

SHOW

850

START TRANSACTION

852

TRUNCATE

853

UNLISTEN

854

UPDATE

856

VACUUM

859

II. PostgreSQL Client Applications

862

clusterdb

863

createdb

866

createlang

869

createuser

872

dropdb

875

droplang

878

dropuser

880

ecpg

883

pg_config

885

pg_dump

887

pg_dumpall

894

pg_restore

898

psql

904

vacuumdb

927

III. PostgreSQL Server Applications

930

initdb

931

ipcclean

934

pg_controldata

935

pg_ctl

936

pg_resetxlog

940

postgres

942

postmaster

946

VII. Internals

951

40. Overview of PostgreSQL Internals

953

40.1. The Path of a Query

953

40.2. How Connections are Established

953

40.3. The Parser Stage

954

40.3.1. Parser

954

40.3.2. Transformation Process

955

40.4. The PostgreSQL Rule System

955

40.5. Planner/Optimizer

955

40.5.1.

Generating Possible Plans

956

40.6.

Executor

957

41. System Catalogs

958

41.1. Overview

958

41.2. pg_aggregate

959

 

41.3. pg_am

959

41.4. pg_amop

961

41.5. pg_amproc

961

41.6. pg_attrdef

962

41.7. pg_attribute

962

41.8. pg_cast

965

41.9. pg_class

966

41.10. pg_constraint

969

41.11. pg_conversion

970

41.12. pg_database

971

41.13. pg_depend

972

41.14. pg_description

974

41.15. pg_group

974

41.16. pg_index

975

41.17. pg_inherits

976

41.18. pg_language

976

41.19. pg_largeobject

977

41.20. pg_listener

978

41.21. pg_namespace

978

41.22. pg_opclass

979

41.23. pg_operator

979

41.24. pg_proc

981

41.25. pg_rewrite

983

41.26. pg_shadow

983

41.27. pg_statistic

984

41.28. pg_tablespace

986

41.29. pg_trigger

986

41.30. pg_type

987

41.31. System Views

993

41.32. pg_indexes

994

41.33. pg_locks

994

41.34. pg_rules

996

41.35. pg_settings

996

41.36. pg_stats

997

41.37. pg_tables

999

41.38. pg_user

1000

41.39. pg_views

1000

42. Frontend/Backend Protocol

1002

42.1. Overview

1002

 

42.1.1. Messaging Overview

1002

42.1.2. Extended Query Overview

1003

42.1.3. Formats and Format Codes

1003

42.2. Message Flow

1004

 

42.2.1. Start-Up

1004

42.2.2. Simple Query

1006

42.2.3. Extended Query

1007

42.2.4. Function Call

1010

42.2.5.

COPY Operations

1010

42.2.6. Asynchronous Operations

1011

42.2.7. Cancelling Requests in Progress

1012

42.2.8. Termination

1013

42.2.9. SSL Session Encryption

1013

42.3. Message Data Types

1014

42.4. Message Formats

1014

42.5. Error and Notice Message Fields

1030

42.6. Summary of Changes since Protocol 2.0

1031

43. PostgreSQL Coding Conventions

1033

43.1. Formatting

1033

43.2. Reporting Errors Within the Server

1033

43.3. Error Message Style Guide

1035

43.3.1. What goes where

1035

43.3.2. Formatting

1036

43.3.3. Quotation marks

1036

43.3.4. Use of quotes

1036

43.3.5. Grammar and punctuation

1037

43.3.6. Upper case vs. lower case

1037

43.3.7. Avoid passive voice

1037

43.3.8. Present vs past tense

1037

43.3.9. Type of the object

1038

43.3.10. Brackets

1038

43.3.11. Assembling error messages

1038

43.3.12. Reasons for errors

1038

43.3.13. Function names

1038

43.3.14. Tricky words to avoid

1039

43.3.15. Proper spelling

1039

43.3.16. Localization

1040

44. Native Language Support

1041

44.1. For the Translator

1041

44.1.1. Requirements

1041

44.1.2. Concepts

1041

44.1.3. Creating and maintaining message catalogs

1042

44.1.4. Editing the PO files

1043

44.2. For the Programmer

1044

44.2.1. Mechanics

1044

44.2.2. Message-writing guidelines

1045

45. Writing A Procedural Language Handler

1046

46. Genetic Query Optimizer

1048

46.1. Query Handling as a Complex Optimization Problem

1048

46.2. Genetic Algorithms

1048

46.3. Genetic Query Optimization (GEQO) in PostgreSQL

1049

46.3.1.

Future Implementation Tasks for PostgreSQL GEQO

1050

46.4. Further Reading

1050

47. Index Cost Estimation Functions

1051

48. GiST Indexes

1054

48.1. Introduction

1054

48.2. Extensibility

1054

48.3. Implementation

1054

48.4. Limitations

1055

48.5. Examples

1055

49.

Database Physical Storage

1057

 

49.1. Database File Layout

1057

49.2. TOAST

1058

49.3. Database Page Layout

1060

50.

BKI Backend Interface

1063

50.1. BKI File Format

1063

50.2. BKI Commands

1063

50.3. Example

1064

VIII. Appendixes

1065

A. PostgreSQL Error Codes

1066

B. Date/Time Support

1073

B.1. Date/Time Input Interpretation

1073

B.2. Date/Time Key Words

1074

B.3. History of Units

1088

C. SQL Key Words

1090

D. SQL Conformance

1109

D.1. Supported Features

1110

D.2. Unsupported Features

1120

E. Release Notes

1128

E.1. Release 8.0

1128

E.1.1. Overview

1128

E.1.2. Migration to version 8.0

1129

E.1.3. Deprecated Features

1130

E.1.4. Changes

1131

E.1.4.1. Performance Improvements

1131

E.1.4.2. Server Changes

1133

E.1.4.3. Query Changes

1134

E.1.4.4. Object Manipulation Changes

1136

E.1.4.5. Utility Command Changes

1137

E.1.4.6. Data Type and Function Changes

1138

E.1.4.7. Server-Side Language Changes

1140

E.1.4.8. psql Changes

1141

E.1.4.9. pg_dump Changes

1141

E.1.4.10. libpq Changes

1142

E.1.4.11. Source Code Changes

1142

E.1.4.12. Contrib Changes

1144

E.2. Release 7.4.6

1144

E.2.1. Migration to version 7.4.6

1144

E.2.2. Changes

1144

E.3. Release 7.4.5

1145

E.3.1. Migration to version 7.4.5

1145

E.3.2. Changes

1145

E.4. Release 7.4.4

1146

E.4.1. Migration to version 7.4.4

1146

E.4.2. Changes

1146

E.5. Release 7.4.3

1146

E.5.1. Migration to version 7.4.3

1147

E.5.2. Changes

1147

E.6. Release 7.4.2

1147

E.6.1. Migration to version 7.4.2

1148

E.6.2. Changes

1149

E.7. Release 7.4.1

1149

E.7.1. Migration to version 7.4.1

1150

E.7.2. Changes

1150

E.8. Release 7.4

1151

E.8.1. Overview

1151

E.8.2. Migration to version 7.4

1153

E.8.3. Changes

1154

E.8.3.1. Server Operation Changes

1154

E.8.3.2. Performance Improvements

1155

E.8.3.3. Server Configuration Changes

1157

E.8.3.4. Query Changes

1158

E.8.3.5. Object Manipulation Changes

1159

E.8.3.6. Utility Command Changes

1160

E.8.3.7. Data Type and Function Changes

1161

E.8.3.8. Server-Side Language Changes

1163

E.8.3.9. psql Changes

1163

E.8.3.10. pg_dump Changes

1164

E.8.3.11. libpq Changes

1165

E.8.3.12. JDBC Changes

1165

E.8.3.13. Miscellaneous Interface Changes

1166

E.8.3.14. Source Code Changes

1166

E.8.3.15. Contrib Changes

1167

E.9. Release 7.3.8

1167

E.9.1. Migration to version 7.3.8

1168

E.9.2. Changes

1168

E.10. Release 7.3.7

1168

E.10.1. Migration to version 7.3.7

1168

E.10.2. Changes

1168

E.11. Release 7.3.6

1169

E.11.1. Migration to version 7.3.6

1169