head	1.16;
access;
symbols
	REL7_4_29:1.9
	REL8_0_25:1.12.4.1
	REL8_1_21:1.12.6.1
	REL8_2_17:1.14
	REL7_4_28:1.9
	REL8_0_24:1.12.4.1
	REL8_1_20:1.12.6.1
	REL8_2_16:1.14
	REL7_4_27:1.9
	REL8_0_23:1.12.4.1
	REL8_1_19:1.12.6.1
	REL8_2_15:1.14
	REL7_4_26:1.9
	REL8_0_22:1.12.4.1
	REL8_1_18:1.12.6.1
	REL8_2_14:1.14
	REL7_4_25:1.9
	REL8_0_21:1.12.4.1
	REL8_1_17:1.12.6.1
	REL8_2_13:1.14
	REL7_4_24:1.9
	REL8_0_20:1.12.4.1
	REL8_1_16:1.12.6.1
	REL8_2_12:1.14
	REL7_4_23:1.9
	REL8_0_19:1.12.4.1
	REL8_1_15:1.12.6.1
	REL8_2_11:1.14
	REL7_4_22:1.9
	REL8_0_18:1.12.4.1
	REL8_1_14:1.12.6.1
	REL8_2_10:1.14
	REL7_4_21:1.9
	REL8_0_17:1.12.4.1
	REL8_1_13:1.12.6.1
	REL8_2_9:1.14
	REL7_4_20:1.9
	REL8_0_16:1.12.4.1
	REL8_1_12:1.12.6.1
	REL8_2_8:1.14
	REL8_2_7:1.14
	REL7_3_21:1.6.2.1
	REL7_4_19:1.9
	REL8_0_15:1.12.4.1
	REL8_1_11:1.12.6.1
	REL8_2_6:1.14
	REL8_3_BETA2:1.15
	REL8_3_BETA1:1.15
	REL7_3_20:1.6.2.1
	REL7_4_18:1.9
	REL8_0_14:1.12.4.1
	REL8_1_10:1.12.6.1
	REL8_2_5:1.14
	REL7_3_19:1.6.2.1
	REL7_4_17:1.9
	REL8_0_13:1.12.4.1
	REL8_1_9:1.12.6.1
	REL8_2_4:1.14
	REL8_0_12:1.12.4.1
	REL8_1_8:1.12.6.1
	REL8_2_3:1.14
	REL7_3_18:1.6.2.1
	REL7_4_16:1.9
	REL8_0_11:1.12.4.1
	REL8_1_7:1.12.6.1
	REL8_2_2:1.14
	REL8_0_10:1.12.4.1
	REL8_1_6:1.12.6.1
	REL8_2_1:1.14
	REL7_4_15:1.9
	REL7_3_17:1.6.2.1
	REL8_2_STABLE:1.14.0.2
	REL8_2_0:1.14
	REL8_2_RC1:1.14
	REL8_2_BETA3:1.14
	REL8_2_BETA2:1.14
	REL8_1_5:1.12.6.1
	REL8_0_9:1.12.4.1
	REL7_4_14:1.9
	REL7_3_16:1.6.2.1
	REL8_2_BETA1:1.14
	REL7_3_15:1.6.2.1
	REL7_4_13:1.9
	REL8_0_8:1.12.4.1
	REL8_1_4:1.12.6.1
	REL7_3_14:1.6.2.1
	REL7_4_12:1.9
	REL8_0_7:1.12.4.1
	REL8_1_3:1.12.6.1
	REL7_3_13:1.6.2.1
	REL7_4_11:1.9
	REL8_0_6:1.12.4.1
	REL8_1_2:1.12.6.1
	REL7_3_12:1.6.2.1
	REL7_4_10:1.9
	REL8_0_5:1.12
	REL8_1_1:1.12
	REL8_1_STABLE:1.12.0.6
	REL8_1_0:1.12
	REL8_1_0RC1:1.12
	REL8_1_0BETA4:1.12
	REL8_1_0BETA3:1.12
	REL7_3_11:1.6.2.1
	REL7_4_9:1.9
	REL8_0_4:1.12
	REL8_1_0BETA2:1.12
	REL8_1_0BETA1:1.12
	REL7_2_8:1.3
	REL7_3_10:1.6.2.1
	REL7_4_8:1.9
	REL8_0_3:1.12
	REL8_0_2:1.12
	REL7_2_7:1.3
	REL7_3_9:1.6.2.1
	REL7_4_7:1.9
	REL8_0_1:1.12
	REL8_0_STABLE:1.12.0.4
	REL8_0_0:1.12.0.2
	REL8_0_0RC5:1.12
	REL8_0_0RC4:1.12
	REL8_0_0RC3:1.11
	REL8_0_0RC2:1.11
	REL8_0_0RC1:1.11
	REL8_0_0BETA5:1.11
	REL8_0_0BETA4:1.11
	REL7_4_6:1.9
	REL7_3_8:1.6.2.1
	REL7_2_6:1.3
	REL8_0_0BETA3:1.11
	REL8_0_0BETA2:1.11
	REL7_2_5:1.3
	REL7_4_5:1.9
	REL7_3_7:1.6.2.1
	REL7_4_4:1.9
	REL8_0_0BETA1:1.10
	REL7_4_3:1.9
	REL7_4_2:1.9
	REL7_3_6:1.6.2.1
	REL7_4_1:1.9
	REL7_3_5:1.6.2.1
	REL7_4:1.9
	REL7_4_RC2:1.9
	REL7_4_STABLE:1.9.0.4
	REL7_4_RC1:1.9
	REL7_4_BETA5:1.9
	REL7_4_BETA4:1.9
	REL7_4_BETA3:1.9
	REL7_4_BETA2:1.9
	WIN32_DEV:1.9.0.2
	REL7_4_BETA1:1.9
	REL7_3_4:1.6.2.1
	REL7_3_2:1.6.2.1
	REL7_2_4:1.3
	REL7_3_STABLE:1.6.0.2
	REL7_2_3:1.3
	REL7_2_STABLE:1.3.0.2
	REL7_2:1.3
	REL7_2_RC2:1.3
	REL7_2_RC1:1.3
	REL7_2_BETA5:1.3
	REL7_2_BETA4:1.2
	REL7_2_BETA3:1.2
	REL7_2_BETA2:1.2
	REL7_2_BETA1:1.2;
