mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-02 17:01:20 +02:00
f4095b4c4b
Adds the ability to retrieve async notifications using dblink, via the addition of the function dblink_get_notify(). Original patch by Marcus Kempe, suggestions by Tom Lane and Alvaro Herrera, patch review and adjustments by Joe Conway.
1958 lines
52 KiB
Plaintext
1958 lines
52 KiB
Plaintext
<!-- $PostgreSQL: pgsql/doc/src/sgml/dblink.sgml,v 1.9 2009/08/05 16:11:07 joe Exp $ -->
|
|
|
|
<sect1 id="dblink">
|
|
<title>dblink</title>
|
|
|
|
<indexterm zone="dblink">
|
|
<primary>dblink</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<filename>dblink</> is a module which supports connections to
|
|
other <productname>PostgreSQL</> databases from within a database
|
|
session.
|
|
</para>
|
|
|
|
<refentry id="CONTRIB-DBLINK-CONNECT">
|
|
<refmeta>
|
|
<refentrytitle>dblink_connect</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_connect</refname>
|
|
<refpurpose>opens a persistent connection to a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_connect(text connstr) returns text
|
|
dblink_connect(text connname, text connstr) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_connect()</> establishes a connection to a remote
|
|
<productname>PostgreSQL</> database. The server and database to
|
|
be contacted are identified through a standard <application>libpq</>
|
|
connection string. Optionally, a name can be assigned to the
|
|
connection. Multiple named connections can be open at once, but
|
|
only one unnamed connection is permitted at a time. The connection
|
|
will persist until closed or until the database session is ended.
|
|
</para>
|
|
|
|
<para>
|
|
The connection string may also be the name of an existing foreign
|
|
server. It is recommended to use
|
|
the <function>postgresql_fdw_validator</function> when defining
|
|
the corresponding foreign-data wrapper. See the example below, as
|
|
well as the following:
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-createforeigndatawrapper" endterm="sql-createforeigndatawrapper-title"></member>
|
|
<member><xref linkend="sql-createserver" endterm="sql-createserver-title"></member>
|
|
<member><xref linkend="sql-createusermapping" endterm="sql-createusermapping-title"></member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name to use for this connection; if omitted, an unnamed
|
|
connection is opened, replacing any existing unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>connstr</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
<application>libpq</>-style connection info string, for example
|
|
<literal>hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres
|
|
password=mypasswd</>.
|
|
For details see <function>PQconnectdb</> in
|
|
<xref linkend="libpq-connect">.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns status, which is always <literal>OK</> (since any error
|
|
causes the function to throw an error instead of returning).
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
Only superusers may use <function>dblink_connect</> to create
|
|
non-password-authenticated connections. If non-superusers need this
|
|
capability, use <function>dblink_connect_u</> instead.
|
|
</para>
|
|
|
|
<para>
|
|
It is unwise to choose connection names that contain equal signs,
|
|
as this opens a risk of confusion with connection info strings
|
|
in other <filename>dblink</> functions.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_connect('myconn', 'dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
-- FOREIGN DATA WRAPPER functionality
|
|
-- Note: local connection must require password authentication for this to work properly
|
|
-- Otherwise, you will receive the following error from dblink_connect():
|
|
-- ----------------------------------------------------------------------
|
|
-- ERROR: password is required
|
|
-- DETAIL: Non-superuser cannot connect if the server does not request a password.
|
|
-- HINT: Target server's authentication method must be changed.
|
|
CREATE USER dblink_regression_test WITH PASSWORD 'secret';
|
|
CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
|
|
CREATE SERVER fdtest FOREIGN DATA WRAPPER postgresql OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression');
|
|
|
|
CREATE USER MAPPING FOR dblink_regression_test SERVER fdtest OPTIONS (user 'dblink_regression_test', password 'secret');
|
|
GRANT USAGE ON FOREIGN SERVER fdtest TO dblink_regression_test;
|
|
GRANT SELECT ON TABLE foo TO dblink_regression_test;
|
|
|
|
\set ORIGINAL_USER :USER
|
|
\c - dblink_regression_test
|
|
SELECT dblink_connect('myconn', 'fdtest');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
SELECT * FROM dblink('myconn','SELECT * FROM foo') AS t(a int, b text, c text[]);
|
|
a | b | c
|
|
----+---+---------------
|
|
0 | a | {a0,b0,c0}
|
|
1 | b | {a1,b1,c1}
|
|
2 | c | {a2,b2,c2}
|
|
3 | d | {a3,b3,c3}
|
|
4 | e | {a4,b4,c4}
|
|
5 | f | {a5,b5,c5}
|
|
6 | g | {a6,b6,c6}
|
|
7 | h | {a7,b7,c7}
|
|
8 | i | {a8,b8,c8}
|
|
9 | j | {a9,b9,c9}
|
|
10 | k | {a10,b10,c10}
|
|
(11 rows)
|
|
|
|
\c - :ORIGINAL_USER
|
|
REVOKE USAGE ON FOREIGN SERVER fdtest FROM dblink_regression_test;
|
|
REVOKE SELECT ON TABLE foo FROM dblink_regression_test;
|
|
DROP USER MAPPING FOR dblink_regression_test SERVER fdtest;
|
|
DROP USER dblink_regression_test;
|
|
DROP SERVER fdtest;
|
|
DROP FOREIGN DATA WRAPPER postgresql;
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-CONNECT-U">
|
|
<refmeta>
|
|
<refentrytitle>dblink_connect_u</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_connect_u</refname>
|
|
<refpurpose>opens a persistent connection to a remote database, insecurely</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_connect_u(text connstr) returns text
|
|
dblink_connect_u(text connname, text connstr) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_connect_u()</> is identical to
|
|
<function>dblink_connect()</>, except that it will allow non-superusers
|
|
to connect using any authentication method.
|
|
</para>
|
|
|
|
<para>
|
|
If the remote server selects an authentication method that does not
|
|
involve a password, then impersonation and subsequent escalation of
|
|
privileges can occur, because the session will appear to have
|
|
originated from the user as which the local <productname>PostgreSQL</>
|
|
server runs. Also, even if the remote server does demand a password,
|
|
it is possible for the password to be supplied from the server
|
|
environment, such as a <filename>~/.pgpass</> file belonging to the
|
|
server's user. This opens not only a risk of impersonation, but the
|
|
possibility of exposing a password to an untrustworthy remote server.
|
|
Therefore, <function>dblink_connect_u()</> is initially
|
|
installed with all privileges revoked from <literal>PUBLIC</>,
|
|
making it un-callable except by superusers. In some situations
|
|
it may be appropriate to grant <literal>EXECUTE</> permission for
|
|
<function>dblink_connect_u()</> to specific users who are considered
|
|
trustworthy, but this should be done with care. It is also recommended
|
|
that any <filename>~/.pgpass</> file belonging to the server's user
|
|
<emphasis>not</> contain any records specifying a wildcard host name.
|
|
</para>
|
|
|
|
<para>
|
|
For further details see <function>dblink_connect()</>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-DISCONNECT">
|
|
<refmeta>
|
|
<refentrytitle>dblink_disconnect</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_disconnect</refname>
|
|
<refpurpose>closes a persistent connection to a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_disconnect() returns text
|
|
dblink_disconnect(text connname) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_disconnect()</> closes a connection previously opened
|
|
by <function>dblink_connect()</>. The form with no arguments closes
|
|
an unnamed connection.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a named connection to be closed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns status, which is always <literal>OK</> (since any error
|
|
causes the function to throw an error instead of returning).
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# select dblink_disconnect();
|
|
dblink_disconnect
|
|
-------------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_disconnect('myconn');
|
|
dblink_disconnect
|
|
-------------------
|
|
OK
|
|
(1 row)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK">
|
|
<refmeta>
|
|
<refentrytitle>dblink</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink</refname>
|
|
<refpurpose>executes a query in a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink(text connname, text sql [, bool fail_on_error]) returns setof record
|
|
dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
|
|
dblink(text sql [, bool fail_on_error]) returns setof record
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink</> executes a query (usually a <command>SELECT</>,
|
|
but it can be any SQL statement that returns rows) in a remote database.
|
|
</para>
|
|
|
|
<para>
|
|
When two <type>text</> arguments are given, the first one is first
|
|
looked up as a persistent connection's name; if found, the command
|
|
is executed on that connection. If not found, the first argument
|
|
is treated as a connection info string as for <function>dblink_connect</>,
|
|
and the indicated connection is made just for the duration of this command.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use; omit this parameter to use the
|
|
unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>connstr</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
A connection info string, as previously described for
|
|
<function>dblink_connect</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>sql</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The SQL query that you wish to execute in the remote database,
|
|
for example <literal>select * from foo</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function returns no rows.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
The function returns the row(s) produced by the query. Since
|
|
<function>dblink</> can be used with any query, it is declared
|
|
to return <type>record</>, rather than specifying any particular
|
|
set of columns. This means that you must specify the expected
|
|
set of columns in the calling query — otherwise
|
|
<productname>PostgreSQL</> would not know what to expect.
|
|
Here is an example:
|
|
|
|
<programlisting>
|
|
SELECT *
|
|
FROM dblink('dbname=mydb', 'select proname, prosrc from pg_proc')
|
|
AS t1(proname name, prosrc text)
|
|
WHERE proname LIKE 'bytea%';
|
|
</programlisting>
|
|
|
|
The <quote>alias</> part of the <literal>FROM</> clause must
|
|
specify the column names and types that the function will return.
|
|
(Specifying column names in an alias is actually standard SQL
|
|
syntax, but specifying column types is a <productname>PostgreSQL</>
|
|
extension.) This allows the system to understand what
|
|
<literal>*</> should expand to, and what <structname>proname</>
|
|
in the <literal>WHERE</> clause refers to, in advance of trying
|
|
to execute the function. At runtime, an error will be thrown
|
|
if the actual query result from the remote database does not
|
|
have the same number of columns shown in the <literal>FROM</> clause.
|
|
The column names need not match, however, and <function>dblink</>
|
|
does not insist on exact type matches either. It will succeed
|
|
so long as the returned data strings are valid input for the
|
|
column type declared in the <literal>FROM</> clause.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
<function>dblink</> fetches the entire remote query result before
|
|
returning any of it to the local system. If the query is expected
|
|
to return a large number of rows, it's better to open it as a cursor
|
|
with <function>dblink_open</> and then fetch a manageable number
|
|
of rows at a time.
|
|
</para>
|
|
|
|
<para>
|
|
A convenient way to use <function>dblink</> with predetermined
|
|
queries is to create a view.
|
|
This allows the column type information to be buried in the view,
|
|
instead of having to spell it out in every query. For example,
|
|
|
|
<programlisting>
|
|
create view myremote_pg_proc as
|
|
select *
|
|
from dblink('dbname=postgres', 'select proname, prosrc from pg_proc')
|
|
as t1(proname name, prosrc text);
|
|
|
|
select * from myremote_pg_proc where proname like 'bytea%';
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
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)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-EXEC">
|
|
<refmeta>
|
|
<refentrytitle>dblink_exec</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_exec</refname>
|
|
<refpurpose>executes a command in a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
|
|
dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
|
|
dblink_exec(text sql [, bool fail_on_error]) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_exec</> executes a command (that is, any SQL statement
|
|
that doesn't return rows) in a remote database.
|
|
</para>
|
|
|
|
<para>
|
|
When two <type>text</> arguments are given, the first one is first
|
|
looked up as a persistent connection's name; if found, the command
|
|
is executed on that connection. If not found, the first argument
|
|
is treated as a connection info string as for <function>dblink_connect</>,
|
|
and the indicated connection is made just for the duration of this command.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use; omit this parameter to use the
|
|
unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>connstr</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
A connection info string, as previously described for
|
|
<function>dblink_connect</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>sql</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The SQL command that you wish to execute in the remote database,
|
|
for example
|
|
<literal>insert into foo values(0,'a','{"a0","b0","c0"}')</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function's return value is set to <literal>ERROR</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns status, either the command's status string or <literal>ERROR</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
select dblink_connect('dbname=dblink_test_slave');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_exec('insert into foo values(21,''z'',''{"a0","b0","c0"}'');');
|
|
dblink_exec
|
|
-----------------
|
|
INSERT 943366 1
|
|
(1 row)
|
|
|
|
select dblink_connect('myconn', 'dbname=regression');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_exec('myconn', 'insert into foo values(21,''z'',''{"a0","b0","c0"}'');');
|
|
dblink_exec
|
|
------------------
|
|
INSERT 6432584 1
|
|
(1 row)
|
|
|
|
select dblink_exec('myconn', 'insert into pg_class values (''foo'')',false);
|
|
NOTICE: sql error
|
|
DETAIL: ERROR: null value in column "relnamespace" violates not-null constraint
|
|
|
|
dblink_exec
|
|
-------------
|
|
ERROR
|
|
(1 row)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-OPEN">
|
|
<refmeta>
|
|
<refentrytitle>dblink_open</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_open</refname>
|
|
<refpurpose>opens a cursor in a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text
|
|
dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_open()</> opens a cursor in a remote database.
|
|
The cursor can subsequently be manipulated with
|
|
<function>dblink_fetch()</> and <function>dblink_close()</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use; omit this parameter to use the
|
|
unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>cursorname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name to assign to this cursor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>sql</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The <command>SELECT</> statement that you wish to execute in the remote
|
|
database, for example <literal>select * from pg_class</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function's return value is set to <literal>ERROR</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns status, either <literal>OK</> or <literal>ERROR</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
Since a cursor can only persist within a transaction,
|
|
<function>dblink_open</> starts an explicit transaction block
|
|
(<command>BEGIN</>) on the remote side, if the remote side was
|
|
not already within a transaction. This transaction will be
|
|
closed again when the matching <function>dblink_close</> is
|
|
executed. Note that if
|
|
you use <function>dblink_exec</> to change data between
|
|
<function>dblink_open</> and <function>dblink_close</>,
|
|
and then an error occurs or you use <function>dblink_disconnect</> before
|
|
<function>dblink_close</>, your change <emphasis>will be
|
|
lost</> because the transaction will be aborted.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo', 'select proname, prosrc from pg_proc');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-FETCH">
|
|
<refmeta>
|
|
<refentrytitle>dblink_fetch</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_fetch</refname>
|
|
<refpurpose>returns rows from an open cursor in a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
|
|
dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_fetch</> fetches rows from a cursor previously
|
|
established by <function>dblink_open</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use; omit this parameter to use the
|
|
unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>cursorname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the cursor to fetch from.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>howmany</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The maximum number of rows to retrieve. The next <parameter>howmany</>
|
|
rows are fetched, starting at the current cursor position, moving
|
|
forward. Once the cursor has reached its end, no more rows are produced.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function returns no rows.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
The function returns the row(s) fetched from the cursor. To use this
|
|
function, you will need to specify the expected set of columns,
|
|
as previously discussed for <function>dblink</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
On a mismatch between the number of return columns specified in the
|
|
<literal>FROM</> clause, and the actual number of columns returned by the
|
|
remote cursor, an error will be thrown. In this event, the remote cursor
|
|
is still advanced by as many rows as it would have been if the error had
|
|
not occurred. The same is true for any other error occurring in the local
|
|
query after the remote <command>FETCH</> has been done.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%''');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select * from dblink_fetch('foo', 5) as (funcname name, source text);
|
|
funcname | source
|
|
----------+----------
|
|
byteacat | byteacat
|
|
byteacmp | byteacmp
|
|
byteaeq | byteaeq
|
|
byteage | byteage
|
|
byteagt | byteagt
|
|
(5 rows)
|
|
|
|
test=# select * from dblink_fetch('foo', 5) as (funcname name, source text);
|
|
funcname | source
|
|
-----------+-----------
|
|
byteain | byteain
|
|
byteale | byteale
|
|
bytealike | bytealike
|
|
bytealt | bytealt
|
|
byteane | byteane
|
|
(5 rows)
|
|
|
|
test=# select * from dblink_fetch('foo', 5) as (funcname name, source text);
|
|
funcname | source
|
|
------------+------------
|
|
byteanlike | byteanlike
|
|
byteaout | byteaout
|
|
(2 rows)
|
|
|
|
test=# select * from dblink_fetch('foo', 5) as (funcname name, source text);
|
|
funcname | source
|
|
----------+--------
|
|
(0 rows)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-CLOSE">
|
|
<refmeta>
|
|
<refentrytitle>dblink_close</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_close</refname>
|
|
<refpurpose>closes a cursor in a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_close(text cursorname [, bool fail_on_error]) returns text
|
|
dblink_close(text connname, text cursorname [, bool fail_on_error]) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_close</> closes a cursor previously opened with
|
|
<function>dblink_open</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use; omit this parameter to use the
|
|
unnamed connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>cursorname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the cursor to close.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function's return value is set to <literal>ERROR</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns status, either <literal>OK</> or <literal>ERROR</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
If <function>dblink_open</> started an explicit transaction block,
|
|
and this is the last remaining open cursor in this connection,
|
|
<function>dblink_close</> will issue the matching <command>COMMIT</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo', 'select proname, prosrc from pg_proc');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_close('foo');
|
|
dblink_close
|
|
--------------
|
|
OK
|
|
(1 row)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-GET-CONNECTIONS">
|
|
<refmeta>
|
|
<refentrytitle>dblink_get_connections</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_get_connections</refname>
|
|
<refpurpose>returns the names of all open named dblink connections</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_get_connections() returns text[]
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_get_connections</> returns an array of the names
|
|
of all open named <filename>dblink</> connections.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>Returns a text array of connection names, or NULL if none.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
SELECT dblink_get_connections();
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-ERROR-MESSAGE">
|
|
<refmeta>
|
|
<refentrytitle>dblink_error_message</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_error_message</refname>
|
|
<refpurpose>gets last error message on the named connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_error_message(text connname) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_error_message</> fetches the most recent remote
|
|
error message for a given connection.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns last error message, or an empty string if there has been
|
|
no error in this connection.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
SELECT dblink_error_message('dtest1');
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-SEND-QUERY">
|
|
<refmeta>
|
|
<refentrytitle>dblink_send_query</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_send_query</refname>
|
|
<refpurpose>sends an async query to a remote database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_send_query(text connname, text sql) returns int
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_send_query</> sends a query to be executed
|
|
asynchronously, that is, without immediately waiting for the result.
|
|
There must not be an async query already in progress on the
|
|
connection.
|
|
</para>
|
|
|
|
<para>
|
|
After successfully dispatching an async query, completion status
|
|
can be checked with <function>dblink_is_busy</>, and the results
|
|
are ultimately collected with <function>dblink_get_result</>.
|
|
It is also possible to attempt to cancel an active async query
|
|
using <function>dblink_cancel_query</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>sql</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The SQL statement that you wish to execute in the remote database,
|
|
for example <literal>select * from pg_class</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns 1 if the query was successfully dispatched, 0 otherwise.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
SELECT dblink_send_query('dtest1', 'SELECT * FROM foo WHERE f1 < 3');
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-IS-BUSY">
|
|
<refmeta>
|
|
<refentrytitle>dblink_is_busy</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_is_busy</refname>
|
|
<refpurpose>checks if connection is busy with an async query</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_is_busy(text connname) returns int
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_is_busy</> tests whether an async query is in progress.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to check.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns 1 if connection is busy, 0 if it is not busy.
|
|
If this function returns 0, it is guaranteed that
|
|
<function>dblink_get_result</> will not block.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
SELECT dblink_is_busy('dtest1');
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-GET-NOTIFY">
|
|
<refnamediv>
|
|
<refname>dblink_get_notify</refname>
|
|
<refpurpose>retrieve async notifications on a connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_get_notify() returns setof (notify_name text, be_pid int, extra text)
|
|
dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, extra text)
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_get_notify</> retrieves notifications on either
|
|
the unnamed connection, or on a named connection if specified.
|
|
To receive notifications via dblink, <function>LISTEN</> must
|
|
first be issued, using <function>dblink_exec</>.
|
|
For details see <xref linkend="sql-listen"> and <xref linkend="sql-notify">.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a named connection to get notifications on.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
<para>Returns setof (notify_name text, be_pid int, extra text), or an empty set if none.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# SELECT dblink_exec('LISTEN virtual');
|
|
dblink_exec
|
|
-------------
|
|
LISTEN
|
|
(1 row)
|
|
|
|
test=# SELECT * FROM dblink_get_notify();
|
|
notify_name | be_pid | extra
|
|
-------------+--------+-------
|
|
(0 rows)
|
|
|
|
test=# NOTIFY virtual;
|
|
NOTIFY
|
|
|
|
SELECT * FROM dblink_get_notify();
|
|
notify_name | be_pid | extra
|
|
-------------+--------+-------
|
|
virtual | 1229 |
|
|
(1 row)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-GET-RESULT">
|
|
<refmeta>
|
|
<refentrytitle>dblink_get_result</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_get_result</refname>
|
|
<refpurpose>gets an async query result</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_get_result(text connname [, bool fail_on_error]) returns setof record
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_get_result</> collects the results of an
|
|
asynchronous query previously sent with <function>dblink_send_query</>.
|
|
If the query is not already completed, <function>dblink_get_result</>
|
|
will wait until it is.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>fail_on_error</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If true (the default when omitted) 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 reported as a NOTICE,
|
|
and the function returns no rows.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
For an async query (that is, a SQL statement returning rows),
|
|
the function returns the row(s) produced by the query. To use this
|
|
function, you will need to specify the expected set of columns,
|
|
as previously discussed for <function>dblink</>.
|
|
</para>
|
|
|
|
<para>
|
|
For an async command (that is, a SQL statement not returning rows),
|
|
the function returns a single row with a single text column containing
|
|
the command's status string. It is still necessary to specify that
|
|
the result will have a single text column in the calling <literal>FROM</>
|
|
clause.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
This function <emphasis>must</> be called if
|
|
<function>dblink_send_query</> returned 1.
|
|
It must be called once for each query
|
|
sent, and one additional time to obtain an empty set result,
|
|
before the connection can be used again.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
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)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-CANCEL-QUERY">
|
|
<refmeta>
|
|
<refentrytitle>dblink_cancel_query</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_cancel_query</refname>
|
|
<refpurpose>cancels any active query on the named connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_cancel_query(text connname) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_cancel_query</> attempts to cancel any query that
|
|
is in progress on the named connection. Note that this is not
|
|
certain to succeed (since, for example, the remote query might
|
|
already have finished). A cancel request simply improves the
|
|
odds that the query will fail soon. You must still complete the
|
|
normal query protocol, for example by calling
|
|
<function>dblink_get_result</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>conname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the connection to use.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns <literal>OK</> if the cancel request has been sent, or
|
|
the text of an error message on failure.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
SELECT dblink_cancel_query('dtest1');
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-GET-PKEY">
|
|
<refmeta>
|
|
<refentrytitle>dblink_get_pkey</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_get_pkey</refname>
|
|
<refpurpose>returns the positions and field names of a relation's
|
|
primary key fields
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_get_pkey(text relname) returns setof dblink_pkey_results
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_get_pkey</> provides information about the primary
|
|
key of a relation in the local database. This is sometimes useful
|
|
in generating queries to be sent to remote databases.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>relname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of a local relation, for example <literal>foo</> or
|
|
<literal>myschema.mytab</>. Include double quotes if the
|
|
name is mixed-case or contains special characters, for
|
|
example <literal>"FooBar"</>; without quotes, the string
|
|
will be folded to lower case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns one row for each primary key field, or no rows if the relation
|
|
has no primary key. The result rowtype is defined as
|
|
|
|
<programlisting>
|
|
CREATE TYPE dblink_pkey_results AS (position int, colname text);
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
test=# create table foobar(f1 int, f2 int, f3 int,
|
|
test(# primary key(f1,f2,f3));
|
|
CREATE TABLE
|
|
test=# select * from dblink_get_pkey('foobar');
|
|
position | colname
|
|
----------+---------
|
|
1 | f1
|
|
2 | f2
|
|
3 | f3
|
|
(3 rows)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-BUILD-SQL-INSERT">
|
|
<refmeta>
|
|
<refentrytitle>dblink_build_sql_insert</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_build_sql_insert</refname>
|
|
<refpurpose>
|
|
builds an INSERT statement using a local tuple, replacing the
|
|
primary key field values with alternative supplied values
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<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
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_build_sql_insert</> can be useful in doing selective
|
|
replication of a local table to a remote database. It selects a row
|
|
from the local table based on primary key, and then builds a SQL
|
|
<command>INSERT</> command that will duplicate that row, but with
|
|
the primary key values replaced by the values in the last argument.
|
|
(To make an exact copy of the row, just specify the same values for
|
|
the last two arguments.)
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>relname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of a local relation, for example <literal>foo</> or
|
|
<literal>myschema.mytab</>. Include double quotes if the
|
|
name is mixed-case or contains special characters, for
|
|
example <literal>"FooBar"</>; without quotes, the string
|
|
will be folded to lower case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>primary_key_attnums</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Attribute numbers (1-based) of the primary key fields,
|
|
for example <literal>1 2</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>num_primary_key_atts</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The number of primary key fields.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>src_pk_att_vals_array</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Values of the primary key fields to be used to look up the
|
|
local tuple. Each field is represented in text form.
|
|
An error is thrown if there is no local row with these
|
|
primary key values.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>tgt_pk_att_vals_array</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Values of the primary key fields to be placed in the resulting
|
|
<command>INSERT</> command. Each field is represented in text form.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>Returns the requested SQL statement as text.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
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)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-BUILD-SQL-DELETE">
|
|
<refmeta>
|
|
<refentrytitle>dblink_build_sql_delete</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_build_sql_delete</refname>
|
|
<refpurpose>builds a DELETE statement using supplied values for primary
|
|
key field values
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
dblink_build_sql_delete(text relname,
|
|
int2vector primary_key_attnums,
|
|
int2 num_primary_key_atts,
|
|
text[] tgt_pk_att_vals_array) returns text
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_build_sql_delete</> can be useful in doing selective
|
|
replication of a local table to a remote database. It builds a SQL
|
|
<command>DELETE</> command that will delete the row with the given
|
|
primary key values.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>relname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of a local relation, for example <literal>foo</> or
|
|
<literal>myschema.mytab</>. Include double quotes if the
|
|
name is mixed-case or contains special characters, for
|
|
example <literal>"FooBar"</>; without quotes, the string
|
|
will be folded to lower case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>primary_key_attnums</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Attribute numbers (1-based) of the primary key fields,
|
|
for example <literal>1 2</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>num_primary_key_atts</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The number of primary key fields.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>tgt_pk_att_vals_array</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Values of the primary key fields to be used in the resulting
|
|
<command>DELETE</> command. Each field is represented in text form.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>Returns the requested SQL statement as text.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
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)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="CONTRIB-DBLINK-BUILD-SQL-UPDATE">
|
|
<refmeta>
|
|
<refentrytitle>dblink_build_sql_update</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dblink_build_sql_update</refname>
|
|
<refpurpose>builds an UPDATE statement using a local tuple, replacing
|
|
the primary key field values with alternative supplied values
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
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
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<function>dblink_build_sql_update</> can be useful in doing selective
|
|
replication of a local table to a remote database. It selects a row
|
|
from the local table based on primary key, and then builds a SQL
|
|
<command>UPDATE</> command that will duplicate that row, but with
|
|
the primary key values replaced by the values in the last argument.
|
|
(To make an exact copy of the row, just specify the same values for
|
|
the last two arguments.) The <command>UPDATE</> command always assigns
|
|
all fields of the row — the main difference between this and
|
|
<function>dblink_build_sql_insert</> is that it's assumed that
|
|
the target row already exists in the remote table.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>relname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Name of a local relation, for example <literal>foo</> or
|
|
<literal>myschema.mytab</>. Include double quotes if the
|
|
name is mixed-case or contains special characters, for
|
|
example <literal>"FooBar"</>; without quotes, the string
|
|
will be folded to lower case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>primary_key_attnums</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Attribute numbers (1-based) of the primary key fields,
|
|
for example <literal>1 2</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>num_primary_key_atts</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The number of primary key fields.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>src_pk_att_vals_array</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Values of the primary key fields to be used to look up the
|
|
local tuple. Each field is represented in text form.
|
|
An error is thrown if there is no local row with these
|
|
primary key values.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>tgt_pk_att_vals_array</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Values of the primary key fields to be placed in the resulting
|
|
<command>UPDATE</> command. Each field is represented in text form.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>Returns the requested SQL statement as text.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
|
|
<programlisting>
|
|
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)
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</sect1>
|