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

   1 '\" t
   2 .\"     Title: dblink_exec
   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_EXEC" "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_exec \- executes a command in a remote database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
  36 dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
  37 dblink_exec(text sql [, bool fail_on_error]) returns text
  38 .fi
  39 .SH "DESCRIPTION"
  40 .PP
  41 \fBdblink_exec\fR
  42 executes a command (that is, any SQL statement that doesn\*(Aqt return rows) in a remote database\&.
  43 .PP
  44 When two
  45 text
  46 arguments are given, the first one is first looked up as a persistent connection\*(Aqs 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
  47 \fBdblink_connect\fR, and the indicated connection is made just for the duration of this command\&.
  48 .SH "ARGUMENTS"
  49 .PP
  50 \fIconnname\fR
  51 .RS 4
  52 Name of the connection to use; omit this parameter to use the unnamed connection\&.
  53 .RE
  54 .PP
  55 \fIconnstr\fR
  56 .RS 4
  57 A connection info string, as previously described for
  58 \fBdblink_connect\fR\&.
  59 .RE
  60 .PP
  61 \fIsql\fR
  62 .RS 4
  63 The SQL command that you wish to execute in the remote database, for example
  64 insert into foo values(0, \*(Aqa\*(Aq, \*(Aq{"a0","b0","c0"}\*(Aq)\&.
  65 .RE
  66 .PP
  67 \fIfail_on_error\fR
  68 .RS 4
  69 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
  70 ERROR\&.
  71 .RE
  72 .SH "RETURN VALUE"
  73 .PP
  74 Returns status, either the command\*(Aqs status string or
  75 ERROR\&.
  76 .SH "EXAMPLES"
  77 .sp
  78 .if n \{\
  79 .RS 4
  80 .\}
  81 .nf
  82 SELECT dblink_connect(\*(Aqdbname=dblink_test_standby\*(Aq);
  83  dblink_connect
  84 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  85  OK
  86 (1 row)
  87
  88 SELECT dblink_exec(\*(Aqinsert into foo values(21, \*(Aq\*(Aqz\*(Aq\*(Aq, \*(Aq\*(Aq{"a0","b0","c0"}\*(Aq\*(Aq);\*(Aq);
  89    dblink_exec
  90 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  91  INSERT 943366 1
  92 (1 row)
  93
  94 SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqdbname=regression\*(Aq);
  95  dblink_connect
  96 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  97  OK
  98 (1 row)
  99
 100 SELECT dblink_exec(\*(Aqmyconn\*(Aq, \*(Aqinsert into foo values(21, \*(Aq\*(Aqz\*(Aq\*(Aq, \*(Aq\*(Aq{"a0","b0","c0"}\*(Aq\*(Aq);\*(Aq);
 101    dblink_exec
 102 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 103  INSERT 6432584 1
 104 (1 row)
 105
 106 SELECT dblink_exec(\*(Aqmyconn\*(Aq, \*(Aqinsert into pg_class values (\*(Aq\*(Aqfoo\*(Aq\*(Aq)\*(Aq,false);
 107 NOTICE:  sql error
 108 DETAIL:  ERROR:  null value in column "relnamespace" violates not\-null constraint
 109
 110  dblink_exec
 111 \-\-\-\-\-\-\-\-\-\-\-\-\-
 112  ERROR
 113 (1 row)
 114 .fi
 115 .if n \{\
 116 .RE
 117 .\}