DO blocks

src/current/_includes/v25.1/sidebar-data/sql.json

@@ -298,6 +298,12 @@
                 "/${VERSION}/delete.html"
               ]
             },
+            {
+              "title": "<code>DO</code>",
+              "urls": [
+                "/${VERSION}/do.html"
+              ]
+            },
             {
               "title": "<code>DROP DATABASE</code>",
               "urls": [

src/current/v25.1/do.md

@@ -0,0 +1,101 @@
+---
+title: DO
+summary: The DO statement executes a SQL or PL/pgSQL code block.
+toc: true
+keywords:
+docs_area: reference.sql
+---
+
+The `DO` [statement]({% link {{ page.version.version }}/sql-statements.md %}) defines a code block that executes SQL or [PL/pgSQL]({% link {{ page.version.version }}/plpgsql.md %}) syntax.
+
+## Required privileges
+
+- To execute a `DO` block, a user must have at least the [`USAGE` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the schema where the `DO` block is being executed.
+- To define a `DO` block with a [user-defined type]({% link {{ page.version.version }}/create-type.md %}), a user must have `USAGE` privilege on the user-defined type.
+
+## Synopsis
+
+<div>
+{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/do.html %}
+</div>
+
+## Parameters
+
+|     Parameter      |         Description         |
+|--------------------|-----------------------------|
+| `routine_body_str` | The body of the code block. |
+
+## Examples
+
+### Declare a variable in a `DO` block
+
+The following example uses the [PL/pgSQL `DECLARE` syntax]({% link {{ page.version.version }}/plpgsql.md %}#declare-a-variable) to declare variables to use in the code block.
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DO $$
+DECLARE
+    x INT := 10;
+    y INT := 5;
+    result INT;
+BEGIN
+    result := x + y;
+    RAISE NOTICE 'The sum of % and % is %', x, y, result;
+END $$;
+~~~
+
+~~~
+NOTICE: The sum of 10 and 5 is 15
+DO
+~~~
+
+### Use a loop in a `DO` block
+
+The following example uses the [PL/pgSQL `WHILE` syntax]({% link {{ page.version.version }}/plpgsql.md %}#write-loops) to loop through several statements.
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DO $$
+DECLARE
+   counter INT := 1;
+BEGIN
+   WHILE counter <= 5 LOOP
+       RAISE NOTICE 'Counter: %', counter;
+       counter := counter + 1;
+   END LOOP;
+END $$;
+~~~
+
+~~~
+NOTICE: Counter: 1
+NOTICE: Counter: 2
+NOTICE: Counter: 3
+NOTICE: Counter: 4
+NOTICE: Counter: 5
+DO
+~~~
+
+### Use a common table expression in a `DO` block
+
+The following example uses a [common table expression]({% link {{ page.version.version }}/common-table-expressions.md %}) in the body of the code block.
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DO $$
+DECLARE
+    sum_result INT;
+BEGIN
+    WITH numbers AS (
+        SELECT generate_series(1, 5) AS num
+    )
+    SELECT sum(num) INTO sum_result
+    FROM numbers;
+
+    RAISE NOTICE 'Sum of numbers 1-5: %', sum_result;
+END $$;
+~~~
+
+~~~
+NOTICE: Sum of numbers 1-5: 15
+DO
+~~~

src/current/v25.1/sql-statements.md

@@ -79,6 +79,7 @@ Statement | Usage
 [`CREATE TABLE AS`]({% link {{ page.version.version }}/create-table-as.md %}) | Create a new table in a database using the results from a [selection query]({% link {{ page.version.version }}/selection-queries.md %}).
 [`COPY FROM`]({% link {{ page.version.version }}/copy-from.md %}) | Copy data from a third-party client to a CockroachDB cluster.<br>For compatibility with PostgreSQL drivers and ORMs, CockroachDB supports `COPY FROM` statements issued only from third-party clients; you cannot issue `COPY FROM` statements from the [`cockroach` SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}). To import data from files, use an [`IMPORT INTO`]({% link {{ page.version.version }}/import-into.md %}) statement instead.
 [`DELETE`]({% link {{ page.version.version }}/delete.md %}) | Delete specific rows from a table.
+[`DO`]({% link {{ page.version.version }}/do.md %}) | Execute a SQL or [PL/pgSQL]({% link {{ page.version.version }}/plpgsql.md %}) code block.
 [`EXPORT`]({% link {{ page.version.version }}/export.md %}) | Export an entire table's data, or the results of a `SELECT` statement, to CSV files.
 [`IMPORT INTO`]({% link {{ page.version.version }}/import-into.md %}) | Bulk-insert CSV data into an existing table.
 [`INSERT`]({% link {{ page.version.version }}/insert.md %}) | Insert rows into a table.