PostgreSQL 7.3.2 Programmer’s Guide The PostgreSQL Global Development Group PostgreSQL 7.3.2 Programmer’s Guide by The PostgreSQL Global Development Group Copyright © 1996-2002 by The PostgreSQL Global Development Group Legal Notice PostgreSQL is Copyright © 1996-2002 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 Short History of PostgreSQL ...............................................................................................i 2.1. The Berkeley POSTGRES Project .............................................................................ii 2.2. Postgres95...................................................................................................................ii 2.3. PostgreSQL................................................................................................................iii 3. What’s In This Book ..............................................................................................................iii 4. Overview of Documentation Resources.................................................................................iv 5. Terminology and Notation ......................................................................................................v 6. Bug Reporting Guidelines.......................................................................................................v 6.1. Identifying Bugs ........................................................................................................vi 6.2. What to report............................................................................................................vi 6.3. Where to report bugs ...............................................................................................viii I. Client Interfaces ..............................................................................................................................1 1. libpq - C Library .....................................................................................................................1 1.1. Introduction ................................................................................................................1 1.2. Database Connection Functions .................................................................................1 1.3. Command Execution Functions .................................................................................7 1.3.1. Main Routines................................................................................................7 1.3.2. Escaping strings for inclusion in SQL queries...............................................8 1.3.3. Escaping binary strings for inclusion in SQL queries ...................................9 1.3.4. Retrieving SELECT Result Information........................................................9 1.3.5. Retrieving SELECT Result Values ..............................................................10 1.3.6. Retrieving Non-SELECT Result Information .............................................11 1.4. Asynchronous Query Processing..............................................................................12 1.5. The Fast-Path Interface.............................................................................................15 1.6. Asynchronous Notification.......................................................................................15 1.7. Functions Associated with the COPY Command ....................................................16 1.8. libpq Tracing Functions............................................................................................18 1.9. libpq Control Functions............................................................................................18 1.10. Environment Variables ...........................................................................................19 1.11. Files ........................................................................................................................20 1.12. Threading Behavior ................................................................................................20 1.13. Building Libpq Programs .......................................................................................21 1.14. Example Programs..................................................................................................22 2. Large Objects ........................................................................................................................31 2.1. Introduction ..............................................................................................................31 2.2. Implementation Features ..........................................................................................31 2.3. Interfaces ..................................................................................................................31 2.3.1. Creating a Large Object ...............................................................................32 2.3.2. Importing a Large Object.............................................................................32 2.3.3. Exporting a Large Object.............................................................................32 2.3.4. Opening an Existing Large Object...............................................................32 2.3.5. Writing Data to a Large Object....................................................................33 2.3.6. Reading Data from a Large Object ..............................................................33 2.3.7. Seeking on a Large Object...........................................................................33 2.3.8. Closing a Large Object Descriptor ..............................................................33 2.3.9. Removing a Large Object ............................................................................33 2.4. Server-side Built-in Functions..................................................................................33 iii 2.5. Accessing Large Objects from Libpq.......................................................................34 3. pgtcl - Tcl Binding Library ...................................................................................................39 3.1. Introduction ..............................................................................................................39 3.2. Loading pgtcl into your application .........................................................................40 3.3. pgtcl Command Reference Information ...................................................................40 pg_connect .............................................................................................................40 pg_disconnect ........................................................................................................42 pg_conndefaults .....................................................................................................43 pg_exec ..................................................................................................................44 pg_result.................................................................................................................45 pg_select ................................................................................................................47 pg_execute .............................................................................................................49 pg_listen.................................................................................................................51 pg_on_connection_loss..........................................................................................52 pg_lo_creat.............................................................................................................53 pg_lo_open.............................................................................................................54 pg_lo_close ............................................................................................................55 pg_lo_read..............................................................................................................56 pg_lo_write