Update tutorial.

Author: anthony-tuininga

.pre-commit-config.yaml

@@ -14,3 +14,4 @@ repos:
     rev: v0.0.291
     hooks:
     -   id: ruff
+        exclude: ^samples/

samples/tutorial/Python-and-Oracle-Database-The-New-Wave-of-Scripting.html

@@ -3,7 +3,7 @@
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
-# Copyright (c) 2017, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2017, 2025, 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
@@ -28,7 +28,7 @@
 
 import oracledb
 import decimal
-import db_config_thick as db_config
+import db_config
 
 con = oracledb.connect(
     user=db_config.user, password=db_config.pw, dsn=db_config.dsn

samples/tutorial/aq.py

@@ -0,0 +1,79 @@
+# -----------------------------------------------------------------------------
+# async_gather.py (Section 17.1)
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, 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.
+# -----------------------------------------------------------------------------
+
+import asyncio
+import oracledb
+import db_config
+
+# Number of coroutines to run
+CONCURRENCY = 5
+
+# Maximum connection pool size
+POOLSIZE = 5
+
+# Query the unique session identifier/serial number combination of a connection
+SQL = """select unique current_timestamp as ct, sid||'-'||serial# as sidser
+         from v$session_connect_info
+         where sid = sys_context('userenv', 'sid')"""
+
+
+# Show the unique session identifier/serial number of each connection that the
+# pool opens
+async def init_session(connection, requested_tag):
+    res = await connection.fetchone(SQL)
+    print(res[0].strftime("%H:%M:%S.%f"), "- init_session SID-SERIAL#", res[1])
+
+
+# The coroutine simply shows the session identifier/serial number of the
+# connection returned by the pool.acquire() call
+async def query(pool):
+    async with pool.acquire() as connection:
+        await connection.callproc("dbms_session.sleep", [1])
+        res = await connection.fetchone(SQL)
+        print(res[0].strftime("%H:%M:%S.%f"), "- query SID-SERIAL#", res[1])
+
+
+async def main():
+
+    pool = oracledb.create_pool_async(
+        user=db_config.user,
+        password=db_config.pw,
+        dsn=db_config.dsn,
+        min=1,
+        max=POOLSIZE,
+        session_callback=init_session,
+    )
+
+    coroutines = [query(pool) for i in range(CONCURRENCY)]
+
+    await asyncio.gather(*coroutines)
+
+    await pool.close()
+
+
+asyncio.run(main())

samples/tutorial/async_gather.py

@@ -3,7 +3,7 @@
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
-# Copyright (c) 2017, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2017, 2025, 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
@@ -27,7 +27,7 @@
 # -----------------------------------------------------------------------------
 
 import oracledb
-import db_config_thick as db_config
+import db_config
 
 con = oracledb.connect(
     user=db_config.user, password=db_config.pw, dsn=db_config.dsn

samples/tutorial/bind_sdo.py

@@ -3,7 +3,7 @@
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
-# Copyright (c) 2017, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2017, 2025, 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
@@ -30,7 +30,7 @@
 import db_config
 
 params = oracledb.ConnectParams(
-    host="localhost", port=1521, service_name="orclpdb"
+    host="localhost", port=1521, service_name="freepdb1"
 )
 con = oracledb.connect(
     user=db_config.user, password=db_config.pw, params=params

samples/tutorial/connect_params2.py

@@ -3,7 +3,7 @@
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2025, 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
@@ -34,8 +34,8 @@
 
 # default values
 PYTHON_USER = "pythondemo"
-PYTHON_CONNECT_STRING = "localhost/orclpdb"
-PYTHON_DRCP_CONNECT_STRING = "localhost/orclpdb:pooled"
+PYTHON_CONNECT_STRING = "localhost/freepdb1"
+PYTHON_DRCP_CONNECT_STRING = "localhost/freepdb1:pooled"
 
 # dictionary containing all parameters; these are acquired as needed by the
 # methods below (which should be used instead of consulting this dictionary

samples/tutorial/create_user.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2025, 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
@@ -32,7 +32,7 @@
 
 user = os.environ.get("PYTHON_USER", "pythondemo")
 
-dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/orclpdb")
+dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/freepdb1")
 
 pw = os.environ.get("PYTHON_PASSWORD")
 if pw is None:

samples/tutorial/db_config.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2025, 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
@@ -32,7 +32,7 @@
 
 sysuser = os.environ.get("PYTHON_SYSUSER", "SYSTEM")
 
-dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/orclpdb")
+dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/freepdb1")
 
 syspw = os.environ.get("PYTHON_SYSPASSWORD")
 if syspw is None:

samples/tutorial/db_config_sys.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2025, 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
@@ -42,7 +42,7 @@
 # Client directory.  Note the use of the raw string r"..."  so backslashes can
 # be used as directory separators.
 if platform.system() == "Windows":
-    instant_client_dir = r"C:\Oracle\instantclient_19_14"
+    instant_client_dir = r"C:\Oracle\instantclient_23_7"
 
 # On macOS set the directory to your Instant Client directory
 if platform.system() == "Darwin":
@@ -62,7 +62,7 @@
 
 user = os.environ.get("PYTHON_USER", "pythondemo")
 
-dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/orclpdb")
+dsn = os.environ.get("PYTHON_CONNECT_STRING", "localhost/freepdb1")
 
 pw = os.environ.get("PYTHON_PASSWORD")
 if pw is None:

samples/tutorial/db_config_thick.py

@@ -1,10 +1,10 @@
 # -----------------------------------------------------------------------------
 # drcp_query.py (Section 2.4 and 2.5)
-# Look at pool statistics of the DRCP Connection
+# Query DRCP pool statistics
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022, 2025, Oracle and/or its affiliates. All rights reserved.
 #
 # 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
@@ -33,9 +33,7 @@
 
 # default values
 PYTHON_SYS_USER = "SYSTEM"
-PYTHON_USER = "pythondemo"
-PYTHON_CONNECT_STRING = "localhost/orclpdb"
-PYTHON_DRCP_CONNECT_STRING = "localhost/orclpdb:pooled"
+PYTHON_DRCP_CONNECT_STRING = "localhost/free"
 
 # dictionary containing all parameters; these are acquired as needed by the
 # methods below (which should be used instead of consulting this dictionary
@@ -63,7 +61,11 @@ def get_value(name, label, default_value=""):
 
 
 def get_main_user():
-    return get_value("user", "Enter the DRCP User", PYTHON_SYS_USER)
+    return get_value(
+        "user",
+        "Enter the privileged user with access to DRCP views",
+        PYTHON_SYS_USER,
+    )
 
 
 def get_main_password():
@@ -73,10 +75,10 @@ def get_main_password():
 def get_drcp_connect_string():
     connect_string = get_value(
         "DRCP_CONNECT_STRING",
-        "Enter the DRCP Connect String",
+        "Enter the connect string to access the DRCP views",
         PYTHON_DRCP_CONNECT_STRING,
     )
-    return "%s/%s@%s" % (get_main_user(), get_main_password(), connect_string)
+    return connect_string
 
 
 drcp_user = get_main_user()

samples/tutorial/drcp_query.py

@@ -0,0 +1,41 @@
+# -----------------------------------------------------------------------------
+# json_insert.py (Section 8.1)
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, 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.
+# -----------------------------------------------------------------------------
+
+import oracledb
+import db_config
+
+con = oracledb.connect(
+    user=db_config.user, password=db_config.pw, dsn=db_config.dsn
+)
+cur = con.cursor()
+
+# Insert JSON data
+data = dict(name="Rod", dept="Sales", location="Germany")
+inssql = "insert into jtab (id, json_data) values (:1, :2)"
+cur.setinputsizes(None, oracledb.DB_TYPE_JSON)
+cur.execute(inssql, [101, data])

samples/tutorial/json_insert.py

@@ -0,0 +1,73 @@
+# -----------------------------------------------------------------------------
+# pipelining.py (Section 18.1)
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, 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.
+# -----------------------------------------------------------------------------
+
+import asyncio
+import oracledb
+import db_config
+
+
+async def get_weather():
+    return "Hot and sunny"
+
+
+async def get_location():
+    return "Melbourne"
+
+
+async def main():
+    con = await oracledb.connect_async(
+        user=db_config.user, password=db_config.pw, dsn=db_config.dsn
+    )
+
+    pipeline = oracledb.create_pipeline()
+    pipeline.add_fetchone(
+        "select ename, job from emp where empno = :en", [7839]
+    )
+    pipeline.add_fetchall("select dname from dept order by deptno")
+
+    # Run the pipeline and non-database operations concurrently.
+    # Note although the database receives all the operations at the same time,
+    # it will execute each operation sequentially. The local Python work
+    # executes during the time the database is processing the queries.
+    return_values = await asyncio.gather(
+        get_weather(), get_location(), con.run_pipeline(pipeline)
+    )
+
+    for r in return_values:
+        if isinstance(r, list):  # the pipeline return list
+            for result in r:
+                if result.rows:
+                    for row in result.rows:
+                        print(*row, sep="\t")
+        else:
+            print(r)  # a local operation result
+
+    await con.close()
+
+
+asyncio.run(main())