begriffs open source - ai-pg/blob - full-docs/txt/contrib-dblink-function.txt

   1
   2 dblink
   3
   4    dblink — executes a query in a remote database
   5
   6 Synopsis
   7
   8 dblink(text connname, text sql [, bool fail_on_error]) returns setof record
   9 dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
  10 dblink(text sql [, bool fail_on_error]) returns setof record
  11
  12 Description
  13
  14    dblink executes a query (usually a SELECT, but it can be any SQL
  15    statement that returns rows) in a remote database.
  16
  17    When two text arguments are given, the first one is first looked up as
  18    a persistent connection's name; if found, the command is executed on
  19    that connection. If not found, the first argument is treated as a
  20    connection info string as for dblink_connect, and the indicated
  21    connection is made just for the duration of this command.
  22
  23 Arguments
  24
  25    connname
  26           Name of the connection to use; omit this parameter to use the
  27           unnamed connection.
  28
  29    connstr
  30           A connection info string, as previously described for
  31           dblink_connect.
  32
  33    sql
  34           The SQL query that you wish to execute in the remote database,
  35           for example select * from foo.
  36
  37    fail_on_error
  38           If true (the default when omitted) then an error thrown on the
  39           remote side of the connection causes an error to also be thrown
  40           locally. If false, the remote error is locally reported as a
  41           NOTICE, and the function returns no rows.
  42
  43 Return Value
  44
  45    The function returns the row(s) produced by the query. Since dblink can
  46    be used with any query, it is declared to return record, rather than
  47    specifying any particular set of columns. This means that you must
  48    specify the expected set of columns in the calling query — otherwise
  49    PostgreSQL would not know what to expect. Here is an example:
  50 SELECT *
  51     FROM dblink('dbname=mydb options=-csearch_path=',
  52                 'select proname, prosrc from pg_proc')
  53       AS t1(proname name, prosrc text)
  54     WHERE proname LIKE 'bytea%';
  55
  56    The “alias” part of the FROM clause must specify the column names and
  57    types that the function will return. (Specifying column names in an
  58    alias is actually standard SQL syntax, but specifying column types is a
  59    PostgreSQL extension.) This allows the system to understand what *
  60    should expand to, and what proname in the WHERE clause refers to, in
  61    advance of trying to execute the function. At run time, an error will
  62    be thrown if the actual query result from the remote database does not
  63    have the same number of columns shown in the FROM clause. The column
  64    names need not match, however, and dblink does not insist on exact type
  65    matches either. It will succeed so long as the returned data strings
  66    are valid input for the column type declared in the FROM clause.
  67
  68 Notes
  69
  70    A convenient way to use dblink with predetermined queries is to create
  71    a view. This allows the column type information to be buried in the
  72    view, instead of having to spell it out in every query. For example,
  73 CREATE VIEW myremote_pg_proc AS
  74   SELECT *
  75     FROM dblink('dbname=postgres options=-csearch_path=',
  76                 'select proname, prosrc from pg_proc')
  77     AS t1(proname name, prosrc text);
  78
  79 SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%';
  80
  81 Examples
  82
  83 SELECT * FROM dblink('dbname=postgres options=-csearch_path=',
  84                      'select proname, prosrc from pg_proc')
  85   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
  86   proname   |   prosrc
  87 ------------+------------
  88  byteacat   | byteacat
  89  byteaeq    | byteaeq
  90  bytealt    | bytealt
  91  byteale    | byteale
  92  byteagt    | byteagt
  93  byteage    | byteage
  94  byteane    | byteane
  95  byteacmp   | byteacmp
  96  bytealike  | bytealike
  97  byteanlike | byteanlike
  98  byteain    | byteain
  99  byteaout   | byteaout
 100 (12 rows)
 101
 102 SELECT dblink_connect('dbname=postgres options=-csearch_path=');
 103  dblink_connect
 104 ----------------
 105  OK
 106 (1 row)
 107
 108 SELECT * FROM dblink('select proname, prosrc from pg_proc')
 109   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
 110   proname   |   prosrc
 111 ------------+------------
 112  byteacat   | byteacat
 113  byteaeq    | byteaeq
 114  bytealt    | bytealt
 115  byteale    | byteale
 116  byteagt    | byteagt
 117  byteage    | byteage
 118  byteane    | byteane
 119  byteacmp   | byteacmp
 120  bytealike  | bytealike
 121  byteanlike | byteanlike
 122  byteain    | byteain
 123  byteaout   | byteaout
 124 (12 rows)
 125
 126 SELECT dblink_connect('myconn', 'dbname=regression options=-csearch_path=');
 127  dblink_connect
 128 ----------------
 129  OK
 130 (1 row)
 131
 132 SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc')
 133   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
 134   proname   |   prosrc
 135 ------------+------------
 136  bytearecv  | bytearecv
 137  byteasend  | byteasend
 138  byteale    | byteale
 139  byteagt    | byteagt
 140  byteage    | byteage
 141  byteane    | byteane
 142  byteacmp   | byteacmp
 143  bytealike  | bytealike
 144  byteanlike | byteanlike
 145  byteacat   | byteacat
 146  byteaeq    | byteaeq
 147  bytealt    | bytealt
 148  byteain    | byteain
 149  byteaout   | byteaout
 150 (14 rows)