locks; strict;
comment	@# @;


1.16
date	2007.11.10.23.30.45;	author momjian;	state dead;
branches;
next	1.15;

1.15
date	2007.01.05.22.19.17;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2006.09.02.21.11.15;	author joe;	state Exp;
branches;
next	1.13;

1.13
date	2006.01.03.23.45.52;	author joe;	state Exp;
branches;
next	1.12;

1.12
date	2005.01.01.20.44.11;	author tgl;	state Exp;
branches
	1.12.4.1
	1.12.6.1;
next	1.11;

1.11
date	2004.08.29.04.12.16;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	2004.03.07.02.27.00;	author joe;	state Exp;
branches;
next	1.9;

1.9
date	2003.08.04.23.59.37;	author tgl;	state Exp;
branches;
next	1.8;

1.8
date	2003.06.25.01.10.15;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2002.11.23.18.59.25;	author tgl;	state Exp;
branches;
next	1.6;

1.6
date	2002.09.02.06.13.31;	author momjian;	state Exp;
branches
	1.6.2.1;
next	1.5;

1.5
date	2002.05.27.21.59.12;	author tgl;	state Exp;
branches;
next	1.4;

1.4
date	2002.04.24.02.28.28;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	2001.12.13.10.48.39;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	2001.06.18.19.09.50;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2001.06.14.16.49.03;	author momjian;	state Exp;
branches;
next	;

1.6.2.1
date	2002.11.23.18.59.29;	author tgl;	state Exp;
branches;
next	;

1.12.4.1
date	2006.01.03.23.47.24;	author joe;	state Exp;
branches;
next	;

1.12.6.1
date	2006.01.03.23.46.32;	author joe;	state Exp;
branches;
next	;


desc
@@


