postgresql/contrib/dblink/README.dblink

/*
 * dblink
 *
 * Functions returning results from a remote database
 *
 * Joe Conway <mail@joeconway.com>
 * And contributors:
 * Darko Prenosil <Darko.Prenosil@finteh.hr>
 * Shridhar Daithankar <shridhar_daithankar@persistent.co.in>
 *
 * Copyright (c) 2001-2005, PostgreSQL Global Development Group
 * ALL RIGHTS RESERVED;
 * 
 * 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 AUTHOR OR DISTRIBUTORS 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 AUTHOR OR DISTRIBUTORS HAVE BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAS NO OBLIGATIONS TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 *
 */

Release Notes:
  Version 0.7 (as of 25 Feb, 2004)
    - Added new version of dblink, dblink_exec, dblink_open, dblink_close,
      and, dblink_fetch -- allows ERROR on remote side of connection to
      throw NOTICE locally instead of ERROR
  Version 0.6
    - functions deprecated in 0.5 have been removed
    - added ability to create "named" persistent connections
  Version 0.5
    - dblink now supports use directly as a table function; this is the new
      preferred usage going forward
    - Use of dblink_tok is now deprecated; original form of dblink is also
      deprecated. They _will_ be removed in the next version.
    - dblink_last_oid is also deprecated; use dblink_exec() which returns
      the command status as a single row, single column result.
    - Original dblink, dblink_tok, and dblink_last_oid are commented out in
      dblink.sql; remove the comments to use the deprecated functions.
    - dblink_strtok() and dblink_replace() functions were removed. Use
      split() and replace() respectively (new backend functions in
      PostgreSQL 7.3) instead.
    - New functions: dblink_exec() for non-SELECT queries; dblink_connect()
      opens connection that persists for duration of a backend;
      dblink_disconnect() closes a persistent connection; dblink_open()
      opens a cursor; dblink_fetch() fetches results from an open cursor.
      dblink_close() closes a cursor.
    - New test suite: dblink_check.sh, dblink.test.sql,
      dblink.test.expected.out. Execute dblink_check.sh from the same
      directory as the other two files. Output is dblink.test.out and
      dblink.test.diff. Note that dblink.test.sql is a good source
      of example usage.

  Version 0.4
    - removed cursor wrap around input sql to allow for remote
      execution of INSERT/UPDATE/DELETE
	- dblink now returns a resource id instead of a real pointer
    - added several utility functions -- see below

  Version 0.3
    - fixed dblink invalid pointer causing corrupt elog message
    - fixed dblink_tok improper handling of null results
    - fixed examples in README.dblink

  Version 0.2
    - initial release    

Installation:
  Place these files in a directory called 'dblink' under 'contrib' in the PostgreSQL source tree. Then run:

    make
    make install

  You can use dblink.sql to create the functions in your database of choice, e.g.

    psql template1 < dblink.sql

  installs following functions into database template1:

     connection
     ------------
     dblink_connect(text) RETURNS text
       - opens an unnamed connection that will persist for duration of
         current backend or until it is disconnected
     dblink_connect(text,text) RETURNS text
       - opens a named connection that will persist for duration of current
         backend or until it is disconnected
     dblink_disconnect() RETURNS text
       - disconnects the unnamed persistent connection
     dblink_disconnect(text) RETURNS text
       - disconnects a named persistent connection

     cursor
     ------------
     dblink_open(text,text [, bool fail_on_error]) RETURNS text
       - opens a cursor using unnamed connection already opened with
         dblink_connect() that will persist for duration of current backend
         or until it is closed
     dblink_open(text,text,text [, bool fail_on_error]) RETURNS text
       - opens a cursor using a named connection already opened with
         dblink_connect() that will persist for duration of current backend
         or until it is closed
     dblink_fetch(text, int [, bool fail_on_error]) RETURNS setof record
       - fetches data from an already opened cursor on the unnamed connection
     dblink_fetch(text, text, int [, bool fail_on_error]) RETURNS setof record
       - fetches data from an already opened cursor on a named connection
     dblink_close(text [, bool fail_on_error]) RETURNS text
       - closes a cursor on the unnamed connection
     dblink_close(text,text [, bool fail_on_error]) RETURNS text
       - closes a cursor on a named connection

     query
     ------------
     dblink(text,text [, bool fail_on_error]) RETURNS setof record
       - returns a set of results from remote SELECT query; the first argument
         is either a connection string, or the name of an already opened
         persistant connection
     dblink(text [, bool fail_on_error]) RETURNS setof record
       - returns a set of results from remote SELECT query, using the unnamed
         connection already opened with dblink_connect()

     execute
     ------------
     dblink_exec(text, text [, bool fail_on_error]) RETURNS text
       - executes an INSERT/UPDATE/DELETE query remotely; the first argument
         is either a connection string, or the name of an already opened
         persistant connection
     dblink_exec(text [, bool fail_on_error]) RETURNS text
       - executes an INSERT/UPDATE/DELETE query remotely, using connection
         already opened with dblink_connect()

     misc
     ------------
     dblink_current_query() RETURNS text
       - returns the current query string
     dblink_get_pkey(text) RETURNS setof text
       - returns the field names of a relation's primary key fields
     dblink_build_sql_insert(text,int2vector,int2,_text,_text) RETURNS text
       - builds an insert statement using a local tuple, replacing the
         selection key field values with alternate supplied values
     dblink_build_sql_delete(text,int2vector,int2,_text) RETURNS text
       - builds a delete statement using supplied values for selection
         key field values
     dblink_build_sql_update(text,int2vector,int2,_text,_text) RETURNS text
       - builds an update statement using a local tuple, replacing the
         selection key field values with alternate supplied values

Documentation:

  Note: Parameters representing relation names must include double
     quotes if the names are mixed-case or contain special characters. They
     must also be appropriately qualified with schema name if applicable.

  See the following files:
     doc/connection
     doc/cursor
     doc/query
     doc/execute
     doc/misc

==================================================================
-- Joe Conway