begriffs open source - ai-pg/blob - full-docs/man3/dblink_open.3

   1 '\" t
   2 .\"     Title: dblink_open
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "DBLINK_OPEN" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 dblink_open \- opens a cursor in a remote database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text
  36 dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBdblink_open()\fR
  41 opens a cursor in a remote database\&. The cursor can subsequently be manipulated with
  42 \fBdblink_fetch()\fR
  43 and
  44 \fBdblink_close()\fR\&.
  45 .SH "ARGUMENTS"
  46 .PP
  47 \fIconnname\fR
  48 .RS 4
  49 Name of the connection to use; omit this parameter to use the unnamed connection\&.
  50 .RE
  51 .PP
  52 \fIcursorname\fR
  53 .RS 4
  54 The name to assign to this cursor\&.
  55 .RE
  56 .PP
  57 \fIsql\fR
  58 .RS 4
  59 The
  60 \fBSELECT\fR
  61 statement that you wish to execute in the remote database, for example
  62 select * from pg_class\&.
  63 .RE
  64 .PP
  65 \fIfail_on_error\fR
  66 .RS 4
  67 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\*(Aqs return value is set to
  68 ERROR\&.
  69 .RE
  70 .SH "RETURN VALUE"
  71 .PP
  72 Returns status, either
  73 OK
  74 or
  75 ERROR\&.
  76 .SH "NOTES"
  77 .PP
  78 Since a cursor can only persist within a transaction,
  79 \fBdblink_open\fR
  80 starts an explicit transaction block (\fBBEGIN\fR) on the remote side, if the remote side was not already within a transaction\&. This transaction will be closed again when the matching
  81 \fBdblink_close\fR
  82 is executed\&. Note that if you use
  83 \fBdblink_exec\fR
  84 to change data between
  85 \fBdblink_open\fR
  86 and
  87 \fBdblink_close\fR, and then an error occurs or you use
  88 \fBdblink_disconnect\fR
  89 before
  90 \fBdblink_close\fR, your change
  91 \fIwill be lost\fR
  92 because the transaction will be aborted\&.
  93 .SH "EXAMPLES"
  94 .sp
  95 .if n \{\
  96 .RS 4
  97 .\}
  98 .nf
  99 SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq);
 100  dblink_connect
 101 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 102  OK
 103 (1 row)
 104
 105 SELECT dblink_open(\*(Aqfoo\*(Aq, \*(Aqselect proname, prosrc from pg_proc\*(Aq);
 106  dblink_open
 107 \-\-\-\-\-\-\-\-\-\-\-\-\-
 108  OK
 109 (1 row)
 110 .fi
 111 .if n \{\
 112 .RE
 113 .\}