From 43f11957a0ca6a9eaa247ea6cebe6d61e49c73bc Mon Sep 17 00:00:00 2001
From: Joeri van Ruth <joeri.van.ruth@monetdbsolutions.com>
Date: Mon, 26 Aug 2024 14:23:33 +0200
Subject: [PATCH] Add documentation on using PREPARE / EXEC

It has been supported since 1.6.4 but it wasn't documented

See also #116
---
 doc/index.rst               |  1 +
 doc/prepared_statements.rst | 41 +++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 doc/prepared_statements.rst

diff --git a/doc/index.rst b/doc/index.rst
index b459a46a..9b582636 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -28,6 +28,7 @@ Contents
    introduction
    examples
    filetransfers
+   prepared_statements
    batchsize
    api
    development
diff --git a/doc/prepared_statements.rst b/doc/prepared_statements.rst
new file mode 100644
index 00000000..a535463a
--- /dev/null
+++ b/doc/prepared_statements.rst
@@ -0,0 +1,41 @@
+Prepared Statements
+===================
+
+MonetDB offers a PREPARE_ statement, which precompiles a SQL statement for
+later execution. If the statement is going to be executed frequently,
+precompiling will safe time.
+
+The PREPARE statement yields a numeric prepared-sql-id which can then be passed
+to the EXECUTE statement to execute it. For example,
+
+::
+
+> sql>PREPARE SELECT ? + 42;
+> execute prepared statement using: EXEC 0(...)
+> ...
+> sql>execute 0(100);
+> +------+
+> | %2   |
+> +======+
+> |  142 |
+> +------+
+> 1 tuple
+> sql>
+
+When PREPARE is called from pymonetdb, the prepared-sql-id will be made available
+in the `lastrowid` attribute of the cursor. For example,
+
+::
+
+    with pymonetdb.connect('demo') as conn, conn.cursor() as c:
+        c.execute("PREPARE SELECT ? + 42")
+        exec_id = c.lastrowid
+        c.execute("EXECUTE %s(%s)", [exec_id, 100])
+        result = c.fetchone()[0]
+        assert result == 142
+
+Note: MonetDB versions older than Dec2023 (11.49.x) drop all prepared statements whenever
+the transaction fails. From Dec2023 onward, this has been corrected.
+
+
+.. _PREPARE: https://www.monetdb.org/documentation/user-guide/sql-manual/data-manipulation/prepare-statement/
\ No newline at end of file