1.16
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@/*
 * 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>
 * Kai Londenberg (K.Londenberg@@librics.de)
 *
 * Copyright (c) 2001-2007, 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:
  27 August 2006
    - Added async query capability. Original patch by
      Kai Londenberg (K.Londenberg@@librics.de), modified by Joe Conway
  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 dblink functions into database template1

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

@


1.15
log
@Update CVS HEAD for 2007 copyright.  Back branches are typically not
back-stamped for this.
@
text
@@


1.14
log
@Added async query capability. Original patch by
Kai Londenberg, modified by Joe Conway
@
text
@d12 1
a12 1
 * Copyright (c) 2001-2006, PostgreSQL Global Development Group
@


1.13
log
@When the remote query result has a different number of columns
than the local query specifies (e.g. in the FROM clause),
throw an ERROR (instead of crashing). Fix for bug #2129 reported
by Akio Iwaasa.
@
text
@d10 1
d35 3
d92 1
a92 69
  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
@


1.12
log
@Some more missed copyright notices.  Many of these look like they
should have been caught by the src/tools/copyright script ... why
weren't they?
@
text
@d11 1
a11 1
 * Copyright (c) 2001-2005, PostgreSQL Global Development Group
@


1.12.4.1
log
@When the remote query result has a different number of columns
than the local query specifies (e.g. in the FROM clause),
throw an ERROR (instead of crashing). Fix for bug #2129 reported
by Akio Iwaasa.
@
text
@d11 1
a11 1
 * Copyright (c) 2001-2006, PostgreSQL Global Development Group
@


1.12.6.1
log
@When the remote query result has a different number of columns
than the local query specifies (e.g. in the FROM clause),
throw an ERROR (instead of crashing). Fix for bug #2129 reported
by Akio Iwaasa.
@
text
@d11 1
a11 1
 * Copyright (c) 2001-2006, PostgreSQL Global Development Group
@


1.11
log
@Update copyright to 2004.
@
text
@d11 1
a11 1
 * Copyright (c) 2001-2004, PostgreSQL Global Development Group
@


1.10
log
@Added new versions 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. Also removed documentation for
previously deprecated, now removed, functions.
@
text
@d11 1
a11 1
 * Copyright (c) 2001-2003, PostgreSQL Global Development Group
@


1.9
log
@Fix some copyright notices that weren't updated.  Improve copyright tool
so it won't miss 'em again.
@
text
@a32 6
Version 0.6 (14 June, 2003):
  Completely removed previously deprecated functions. Added ability
  to create "named" persistent connections in addition to the single global
  "unnamed" persistent connection.
  Tested under Linux (Red Hat 9) and PostgreSQL 7.4devel.

d34 4
d86 1
a86 1
    psql -U postgres template1 < dblink.sql
d105 1
a105 1
     dblink_open(text,text) RETURNS text
d109 1
a109 1
     dblink_open(text,text,text) RETURNS text
d113 1
a113 1
     dblink_fetch(text, int) RETURNS setof record
d115 1
a115 1
     dblink_fetch(text, text, int) RETURNS setof record
d117 1
a117 1
     dblink_close(text) RETURNS text
d119 1
a119 1
     dblink_close(text,text) RETURNS text
d124 1
a124 1
     dblink(text,text) RETURNS setof record
d128 1
a128 1
     dblink(text) RETURNS setof record
d134 1
a134 1
     dblink_exec(text, text) RETURNS text
d138 1
a138 1
     dblink_exec(text) RETURNS text
a169 1
     doc/deprecated
@


1.8
log
@Please apply attached patch to contrib/dblink. It adds named persistent
connections to dblink.

Shridhar Daithanka
@
text
@d11 1
a11 1
 * Copyright (c) 2001, 2002, 2003 by PostgreSQL Global Development Group
@


1.7
log
@Fix inappropriate quoting in dblink.  From Joe Conway.
@
text
@d7 3
d11 1
a11 1
 * Copyright (c) 2001, 2002 by PostgreSQL Global Development Group
d33 5
a37 6
Version 0.5 (25 August, 2002):
  Major overhaul to work with new backend "table function" capability. Removed
  dblink_strtok() and dblink_replace() functions because they are now
  available as backend functions (split() and replace() respectively).
  Tested under Linux (Red Hat 7.3) and PostgreSQL 7.3devel. This version
  is no longer backwards portable to PostgreSQL 7.2.
d40 3
d95 4
a98 1
       - opens a connection that will persist for duration of current
d101 3
a103 1
       - disconnects a persistent connection
d108 7
a114 3
       - opens a cursor using connection already opened with dblink_connect()
         that will persist for duration of current backend or until it is
         closed
d116 3
a118 1
       - fetches data from an already opened cursor
d120 3
a122 1
       - closes a cursor
d127 3
a129 2
       - returns a set of results from remote SELECT query
         (Note: comment out in dblink.sql to use deprecated version)
d131 2
a132 2
       - returns a set of results from remote SELECT query, using connection
         already opened with dblink_connect()
d137 3
a139 1
       - executes an INSERT/UPDATE/DELETE query remotely
a158 13

  Not installed by default
     deprecated
     ------------
     dblink(text,text) RETURNS setof int
       - *DEPRECATED* returns a resource id for results from remote query
         (Note: must uncomment in dblink.sql to use)
     dblink_tok(int,int) RETURNS text
       - *DEPRECATED* extracts and returns individual field results; used
         only in conjunction with the *DEPRECATED* form of dblink
         (Note: must uncomment in dblink.sql to use)
     dblink_last_oid(int) RETURNS oid
       - *DEPRECATED* returns the last inserted oid
@


1.6
log
@Attached is a fairly sizeable update to contrib/dblink. I'd love to get
review/feedback if anyone is interested and can spend the time. But I'd
also love to get this committed and address changes as incremental
patches ;-), so if there are no objections, please apply.

Below I'll give a synopsis of the changes. More detailed descriptions
are now in a new doc directory under contrib/dblink. There is also a new

dblink.test.sql file which will give a pretty good overview of the
functions and their use.

Joe Conway
@
text
@d154 4
@


1.6.2.1
log
@Fix inappropriate quoting in dblink.  From Joe Conway.
@
text
@a153 4
  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.

@


1.5
log
@Update dblink to work with qualified relation names.
From Joe Conway.
@
text
@d6 3
a8 1
 * Copyright (c) Joseph Conway <mail@@joeconway.com>, 2001, 2002,
d30 6
a35 5

Version 0.4 (7 April, 2002):
  Functions allowing remote database INSERT/UPDATE/DELETE/SELECT, and
  various utility functions.
  Tested under Linux (Red Hat 7.2) and PostgreSQL 7.2 and 7.3devel
d38 22
d87 40
a126 6
     dblink(text,text) RETURNS setof int
       - returns a resource id for results from remote query
     dblink_tok(int,int) RETURNS text
       - extracts and returns individual field results
     dblink_strtok(text,text,int) RETURNS text
       - extracts and returns individual token from delimited text
a128 2
     dblink_last_oid(int) RETURNS oid
       - returns the last inserted oid
a137 5
     dblink_current_query() RETURNS text
       - returns the current query string
     dblink_replace(text,text,text) RETURNS text
       - replace all occurences of substring-a in the input-string 
         with substring-b
d139 12
a150 127
Documentation
==================================================================
Name

dblink -- Returns a resource id for a data set from a remote database

Synopsis

dblink(text connstr, text sql)

Inputs

  connstr

    standard libpq format connection srting, 
    e.g. "hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd"

  sql

    sql statement that you wish to execute on the remote host
    e.g. "select * from pg_class"

Outputs

  Returns setof int (res_id)

Example usage

  select dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd'
               ,'select f1, f2 from mytable');


==================================================================

Name

dblink_tok -- Returns individual select field results from a dblink remote query

Synopsis

dblink_tok(int res_id, int fnumber)

Inputs

  res_id

    a resource id returned by a call to dblink()

  fnumber

    the ordinal position (zero based) of the field to be returned from the dblink result set

Outputs

  Returns text

Example usage

  select dblink_tok(t1.dblink_p,0) as f1, dblink_tok(t1.dblink_p,1) as f2
  from (select dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd'
                     ,'select f1, f2 from mytable') as dblink_p) as t1;


==================================================================

A more convenient way to use dblink may be to create a view:

 create view myremotetable as
 select dblink_tok(t1.dblink_p,0) as f1, dblink_tok(t1.dblink_p,1) as f2
 from (select dblink('hostaddr=127.0.0.1 port=5432 dbname=template1 user=postgres password=postgres'
                    ,'select proname, prosrc from pg_proc') as dblink_p) as t1;

Then you can simply write:

   select f1, f2 from myremotetable where f1 like 'bytea%';

==================================================================
Name

dblink_strtok -- Extracts and returns individual token from delimited text

Synopsis

dblink_strtok(text inputstring, text delimiter, int posn) RETURNS text

Inputs

  inputstring

    any string you want to parse a token out of;
    e.g. 'f=1&g=3&h=4'

  delimiter

    a single character to use as the delimiter;
    e.g. '&' or '='

  posn

    the position of the token of interest, 0 based;
    e.g. 1

Outputs

  Returns text

Example usage

test=# select dblink_strtok(dblink_strtok('f=1&g=3&h=4','&',1),'=',1);
 dblink_strtok
---------------
 3
(1 row)

==================================================================
Name

dblink_get_pkey -- returns the field names of a relation's primary
                   key fields

Synopsis

dblink_get_pkey(text relname) RETURNS setof text

Inputs

  relname
d152 1
a152 157
    any relation name;
    e.g. 'foobar'

Outputs

  Returns setof text -- one row for each primary key field, in order of
                        precedence

Example usage

test=# select dblink_get_pkey('foobar');
 dblink_get_pkey
-----------------
 f1
 f2
 f3
 f4
 f5
(5 rows)


==================================================================
Name

dblink_last_oid -- Returns last inserted oid

Synopsis

dblink_last_oid(int res_id) RETURNS oid

Inputs

  res_id

    any resource id returned by dblink function;

Outputs

  Returns oid of last inserted tuple

Example usage

test=# select dblink_last_oid(dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd'
               ,'insert into mytable (f1, f2) values (1,2)'));

 dblink_last_oid
----------------
 16553
(1 row)


==================================================================
Name

dblink_build_sql_insert -- builds an insert statement using a local
                           tuple, replacing the selection key field
                           values with alternate supplied values
dblink_build_sql_delete -- builds a delete statement using supplied
                           values for selection key field values
dblink_build_sql_update -- builds an update statement using a local
                           tuple, replacing the selection key field
                           values with alternate supplied values


Synopsis

dblink_build_sql_insert(text relname
                         ,int2vector primary_key_attnums
                         ,int2 num_primary_key_atts
                         ,_text src_pk_att_vals_array
                         ,_text tgt_pk_att_vals_array) RETURNS text
dblink_build_sql_delete(text relname
                         ,int2vector primary_key_attnums
                         ,int2 num_primary_key_atts
                         ,_text tgt_pk_att_vals_array) RETURNS text
dblink_build_sql_update(text relname
                         ,int2vector primary_key_attnums
                         ,int2 num_primary_key_atts
                         ,_text src_pk_att_vals_array
                         ,_text tgt_pk_att_vals_array) RETURNS text

Inputs

  relname

    any relation name;
    e.g. 'foobar'

  primary_key_attnums

    vector of primary key attnums (1 based, see pg_index.indkey);
    e.g. '1 2'

  num_primary_key_atts

    number of primary key attnums in the vector; e.g. 2

  src_pk_att_vals_array

    array of primary key values, used to look up the local matching
    tuple, the values of which are then used to construct the SQL
    statement

  tgt_pk_att_vals_array

    array of primary key values, used to replace the local tuple
    values in the SQL statement

Outputs

  Returns text -- requested SQL statement

Example usage

test=# select dblink_build_sql_insert('foo','1 2',2,'{"1", "a"}','{"1", "b''a"}');
             dblink_build_sql_insert
--------------------------------------------------
 INSERT INTO foo(f1,f2,f3) VALUES('1','b''a','1')
(1 row)

test=# select dblink_build_sql_delete('MyFoo','1 2',2,'{"1", "b"}');
           dblink_build_sql_delete
---------------------------------------------
 DELETE FROM "MyFoo" WHERE f1='1' AND f2='b'
(1 row)

test=# select dblink_build_sql_update('foo','1 2',2,'{"1", "a"}','{"1", "b"}');
                   dblink_build_sql_update
-------------------------------------------------------------
 UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b'
(1 row)


==================================================================
Name

dblink_current_query -- returns the current query string

Synopsis

dblink_current_query () RETURNS text

Inputs

  None

Outputs

  Returns text -- a copy of the currently executing query

Example usage

test=# select dblink_current_query() from (select dblink('dbname=template1','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
                                                                dblink_current_query
-----------------------------------------------------------------------------------------------------------------------------------------------------
 select dblink_current_query() from (select dblink('dbname=template1','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
(1 row)
d154 7
a162 39
Name

dblink_replace -- replace all occurences of substring-a in the
                  input-string with substring-b

Synopsis

dblink_replace(text input-string, text substring-a, text substring-b) RETURNS text

Inputs

  input-string

    the starting string, before replacement of substring-a

  substring-a

    the substring to find and replace

  substring-b

    the substring to be substituted in place of substring-a

Outputs

  Returns text -- a copy of the starting string, but with all occurences of
                  substring-a replaced with substring-b

Example usage

test=# select dblink_replace('12345678901234567890','56','hello');
       dblink_replace
----------------------------
 1234hello78901234hello7890
(1 row)

==================================================================


@


1.4
log
@Attached is an update to contrib/dblink. Please apply if there are no
objections.

Major changes:
   - 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

I'm still hoping to add explicit cursor open/fetch/close support before
7.3 is released, but I need a bit more time on that.

On a somewhat unrelated topic, I never got any feedback on the
unknownin/out patch and the mb_substring patch. Is there anything else I
need to do to get those applied?

Joe Conway
@
text
@d68 1
a68 1
     dblink_get_pkey(name) RETURNS setof text
d72 1
a72 1
     dblink_build_sql_insert(name,int2vector,int2,_text,_text) RETURNS text
d75 1
a75 1
     dblink_build_sql_delete(name,int2vector,int2,_text) RETURNS text
d78 1
a78 1
     dblink_build_sql_update(name,int2vector,int2,_text,_text) RETURNS text
d209 1
a209 1
dblink_get_pkey(name relname) RETURNS setof text
d281 1
a281 1
dblink_build_sql_insert(name relname
d286 1
a286 1
dblink_build_sql_delete(name relname
d290 1
a290 1
dblink_build_sql_update(name relname
@


1.3
log
@>>I confirmed the UNION hack is no longer required. Thanks! Is it too late
>>to change the README in contrib/dblink?
>>
>
> No, I don't think that's a problem.  Send a patch.
>

Here's a (documentation only) patch for the contrib/dblink README.

Joe Conway
@
text
@d6 2
a7 1
 * Copyright (c) Joseph Conway <joe.conway@@mail.com>, 2001;
d29 4
a32 3
Version 0.3 (14 June, 2001):
  Function to test returning data set from remote database
  Tested under Linux (Red Hat 6.2 and 7.0) and PostgreSQL 7.1 and 7.2devel
d36 6
d62 24
a85 2
     dblink() - returns a pointer to results from remote query
     dblink_tok() - extracts and returns individual field results
d91 1
a91 1
dblink -- Returns a pointer to a data set from a remote database
d111 1
a111 1
  Returns setof int (pointer)
d127 1
a127 1
dblink_tok(int pointer, int fnumber)
d131 1
a131 1
  pointer
d133 1
a133 1
    a pointer returned by a call to dblink()
d164 249
@


1.2
log
@Here's a small patch for dblink:

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

Joe Conway
@
text
@d85 2
a86 1
  select dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd','select f1, f2 from mytable');
d122 1
a122 2
NOTE: If you need to provide selection criteria in a WHERE clause, it is necessary
to 'fake' a UNION, e.g.
d124 4
a127 31
  select
     dblink_tok(t1.dblink_p,0) as f1
    ,dblink_tok(t1.dblink_p,1) as f2
  from
   (
    select dblink(
                   'hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd'
                  ,'select f1, f2 from mytable'
                 ) as dblink_p
    union all
    select null where false
   ) as t1
  where
    dblink_tok(t1.dblink_p,0) = 'mycriteria';

in order to work around an issue with the query optimizer. A more convenient way to approach
this problem is to create a view:

  create view myremotetable as
  select
     dblink_tok(t1.dblink_p,0) as f1
    ,dblink_tok(t1.dblink_p,1) as f2
  from
   (
    select dblink(
                   'hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd'
                  ,'select f1, f2 from mytable'
                 ) as dblink_p
    union all
    select null where false
   ) as t1;
d131 1
a131 1
   select f1,f2 from myremotetable where f1 = 'mycriteria';
@


1.1
log
@Allow remote query execution (dblink)

Joe Conway
@
text
@d27 2
a28 1
Version 0.2 (29 May, 2001):
d34 5
d133 2
a134 2
    union
    select null,null where false
d137 1
a137 1
    f1 = 'mycriteria';
d152 2
a153 2
    union
    select null,null where false
@
