head	1.6;
access;
symbols
	REL7_4_29:1.2
	REL8_0_25:1.3
	REL8_1_21:1.4
	REL8_2_17:1.5
	REL7_4_28:1.2
	REL8_0_24:1.3
	REL8_1_20:1.4
	REL8_2_16:1.5
	REL7_4_27:1.2
	REL8_0_23:1.3
	REL8_1_19:1.4
	REL8_2_15:1.5
	REL7_4_26:1.2
	REL8_0_22:1.3
	REL8_1_18:1.4
	REL8_2_14:1.5
	REL7_4_25:1.2
	REL8_0_21:1.3
	REL8_1_17:1.4
	REL8_2_13:1.5
	REL7_4_24:1.2
	REL8_0_20:1.3
	REL8_1_16:1.4
	REL8_2_12:1.5
	REL7_4_23:1.2
	REL8_0_19:1.3
	REL8_1_15:1.4
	REL8_2_11:1.5
	REL7_4_22:1.2
	REL8_0_18:1.3
	REL8_1_14:1.4
	REL8_2_10:1.5
	REL7_4_21:1.2
	REL8_0_17:1.3
	REL8_1_13:1.4
	REL8_2_9:1.5
	REL7_4_20:1.2
	REL8_0_16:1.3
	REL8_1_12:1.4
	REL8_2_8:1.5
	REL8_2_7:1.5
	REL7_3_21:1.1
	REL7_4_19:1.2
	REL8_0_15:1.3
	REL8_1_11:1.4
	REL8_2_6:1.5
	REL8_3_BETA2:1.5
	REL8_3_BETA1:1.5
	REL7_3_20:1.1
	REL7_4_18:1.2
	REL8_0_14:1.3
	REL8_1_10:1.4
	REL8_2_5:1.5
	REL7_3_19:1.1
	REL7_4_17:1.2
	REL8_0_13:1.3
	REL8_1_9:1.4
	REL8_2_4:1.5
	REL8_0_12:1.3
	REL8_1_8:1.4
	REL8_2_3:1.5
	REL7_3_18:1.1
	REL7_4_16:1.2
	REL8_0_11:1.3
	REL8_1_7:1.4
	REL8_2_2:1.5
	REL8_0_10:1.3
	REL8_1_6:1.4
	REL8_2_1:1.5
	REL7_4_15:1.2
	REL7_3_17:1.1
	REL8_2_STABLE:1.5.0.2
	REL8_2_0:1.5
	REL8_2_RC1:1.5
	REL8_2_BETA3:1.5
	REL8_2_BETA2:1.5
	REL8_1_5:1.4
	REL8_0_9:1.3
	REL7_4_14:1.2
	REL7_3_16:1.1
	REL8_2_BETA1:1.5
	REL7_3_15:1.1
	REL7_4_13:1.2
	REL8_0_8:1.3
	REL8_1_4:1.4
	REL7_3_14:1.1
	REL7_4_12:1.2
	REL8_0_7:1.3
	REL8_1_3:1.4
	REL7_3_13:1.1
	REL7_4_11:1.2
	REL8_0_6:1.3
	REL8_1_2:1.4
	REL7_3_12:1.1
	REL7_4_10:1.2
	REL8_0_5:1.3
	REL8_1_1:1.4
	REL8_1_STABLE:1.4.0.2
	REL8_1_0:1.4
	REL8_1_0RC1:1.4
	REL8_1_0BETA4:1.4
	REL8_1_0BETA3:1.4
	REL7_3_11:1.1
	REL7_4_9:1.2
	REL8_0_4:1.3
	REL8_1_0BETA2:1.4
	REL8_1_0BETA1:1.4
	REL7_3_10:1.1
	REL7_4_8:1.2
	REL8_0_3:1.3
	REL8_0_2:1.3
	REL7_3_9:1.1
	REL7_4_7:1.2
	REL8_0_1:1.3
	REL8_0_STABLE:1.3.0.4
	REL8_0_0:1.3.0.2
	REL8_0_0RC5:1.3
	REL8_0_0RC4:1.3
	REL8_0_0RC3:1.3
	REL8_0_0RC2:1.3
	REL8_0_0RC1:1.3
	REL8_0_0BETA5:1.3
	REL8_0_0BETA4:1.3
	REL7_4_6:1.2
	REL7_3_8:1.1
	REL8_0_0BETA3:1.3
	REL8_0_0BETA2:1.3
	REL7_4_5:1.2
	REL7_3_7:1.1
	REL7_4_4:1.2
	REL8_0_0BETA1:1.3
	REL7_4_3:1.2
	REL7_4_2:1.2
	REL7_3_6:1.1
	REL7_4_1:1.2
	REL7_3_5:1.1
	REL7_4:1.2
	REL7_4_RC2:1.2
	REL7_4_STABLE:1.2.0.4
	REL7_4_RC1:1.2
	REL7_4_BETA5:1.2
	REL7_4_BETA4:1.2
	REL7_4_BETA3:1.2
	REL7_4_BETA2:1.2
	WIN32_DEV:1.2.0.2
	REL7_4_BETA1:1.2
	REL7_3_4:1.1
	REL7_3_2:1.1
	REL7_3_STABLE:1.1.0.2;
