postgresql/contrib/dblink
Tom Lane 6f7fc0bade Cause initdb to create a third standard database "postgres", which
unlike template0 and template1 does not have any special status in
terms of backend functionality.  However, all external utilities such
as createuser and createdb now connect to "postgres" instead of
template1, and the documentation is changed to encourage people to use
"postgres" instead of template1 as a play area.  This should fix some
longstanding gotchas involving unexpected propagation of database
objects by createdb (when you used template1 without understanding
the implications), as well as ameliorating the problem that CREATE
DATABASE is unhappy if anyone else is connected to template1.
Patch by Dave Page, minor editing by Tom Lane.  All per recent
pghackers discussions.
2005-06-21 04:02:34 +00:00
..
doc Cause initdb to create a third standard database "postgres", which 2005-06-21 04:02:34 +00:00
expected Add a --dbname option to the pg_regress script, and use pl_regression 2005-05-17 18:26:23 +00:00
sql Add a --dbname option to the pg_regress script, and use pl_regression 2005-05-17 18:26:23 +00:00
dblink.c Document get_call_result_type() and friends; mark TypeGetTupleDesc() 2005-05-30 23:09:07 +00:00
dblink.h Update copyrights that were missed. 2005-01-01 05:43:09 +00:00
dblink.sql.in Added new versions of dblink, dblink_exec, dblink_open, dblink_close, 2004-03-07 02:27:00 +00:00
Makefile > Please find enclose a submission to fix these problems. 2004-08-20 20:13:10 +00:00
README.dblink Some more missed copyright notices. Many of these look like they 2005-01-01 20:44:34 +00:00

/*
 * 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