|
| 1 | +# ----------------------------------------------------------------------------- |
| 2 | +# Copyright (c) 2025 Oracle and/or its affiliates. |
| 3 | +# |
| 4 | +# This software is dual-licensed to you under the Universal Permissive License |
| 5 | +# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License |
| 6 | +# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose |
| 7 | +# either license. |
| 8 | +# |
| 9 | +# If you elect to accept the software under the Apache License, Version 2.0, |
| 10 | +# the following applies: |
| 11 | +# |
| 12 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 13 | +# you may not use this file except in compliance with the License. |
| 14 | +# You may obtain a copy of the License at |
| 15 | +# |
| 16 | +# https://www.apache.org/licenses/LICENSE-2.0 |
| 17 | +# |
| 18 | +# Unless required by applicable law or agreed to in writing, software |
| 19 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 20 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 21 | +# See the License for the specific language governing permissions and |
| 22 | +# limitations under the License. |
| 23 | +# ----------------------------------------------------------------------------- |
| 24 | + |
| 25 | +# ----------------------------------------------------------------------------- |
| 26 | +# sessionless_transactions.py |
| 27 | +# |
| 28 | +# Show Oracle Database 23ai Sessionless Transactions |
| 29 | +# ----------------------------------------------------------------------------- |
| 30 | + |
| 31 | +import sys |
| 32 | + |
| 33 | +import oracledb |
| 34 | +import sample_env |
| 35 | + |
| 36 | +# determine whether to use python-oracledb thin mode or thick mode |
| 37 | +if not sample_env.get_is_thin(): |
| 38 | + oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client()) |
| 39 | + |
| 40 | +# this script only works with Oracle Database 23.6 or later |
| 41 | +if sample_env.get_server_version() < (23, 6): |
| 42 | + sys.exit("This example requires Oracle Database 23.6 or later.") |
| 43 | + |
| 44 | +# this script works with thin mode, or with thick mode using Oracle Client |
| 45 | +# 23.6 or later |
| 46 | +if not oracledb.is_thin_mode() and oracledb.clientversion()[:2] < (23, 6): |
| 47 | + sys.exit( |
| 48 | + "This example requires python-oracledb thin mode, or Oracle Client" |
| 49 | + " 23.6 or later" |
| 50 | + ) |
| 51 | + |
| 52 | +TXN_ID = b"my_transaction_id" |
| 53 | + |
| 54 | +pool = oracledb.create_pool( |
| 55 | + user=sample_env.get_main_user(), |
| 56 | + password=sample_env.get_main_password(), |
| 57 | + dsn=sample_env.get_connect_string(), |
| 58 | + params=sample_env.get_pool_params(), |
| 59 | +) |
| 60 | + |
| 61 | +# ----------------------------------------------------------------------------- |
| 62 | +# Basic Sessionless Transaction example |
| 63 | + |
| 64 | +print("Example 1:") |
| 65 | + |
| 66 | +# Start and suspend a transaction |
| 67 | +with pool.acquire() as connection1: |
| 68 | + |
| 69 | + # Immediately begin the transaction |
| 70 | + connection1.begin_sessionless_transaction(transaction_id=TXN_ID) |
| 71 | + |
| 72 | + with connection1.cursor() as cursor1: |
| 73 | + cursor1.execute( |
| 74 | + "insert into mytab(id, data) values (:i, :d)", [1, "Sessionless 1"] |
| 75 | + ) |
| 76 | + connection1.suspend_sessionless_transaction() |
| 77 | + |
| 78 | + # Since the transaction is suspended, there will be no rows |
| 79 | + print("1st query") |
| 80 | + with connection1.cursor() as cursor1b: |
| 81 | + for r in cursor1b.execute("select * from mytab"): |
| 82 | + print(r) |
| 83 | + |
| 84 | +# Resume and complete the transaction in a different connection |
| 85 | +with pool.acquire() as connection2: |
| 86 | + |
| 87 | + # Immediately resume the transaction |
| 88 | + connection2.resume_sessionless_transaction(transaction_id=TXN_ID) |
| 89 | + |
| 90 | + with connection2.cursor() as cursor2: |
| 91 | + cursor2.execute( |
| 92 | + "insert into mytab(id, data) values (:i, :d)", [2, "Sessionless 2"] |
| 93 | + ) |
| 94 | + |
| 95 | + # The query will show both rows inserted |
| 96 | + print("2nd query") |
| 97 | + for r in cursor2.execute("select * from mytab order by id"): |
| 98 | + print(r) |
| 99 | + |
| 100 | + # Rollback so the example can be run multiple times. |
| 101 | + # This concludes the Sessionless Transaction |
| 102 | + connection2.rollback() |
| 103 | + |
| 104 | +# ----------------------------------------------------------------------------- |
| 105 | +# Sessionless Transaction example with custom timeouts and round-trip |
| 106 | +# optimizations |
| 107 | + |
| 108 | +print("Example 2:") |
| 109 | + |
| 110 | +# Start and suspend a transaction |
| 111 | +with pool.acquire() as connection3: |
| 112 | + |
| 113 | + connection3.begin_sessionless_transaction( |
| 114 | + transaction_id=TXN_ID, |
| 115 | + # The transaction can only ever be suspended for 15 seconds before it |
| 116 | + # is automatically rolled back |
| 117 | + timeout=15, |
| 118 | + # Only start the transaction when the next DB operation is performed |
| 119 | + defer_round_trip=True, |
| 120 | + ) |
| 121 | + with connection3.cursor() as cursor3: |
| 122 | + cursor3.execute( |
| 123 | + "insert into mytab(id, data) values (:i, :d)", |
| 124 | + [3, "Sessionless 3"], |
| 125 | + suspend_on_success=True, # automatically suspend on success |
| 126 | + ) |
| 127 | + |
| 128 | + # Since the transaction is suspended, there will be no rows |
| 129 | + print("1st query") |
| 130 | + with connection3.cursor() as cursor3b: |
| 131 | + for r in cursor3b.execute("select * from mytab"): |
| 132 | + print(r) |
| 133 | + |
| 134 | +# Resume and complete the transaction in a different connection |
| 135 | +with pool.acquire() as connection4: |
| 136 | + connection4.resume_sessionless_transaction( |
| 137 | + transaction_id=TXN_ID, |
| 138 | + # Only wait 20 seconds if someone else is using the transaction |
| 139 | + timeout=20, |
| 140 | + # Only initiate resuming the transaction when the next DB operation is |
| 141 | + # performed |
| 142 | + defer_round_trip=True, |
| 143 | + ) |
| 144 | + |
| 145 | + with connection4.cursor() as cursor4: |
| 146 | + cursor4.execute( |
| 147 | + "insert into mytab(id, data) values (:i, :d)", [4, "Sessionless 4"] |
| 148 | + ) |
| 149 | + |
| 150 | + # The query will show both rows inserted |
| 151 | + print("2nd query") |
| 152 | + for r in cursor4.execute("select * from mytab order by id"): |
| 153 | + print(r) |
| 154 | + |
| 155 | + # Rollback so the example can be run multiple times. |
| 156 | + # This concludes the Sessionless Transaction |
| 157 | + connection4.rollback() |
0 commit comments