locks; strict;
comment	@# @;


1.6
date	2007.11.11.05.13.09;	author momjian;	state dead;
branches;
next	1.5;

1.5
date	2006.09.02.21.11.15;	author joe;	state Exp;
branches;
next	1.4;

1.4
date	2005.06.21.04.02.28;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2004.03.07.02.27.00;	author joe;	state Exp;
branches;
next	1.2;

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

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


desc
@@


1.6
log
@Remove /contrib/dblink/doc directory, now in SGML.
@
text
@==================================================================
Name

dblink -- Returns a set from a remote database

Synopsis

dblink(text connstr, text sql [, bool fail_on_error])
dblink(text connname, text sql [, bool fail_on_error])
dblink(text sql [, bool fail_on_error])

Inputs

  connname
  connstr
    If two arguments are present, the first is first assumed to be a specific
    connection name to use. If the name is not found, the argument is then
    assumed to be a valid connection string, of standard libpq format,
    e.g.: "hostaddr=127.0.0.1 dbname=mydb user=postgres password=mypasswd"

    If only one argument is used, then the unnamed connection is used.

  sql

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

  fail_on_error

    If true (default when not present) then an ERROR thrown on the remote side
    of the connection causes an ERROR to also be thrown locally. If false, the
    remote ERROR is locally treated as a NOTICE, and no rows are returned.

Outputs

  Returns setof record

Example usage

select * from dblink('dbname=postgres','select proname, prosrc from pg_proc')
 as t1(proname name, prosrc text) where proname like 'bytea%';
  proname   |   prosrc
------------+------------
 byteacat   | byteacat
 byteaeq    | byteaeq
 bytealt    | bytealt
 byteale    | byteale
 byteagt    | byteagt
 byteage    | byteage
 byteane    | byteane
 byteacmp   | byteacmp
 bytealike  | bytealike
 byteanlike | byteanlike
 byteain    | byteain
 byteaout   | byteaout
(12 rows)

select dblink_connect('dbname=postgres');
 dblink_connect
----------------
 OK
(1 row)

select * from dblink('select proname, prosrc from pg_proc')
 as t1(proname name, prosrc text) where proname like 'bytea%';
  proname   |   prosrc
------------+------------
 byteacat   | byteacat
 byteaeq    | byteaeq
 bytealt    | bytealt
 byteale    | byteale
 byteagt    | byteagt
 byteage    | byteage
 byteane    | byteane
 byteacmp   | byteacmp
 bytealike  | bytealike
 byteanlike | byteanlike
 byteain    | byteain
 byteaout   | byteaout
(12 rows)

select dblink_connect('myconn','dbname=regression');
 dblink_connect
----------------
 OK
(1 row)

select * from dblink('myconn','select proname, prosrc from pg_proc')
 as t1(proname name, prosrc text) where proname like 'bytea%';
  proname   |   prosrc
------------+------------
 bytearecv  | bytearecv
 byteasend  | byteasend
 byteale    | byteale
 byteagt    | byteagt
 byteage    | byteage
 byteane    | byteane
 byteacmp   | byteacmp
 bytealike  | bytealike
 byteanlike | byteanlike
 byteacat   | byteacat
 byteaeq    | byteaeq
 bytealt    | bytealt
 byteain    | byteain
 byteaout   | byteaout
(14 rows)


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

 create view myremote_pg_proc as
 select *
 from dblink('dbname=postgres','select proname, prosrc from pg_proc')
 as t1(proname name, prosrc text);

Then you can simply write:

   select * from myremote_pg_proc where proname like 'bytea%';


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

dblink_send_query -- Sends an async query to a remote database

Synopsis

