Update documentation and add samples for executemany() with PL/SQL.

anthony-tuininga · anthony-tuininga · commit eb1daa48a8f2 · 2024-12-18T15:23:38.000-07:00
diff --git a/doc/src/user_guide/batch_statement.rst b/doc/src/user_guide/batch_statement.rst
@@ -153,12 +153,20 @@ With named bind variables, use named parameters when calling
             values (:pid, :pdesc)""", data)
 
 
+.. _batchplsql:
+
 Batch Execution of PL/SQL
 =========================
 
-PL/SQL functions and procedures and anonymous PL/SQL blocks can also be called
-using :meth:`~Cursor.executemany()` in order to improve performance. For
-example:
+Using :meth:`~Cursor.executemany()` can improve performance when PL/SQL
+functions, procedures, or anonymous blocks need to be called multiple times.
+
+Runnable examples are in `plsql_batch.py <https://github.com/oracle/python-
+oracledb/tree/main/samples/plsql_batch.py>`__.
+
+**IN Binds**
+
+An example using :ref:`bind by position <bindbyposition>` for IN binds is:
 
 .. code-block:: python
 
@@ -171,12 +179,110 @@ example:
     ]
     cursor.executemany("begin mypkg.create_parent(:1, :2); end;", data)
 
-If ``executemany()`` is used for PL/SQL code that returns OUT binds it will
-have the same performance characteristics as repeated calls to ``execute()``.
+Note that the ``batcherrors`` parameter of :meth:`~Cursor.executemany()`
+(discussed in :ref:`batcherrors`) cannot be used with PL/SQL block execution.
+
+**OUT Binds**
+
+When using OUT binds in PL/SQL, the input data omits entries for the OUT bind
+variable placeholders. An example PL/SQL procedure that returns OUT binds is:
+
+.. code-block:: sql
+
+    create or replace procedure myproc(p1 in number, p2 out number) as
+    begin
+        p2 := p1 * 2;
+    end;
+
+This can be called in python-oracledb using positional binds like:
+
+.. code-block:: python
+
+    data = [
+        (100,),
+        (200,),
+        (300,)
+    ]
+
+    outvals = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data))
+    cursor.setinputsizes(None, outvals)
+
+    cursor.executemany("begin myproc(:1, :2); end;", data)
+    print(outvals.values)
+
+The output is::
+
+    [200, 400, 600]
+
+The equivalent code using named binds is:
+
+.. code-block:: python
+
+    data = [
+        {"p1bv": 100},
+        {"p1bv": 200},
+        {"p1bv": 300}
+    ]
+
+    outvals = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data))
+    cursor.setinputsizes(p1bv=None, p2bv=outvals)
+
+    cursor.executemany("begin myproc(:p1bv, :p2bv); end;", data)
+    print(outvals.values)
+
+Note that in python-oracledb Thick mode, when :meth:`~Cursor.executemany()` is
+used for PL/SQL code that returns OUT binds, it will have the same performance
+characteristics as repeated calls to :meth:`~Cursor.execute()`.
+
+**IN/OUT Binds**
+
+An example PL/SQL procedure that returns IN/OUT binds is:
+
+.. code-block:: sql
+
+    create or replace procedure myproc2 (p1 in number, p2 in out varchar2) as
+    begin
+        p2 := p2 || ' ' || p1;
+    end;
+
+This can be called in python-oracledb using positional binds like:
+
+.. code-block:: python
+
+    data = [
+        (440, 'Gregory'),
+        (550, 'Haley'),
+        (660, 'Ian')
+    ]
+    outvals = cursor.var(oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data))
+    cursor.setinputsizes(None, outvals)
+
+    cursor.executemany("begin myproc2(:1, :2); end;", data)
+    print(outvals.values)
+
+The ``size`` parameter of :meth:`Cursor.var()` indicates the maximum length of
+the string that can be returned.
+
+Output is::
+
+    ['Gregory 440', 'Haley 550', 'Ian 660']
+
+The equivalent code using named binds is:
+
+.. code-block:: python
+
+    data = [
+        {"p1bv": 440, "p2bv": 'Gregory'},
+        {"p1bv": 550, "p2bv": 'Haley'},
+        {"p1bv": 660, "p2bv": 'Ian'}
+    ]
+    outvals = cursor.var(oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data))
+    cursor.setinputsizes(p1bv=None, p2bv=outvals)
 
-Note that the ``batcherrors`` parameter (discussed below) cannot be used with
-PL/SQL block execution.
+    cursor.executemany("begin myproc2(:p1bv, :p2bv); end;", data)
+    print(outvals.values)
 
+.. _batcherrors:
 
 Handling Data Errors
 ====================
diff --git a/doc/src/user_guide/plsql_execution.rst b/doc/src/user_guide/plsql_execution.rst
@@ -4,9 +4,14 @@
 Executing PL/SQL
 ****************
 
-PL/SQL stored procedures, functions and anonymous blocks can be called from
+PL/SQL stored procedures, functions, and anonymous blocks can be called from
 python-oracledb.
 
+Examples in this chapter show single invocations using
+:meth:`Cursor.callproc()`, :meth:`Cursor.callfunc()`, or
+:meth:`Cursor.execute()`. Examples of repeated calls using
+:meth:`Cursor.executemany()` are shown in :ref:`batchplsql`.
+
 .. _plsqlproc:
 
 PL/SQL Stored Procedures
diff --git a/samples/plsql_batch.py b/samples/plsql_batch.py
@@ -0,0 +1,193 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2024, Oracle and/or its affiliates.
+#
+# This software is dual-licensed to you under the Universal Permissive License
+# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+# either license.
+#
+# If you elect to accept the software under the Apache License, Version 2.0,
+# the following applies:
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# plsql_batch.py
+#
+# Demonstrates using executemany() to make repeated calls to a PL/SQL procedure
+#
+# Note in python-oracledb Thick mode, when cursor.executemany() is used for
+# PL/SQL code that returns OUT binds, it will have the same performance
+# characteristics as repeated calls to cursor.execute().
+# -----------------------------------------------------------------------------
+
+import oracledb
+import sample_env
+
+# determine whether to use python-oracledb thin mode or thick mode
+if not sample_env.get_is_thin():
+    oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+
+connection = oracledb.connect(
+    user=sample_env.get_main_user(),
+    password=sample_env.get_main_password(),
+    dsn=sample_env.get_connect_string(),
+    params=sample_env.get_connect_params(),
+)
+
+# -----------------------------------------------------------------------------
+# IN and OUT PL/SQL parameter examples
+# Also shows passing in an object
+# -----------------------------------------------------------------------------
+
+# Setup
+
+with connection.cursor() as cursor:
+    stmts = [
+        """create or replace type my_varchar_list as table of varchar2(100)""",
+        """create or replace procedure myproc
+                  (p in number, names in my_varchar_list, count out number) as
+           begin
+               count := p + names.count;
+           end;""",
+    ]
+    for s in stmts:
+        cursor.execute(s)
+        if cursor.warning:
+            print(cursor.warning)
+            print(s)
+
+type_obj = connection.gettype("MY_VARCHAR_LIST")
+
+# Example 1: positional binds
+
+with connection.cursor() as cursor:
+
+    obj1 = type_obj.newobject()
+    obj1.extend(["Alex", "Bobbie"])
+    obj2 = type_obj.newobject()
+    obj2.extend(["Charlie", "Dave", "Eric"])
+    obj3 = type_obj.newobject()
+    obj3.extend(["Fred", "Georgia", "Helen", "Ian"])
+
+    data = [
+        (1, obj1),
+        (2, obj2),
+        (3, obj3),
+    ]
+
+    count = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data))
+    cursor.setinputsizes(None, type_obj, count)
+
+    cursor.executemany("begin myproc(:1, :2, :3); end;", data)
+    print(count.values)  # [3, 5, 7]
+
+# Example 2: named binds
+
+with connection.cursor() as cursor:
+
+    obj1 = type_obj.newobject()
+    obj1.extend(["Alex", "Bobbie"])
+    obj2 = type_obj.newobject()
+    obj2.extend(["Charlie", "Dave", "Eric"])
+    obj3 = type_obj.newobject()
+    obj3.extend(["Fred", "Georgia", "Helen", "Ian"])
+
+    data = [
+        {"p": 100, "names": obj1},
+        {"p": 200, "names": obj2},
+        {"p": 300, "names": obj3},
+    ]
+
+    count = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data))
+    cursor.setinputsizes(p=None, names=type_obj, count=count)
+
+    cursor.executemany("begin myproc(:p, :names, :count); end;", data)
+    print(count.values)  # [102, 203, 304]
+
+# -----------------------------------------------------------------------------
+# IN/OUT PL/SQL parameter examples
+# -----------------------------------------------------------------------------
+
+# Setup
+
+with connection.cursor() as cursor:
+    stmt = """create or replace procedure myproc2
+                     (p1 in number, p2 in out varchar2) as
+              begin
+                  p2 := p2 || ' ' || p1;
+              end;"""
+    cursor.execute(stmt)
+    if cursor.warning:
+        print(cursor.warning)
+        print(stmt)
+
+# Example 3: positional binds
+
+with connection.cursor() as cursor:
+    data = [(440, "Gregory"), (550, "Haley"), (660, "Ian")]
+    outvals = cursor.var(
+        oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)
+    )
+    cursor.setinputsizes(None, outvals)
+
+    cursor.executemany("begin myproc2(:1, :2); end;", data)
+    print(outvals.values)  # ['Gregory 440', 'Haley 550', 'Ian 660']
+
+# Example 4: positional binds, utilizing setvalue()
+
+with connection.cursor() as cursor:
+    data = [(777,), (888,), (999,)]
+
+    inoutvals = cursor.var(
+        oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)
+    )
+    inoutvals.setvalue(0, "Roger")
+    inoutvals.setvalue(1, "Sally")
+    inoutvals.setvalue(2, "Tom")
+    cursor.setinputsizes(None, inoutvals)
+
+    cursor.executemany("begin myproc2(:1, :2); end;", data)
+    print(inoutvals.values)  # ['Roger 777', 'Sally 888', 'Tom 999']
+
+# Example 5: named binds
+
+with connection.cursor() as cursor:
+    data = [
+        {"p1bv": 100, "p2bv": "Alfie"},
+        {"p1bv": 200, "p2bv": "Brian"},
+        {"p1bv": 300, "p2bv": "Cooper"},
+    ]
+    outvals = cursor.var(
+        oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)
+    )
+    cursor.setinputsizes(p1bv=None, p2bv=outvals)
+
+    cursor.executemany("begin myproc2(:p1bv, :p2bv); end;", data)
+    print(outvals.values)  # ['Alfie 100', 'Brian 200', 'Cooper 300']
+
+# Example 6: named binds, utilizing setvalue()
+
+with connection.cursor() as cursor:
+    inoutvals = cursor.var(
+        oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)
+    )
+    inoutvals.setvalue(0, "Dean")
+    inoutvals.setvalue(1, "Elsa")
+    inoutvals.setvalue(2, "Felix")
+    data = [{"p1bv": 101}, {"p1bv": 202}, {"p1bv": 303}]
+    cursor.setinputsizes(p1bv=None, p2bv=inoutvals)
+
+    cursor.executemany("begin myproc2(:p1bv, :p2bv); end;", data)
+    print(inoutvals.values)  # ['Dean 101', 'Elsa 202', 'Felix 303']
diff --git a/samples/plsql_batch_async.py b/samples/plsql_batch_async.py
