/* * dblink * * Functions returning results from a remote database * * Joe Conway * And contributors: * Darko Prenosil * Shridhar Daithankar * * 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