2009-09-23 01:43:43 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/do.sgml
|
2009-09-23 01:43:43 +02:00
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="sql-do">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-do">
|
|
|
|
<primary>DO</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="sql-do">
|
|
|
|
<primary>anonymous code blocks</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2009-09-23 01:43:43 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>DO</refentrytitle>
|
2009-09-23 01:43:43 +02:00
|
|
|
<manvolnum>7</manvolnum>
|
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>DO</refname>
|
|
|
|
<refpurpose>execute an anonymous code block</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2017-10-09 04:00:57 +02:00
|
|
|
DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replaceable class="parameter">code</replaceable>
|
2009-09-23 01:43:43 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>DO</command> executes an anonymous code block, or in other
|
|
|
|
words a transient anonymous function in a procedural language.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The code block is treated as though it were the body of a function
|
2017-10-09 03:44:17 +02:00
|
|
|
with no parameters, returning <type>void</type>. It is parsed and
|
2009-09-23 01:43:43 +02:00
|
|
|
executed a single time.
|
|
|
|
</para>
|
2009-09-23 17:41:51 +02:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The optional <literal>LANGUAGE</literal> clause can be written either
|
2009-09-23 17:41:51 +02:00
|
|
|
before or after the code block.
|
|
|
|
</para>
|
2009-09-23 01:43:43 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2017-10-09 04:00:57 +02:00
|
|
|
<term><replaceable class="parameter">code</replaceable></term>
|
2009-09-23 01:43:43 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The procedural language code to be executed. This must be specified
|
2017-10-09 03:44:17 +02:00
|
|
|
as a string literal, just as in <command>CREATE FUNCTION</command>.
|
2009-09-23 01:43:43 +02:00
|
|
|
Use of a dollar-quoted literal is recommended.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2017-10-09 04:00:57 +02:00
|
|
|
<term><replaceable class="parameter">lang_name</replaceable></term>
|
2009-09-23 01:43:43 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the procedural language the code is written in.
|
2017-10-09 03:44:17 +02:00
|
|
|
If omitted, the default is <literal>plpgsql</literal>.
|
2009-09-23 01:43:43 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The procedural language to be used must already have been installed
|
2018-04-27 19:42:03 +02:00
|
|
|
into the current database by means of <command>CREATE EXTENSION</command>.
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>plpgsql</literal> is installed by default, but other languages are not.
|
2009-09-23 01:43:43 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The user must have <literal>USAGE</literal> privilege for the procedural
|
2009-09-23 01:43:43 +02:00
|
|
|
language, or must be a superuser if the language is untrusted.
|
|
|
|
This is the same privilege requirement as for creating a function
|
|
|
|
in the language.
|
|
|
|
</para>
|
Transaction control in PL procedures
In each of the supplied procedural languages (PL/pgSQL, PL/Perl,
PL/Python, PL/Tcl), add language-specific commit and rollback
functions/commands to control transactions in procedures in that
language. Add similar underlying functions to SPI. Some additional
cleanup so that transaction commit or abort doesn't blow away data
structures still used by the procedure call. Add execution context
tracking to CALL and DO statements so that transaction control commands
can only be issued in top-level procedure and block calls, not function
calls or other procedure or block calls.
- SPI
Add a new function SPI_connect_ext() that is like SPI_connect() but
allows passing option flags. The only option flag right now is
SPI_OPT_NONATOMIC. A nonatomic SPI connection can execute transaction
control commands, otherwise it's not allowed. This is meant to be
passed down from CALL and DO statements which themselves know in which
context they are called. A nonatomic SPI connection uses different
memory management. A normal SPI connection allocates its memory in
TopTransactionContext. For nonatomic connections we use PortalContext
instead. As the comment in SPI_connect_ext() (previously SPI_connect())
indicates, one could potentially use PortalContext in all cases, but it
seems safest to leave the existing uses alone, because this stuff is
complicated enough already.
SPI also gets new functions SPI_start_transaction(), SPI_commit(), and
SPI_rollback(), which can be used by PLs to implement their transaction
control logic.
- portalmem.c
Some adjustments were made in the code that cleans up portals at
transaction abort. The portal code could already handle a command
*committing* a transaction and continuing (e.g., VACUUM), but it was not
quite prepared for a command *aborting* a transaction and continuing.
In AtAbort_Portals(), remove the code that marks an active portal as
failed. As the comment there already predicted, this doesn't work if
the running command wants to keep running after transaction abort. And
it's actually not necessary, because pquery.c is careful to run all
portal code in a PG_TRY block and explicitly runs MarkPortalFailed() if
there is an exception. So the code in AtAbort_Portals() is never used
anyway.
In AtAbort_Portals() and AtCleanup_Portals(), we need to be careful not
to clean up active portals too much. This mirrors similar code in
PreCommit_Portals().
- PL/Perl
Gets new functions spi_commit() and spi_rollback()
- PL/pgSQL
Gets new commands COMMIT and ROLLBACK.
Update the PL/SQL porting example in the documentation to reflect that
transactions are now possible in procedures.
- PL/Python
Gets new functions plpy.commit and plpy.rollback.
- PL/Tcl
Gets new commands commit and rollback.
Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndquadrant.com>
2018-01-22 14:30:16 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
If <command>DO</command> is executed in a transaction block, then the
|
|
|
|
procedure code cannot execute transaction control statements. Transaction
|
|
|
|
control statements are only allowed if <command>DO</command> is executed in
|
|
|
|
its own transaction.
|
|
|
|
</para>
|
2009-09-23 01:43:43 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1 id="sql-do-examples">
|
2020-03-13 15:45:37 +01:00
|
|
|
<title>Examples</title>
|
2009-09-23 01:43:43 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Grant all privileges on all views in schema <literal>public</literal> to
|
|
|
|
role <literal>webuser</literal>:
|
2009-09-23 01:43:43 +02:00
|
|
|
<programlisting>
|
2009-09-23 17:41:51 +02:00
|
|
|
DO $$DECLARE r record;
|
2009-09-23 01:43:43 +02:00
|
|
|
BEGIN
|
2009-09-23 17:41:51 +02:00
|
|
|
FOR r IN SELECT table_schema, table_name FROM information_schema.tables
|
|
|
|
WHERE table_type = 'VIEW' AND table_schema = 'public'
|
2009-09-23 01:43:43 +02:00
|
|
|
LOOP
|
2009-09-23 17:41:51 +02:00
|
|
|
EXECUTE 'GRANT ALL ON ' || quote_ident(r.table_schema) || '.' || quote_ident(r.table_name) || ' TO webuser';
|
2009-09-23 01:43:43 +02:00
|
|
|
END LOOP;
|
|
|
|
END$$;
|
2011-08-07 09:49:45 +02:00
|
|
|
</programlisting></para>
|
2009-09-23 01:43:43 +02:00
|
|
|
</refsect1>
|
2011-08-07 09:49:45 +02:00
|
|
|
|
2009-09-23 01:43:43 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is no <command>DO</command> statement in the SQL standard.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="sql-createlanguage"/></member>
|
2009-09-23 01:43:43 +02:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|