dblink_send_query(text connname, text sql)

Inputs

  connname
    The specific connection name to use.

  sql

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

Outputs

  Returns int. A return value of 1 if the query was successfully dispatched,
  0 otherwise. If 1, results must be fetched by dblink_get_result(connname).
  A running query may be cancelled by dblink_cancel_query(connname).

Example usage

  SELECT dblink_connect('dtest1', 'dbname=contrib_regression');
  SELECT * from 
   dblink_send_query('dtest1', 'select * from foo where f1 < 3') as t1;

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

dblink_get_result -- Gets an async query result

Synopsis

dblink_get_result(text connname [, bool fail_on_error])

Inputs

  connname
    The specific connection name to use. An asynchronous query must
    have already been sent using dblink_send_query()

  fail_on_error

    If true (default when not present) then an ERROR thrown on the remote side
    of the connection causes an ERROR to also be thrown locally. If false, the
    remote ERROR is locally treated as a NOTICE, and no rows are returned.

Outputs

  Returns setof record

Notes
  Blocks until a result gets available.

  This function *must* be called if dblink_send_query returned
  a 1, even on cancelled queries - otherwise the connection
  can't be used anymore. It must be called once for each query
  sent, and one additional time to obtain an empty set result,
  prior to using the connection again.

Example usage

contrib_regression=#   SELECT dblink_connect('dtest1', 'dbname=contrib_regression');
 dblink_connect
----------------
 OK
(1 row)

contrib_regression=#   SELECT * from
contrib_regression-#    dblink_send_query('dtest1', 'select * from foo where f1 < 3') as t1;
 t1
----
  1
(1 row)

contrib_regression=#   SELECT * from dblink_get_result('dtest1') as t1(f1 int, f2 text, f3 text[]);
 f1 | f2 |     f3
----+----+------------
  0 | a  | {a0,b0,c0}
  1 | b  | {a1,b1,c1}
  2 | c  | {a2,b2,c2}
(3 rows)

contrib_regression=#   SELECT * from dblink_get_result('dtest1') as t1(f1 int, f2 text, f3 text[]);
 f1 | f2 | f3
----+----+----
(0 rows)

contrib_regression=#   SELECT * from
   dblink_send_query('dtest1', 'select * from foo where f1 < 3; select * from foo where f1 > 6') as t1;
 t1
----
  1
(1 row)

contrib_regression=#   SELECT * from dblink_get_result('dtest1') as t1(f1 int, f2 text, f3 text[]);
 f1 | f2 |     f3
----+----+------------
  0 | a  | {a0,b0,c0}
  1 | b  | {a1,b1,c1}
  2 | c  | {a2,b2,c2}
(3 rows)

contrib_regression=#   SELECT * from dblink_get_result('dtest1') as t1(f1 int, f2 text, f3 text[]);
 f1 | f2 |      f3
----+----+---------------
  7 | h  | {a7,b7,c7}
  8 | i  | {a8,b8,c8}
  9 | j  | {a9,b9,c9}
 10 | k  | {a10,b10,c10}
(4 rows)

contrib_regression=#   SELECT * from dblink_get_result('dtest1') as t1(f1 int, f2 text, f3 text[]);
 f1 | f2 | f3
----+----+----
(0 rows)
@


1.5
log
@Added async query capability. Original patch by
Kai Londenberg, modified by Joe Conway
@
text
@@


1.4
log
@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.
@
text
@d121 122
@


1.3
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
@d40 1
a40 1
select * from dblink('dbname=template1','select proname, prosrc from pg_proc')
d58 1
a58 1
select dblink_connect('dbname=template1');
d114 1
a114 1
 from dblink('dbname=template1','select proname, prosrc from pg_proc')
@


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

Shridhar Daithanka
@
text
@d8 3
a10 3
dblink(text connstr, text sql)
dblink(text connname, text sql)
dblink(text sql)
d27 6
@


1.1
log
@Add missing dblink files.
@
text
@d9 1
a9 1
- or -
d14 1
d16 4
d21 1
a21 4
    standard libpq format connection string, 
    e.g. "hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd"
    If the second form is used, then the dblink_connect(text connstr) must be
    executed first.
d34 1
a34 1
test=# select * from dblink('dbname=template1','select proname, prosrc from pg_proc')
d52 1
a52 1
test=# select dblink_connect('dbname=template1');
d58 1
a58 1
test=# select * from dblink('select proname, prosrc from pg_proc')
d75 27
@

