mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-22 05:13:22 +02:00
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.
174 lines
7.4 KiB
Plaintext
174 lines
7.4 KiB
Plaintext
/*
|
|
* 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-2003, 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
|
|
|