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