Added support for setting the edition when connecting to Oracle

Database.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -46,6 +46,8 @@ Thin Mode Changes
     operation.
 #)  Added attribute :data:`PipelineOpResult.columns` to provide information
     about any query column metadata returned from a pipeline operation.
+#)  Added support for setting the :ref:`edition <ebr>` when connecting to
+    Oracle Database.
 #)  Fixed bug causing some pooled connections to be permanently marked as busy
     and unavailable for reuse
     (`issue 392 <https://github.com/oracle/python-oracledb/issues/392>`__).

doc/src/user_guide/appendix_a.rst

@@ -183,7 +183,7 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - Yes
       - Yes
     * - Edition Based Redefinition (EBR) (see :ref:`ebr`)
-      - No - not at connect time.  ALTER SESSION can be used.
+      - Yes
       - Yes
       - Yes
     * - SQL execution (see :ref:`sqlexecution`)

doc/src/user_guide/plsql_execution.rst

@@ -422,38 +422,34 @@ or eliminating down time. This feature allows multiple versions of views,
 synonyms, PL/SQL objects and SQL Translation profiles to be used concurrently.
 Different versions of the database objects are associated with an "edition".
 
-.. note::
-
-    Setting the Edition-Based Redefinition (EBR) edition at connection time is
-    only supported in the python-oracledb Thick mode.  See
-    :ref:`enablingthick`.  In python-oracledb Thin mode, the edition can be
-    changed with ALTER SESSION after connecting.
-
-The simplest way to set an edition is to pass the ``edition`` parameter to
-:meth:`oracledb.connect()` or :meth:`oracledb.create_pool()`:
+The simplest way to set the edition used by your applications is to pass the
+``edition`` parameter to :meth:`oracledb.connect()` or
+:meth:`oracledb.create_pool()`:
 
 .. code-block:: python
 
     connection = oracledb.connect(user="hr", password=userpwd,
                                    dsn="dbhost.example.com/orclpdb",
-                                   edition="newsales", encoding="UTF-8")
+                                   edition="newsales")
 
 
-The edition could also be set by setting the environment variable
-``ORA_EDITION`` or by executing the SQL statement:
+The edition can also be set by executing the SQL statement:
 
 .. code-block:: sql
 
     alter session set edition = <edition name>;
 
-Regardless of which method is used to set the edition, the value that is in use
-can be seen by examining the attribute :attr:`Connection.edition`. If no value
-has been set, the value will be None. This corresponds to the database default
+You can also set the environment variable ``ORA_EDITION`` to your edition name.
+
+Regardless of which method sets the edition, the value that is in use can be
+seen by examining the attribute :attr:`Connection.edition`. If no value has
+been set, the value will be None. This corresponds to the database default
 edition ``ORA$BASE``.
 
 Consider an example where one version of a PL/SQL function ``Discount`` is
 defined in the database default edition ``ORA$BASE`` and the other version of
-the same function is defined in a user created edition ``DEMO``.
+the same function is defined in a user created edition ``DEMO``.  In your SQL
+editor run:
 
 .. code-block:: sql
 
@@ -494,14 +490,13 @@ The ``Discount`` function for the demo edition is as follows:
     END;
     /
 
-The Python application can then call the required version of the PL/SQL
-function as shown:
+A Python application can then call the required version of the PL/SQL function
+as shown:
 
 .. code-block:: python
 
     connection = oracledb.connect(user=user, password=password,
-                                   dsn="dbhost.example.com/orclpdb",
-                                   encoding="UTF-8")
+                                   dsn="dbhost.example.com/orclpdb")
     print("Edition is:", repr(connection.edition))
 
     cursor = connection.cursor()
@@ -511,7 +506,7 @@ function as shown:
     # Use the edition parameter for the connection
     connection = oracledb.connect(user=user, password=password,
                                    dsn="dbhost.example.com/orclpdb",
-                                   edition="demo", encoding="UTF-8")
+                                   edition="demo")
     print("Edition is:", repr(connection.edition))
 
     cursor = connection.cursor()

samples/editioning.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 #
 # Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
 #
@@ -41,8 +41,9 @@
 import oracledb
 import sample_env
 
-# this script is currently only supported in python-oracledb thick mode
-oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+# 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())
 
 # connect to the editions user and create a procedure
 edition_connect_string = sample_env.get_edition_connect_string()

src/oracledb/impl/base/connect_params.pyx

@@ -55,6 +55,7 @@ cdef class ConnectParamsImpl:
         self.description_list = DescriptionList()
         self.description_list.children.append(self._default_description)
         self.debug_jdwp = os.getenv("ORA_DEBUG_JDWP")
+        self.edition = os.getenv("ORA_EDITION")
         address_list = AddressList()
         address_list.children.append(self._default_address)
         self._default_description.children.append(address_list)

src/oracledb/impl/thin/messages.pyx

@@ -1458,6 +1458,7 @@ cdef class AuthMessage(Message):
         str machine
         str osuser
         str driver_name
+        str edition
 
     cdef int _encrypt_passwords(self) except -1:
         """
@@ -1644,6 +1645,7 @@ cdef class AuthMessage(Message):
             self.conn_impl.server_version = self._get_version_tuple(buf)
             self.conn_impl.supports_bool = \
                     buf._caps.ttc_field_version >= TNS_CCAP_FIELD_VERSION_23_1
+            self.conn_impl._edition = self.edition
 
     cdef int _set_params(self, ConnectParamsImpl params,
                          Description description) except -1:
@@ -1664,6 +1666,7 @@ cdef class AuthMessage(Message):
         self.driver_name = params.driver_name
         if self.driver_name is None:
             self.driver_name = f"{DRIVER_NAME} thn : {DRIVER_VERSION}"
+        self.edition = params.edition
 
         # if drcp is used, use purity = NEW as the default purity for
         # standalone connections and purity = SELF for connections that belong
@@ -1765,6 +1768,8 @@ cdef class AuthMessage(Message):
                 num_pairs += 2
             if self.encoded_jdwp_data is not None:
                 num_pairs += 1
+            if self.edition is not None:
+                num_pairs += 1
 
         # write basic data to packet
         self._write_function_code(buf)
@@ -1829,6 +1834,8 @@ cdef class AuthMessage(Message):
             if self.encoded_jdwp_data is not None:
                 self._write_key_value(buf, "AUTH_ORA_DEBUG_JDWP",
                                       self.encoded_jdwp_data)
+            if self.edition is not None:
+                self._write_key_value(buf, "AUTH_ORA_EDITION", self.edition)
 
 
 @cython.final

tests/create_schema.py

@@ -47,6 +47,7 @@
     main_password=test_env.get_main_password(),
     proxy_user=test_env.get_proxy_user(),
     proxy_password=test_env.get_proxy_password(),
+    edition_name=test_env.get_edition_name(),
 )
 if test_env.get_server_version() >= (21, 0):
     test_env.run_sql_script(

tests/drop_schema.py

@@ -42,6 +42,7 @@ def drop_schema(conn):
         "drop_schema",
         main_user=test_env.get_main_user(),
         proxy_user=test_env.get_proxy_user(),
+        edition_name=test_env.get_edition_name(),
     )
 
 

tests/sql/create_schema.sql

@@ -77,6 +77,13 @@ begin
 end;
 /
 
+-- create edition
+create edition &edition_name
+/
+
+grant use on edition &edition_name to &main_user
+/
+
 -- create types
 create type &main_user..udt_SubObject as object (
     SubNumberValue                      number,

tests/sql/drop_schema.sql

@@ -40,5 +40,13 @@ begin
         execute immediate 'drop user ' || r.username || ' cascade';
     end loop;
 
+    for r in
+            ( select edition_name
+              from dba_editions
+              where edition_name in (upper('&edition_name'))
+            ) loop
+        execute immediate 'drop edition ' || r.edition_name || ' cascade';
+    end loop;
+
 end;
 /

tests/test_1100_connection.py

@@ -915,6 +915,32 @@ def hook(passed_protocol, passed_protocol_arg, passed_params):
         finally:
             oracledb.register_protocol(protocol, None)
 
+    def test_1154(self):
+        "1154 - test altering connection edition"
+        conn = test_env.get_connection()
+        self.assertIsNone(conn.edition)
+        cursor = conn.cursor()
+        sql = "select sys_context('USERENV', 'CURRENT_EDITION_NAME') from dual"
+        default_edition = "ORA$BASE"
+        test_edition = test_env.get_edition_name()
+        for edition in [test_edition, default_edition]:
+            with self.subTest(edition=edition):
+                cursor.execute(f"alter session set edition = {edition}")
+                cursor.execute(sql)
+                self.assertEqual(conn.edition, cursor.fetchone()[0])
+                self.assertEqual(conn.edition, edition.upper())
+
+    def test_1155(self):
+        "1155 - test connect() with edition"
+        edition = test_env.get_edition_name()
+        conn = test_env.get_connection(edition=edition)
+        cursor = conn.cursor()
+        cursor.execute(
+            "select sys_context('USERENV', 'CURRENT_EDITION_NAME') from dual"
+        )
+        self.assertEqual(cursor.fetchone()[0], edition.upper())
+        self.assertEqual(conn.edition, edition)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_2400_pool.py

@@ -979,6 +979,13 @@ def hook(passed_protocol, passed_protocol_arg, passed_params):
         finally:
             oracledb.register_protocol(protocol, None)
 
+    def test_2448(self):
+        "2448 - test create_pool() with edition"
+        edition = test_env.get_edition_name()
+        pool = test_env.get_pool(edition=edition)
+        conn = pool.acquire()
+        self.assertEqual(conn.edition, edition)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_5300_connection_async.py

@@ -690,6 +690,34 @@ def hook(passed_protocol, passed_protocol_arg, passed_params):
         finally:
             oracledb.register_protocol(protocol, None)
 
+    async def test_5354(self):
+        "5354 - test altering connection edition"
+        conn = await test_env.get_admin_connection_async()
+        self.assertIsNone(conn.edition)
+        cursor = conn.cursor()
+        sql = "select sys_context('USERENV', 'CURRENT_EDITION_NAME') from dual"
+        default_edition = "ORA$BASE"
+        test_edition = test_env.get_edition_name()
+        for edition in [test_edition, default_edition]:
+            with self.subTest(edition=edition):
+                await cursor.execute(f"alter session set edition = {edition}")
+                await cursor.execute(sql)
+                (fetched_edition,) = await cursor.fetchone()
+                self.assertEqual(fetched_edition, edition.upper())
+                self.assertEqual(conn.edition, edition.upper())
+
+    async def test_5355(self):
+        "5355 - test connect() with edition"
+        edition = test_env.get_edition_name()
+        conn = await test_env.get_connection_async(edition=edition)
+        cursor = conn.cursor()
+        await cursor.execute(
+            "select sys_context('USERENV', 'CURRENT_EDITION_NAME') from dual"
+        )
+        (fetched_edition,) = await cursor.fetchone()
+        self.assertEqual(fetched_edition, edition.upper())
+        self.assertEqual(conn.edition, edition)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_5500_pool_async.py

@@ -581,6 +581,14 @@ def hook(passed_protocol, passed_protocol_arg, passed_params):
         finally:
             oracledb.register_protocol(protocol, None)
 
+    async def test_5536(self):
+        "5536 - test create_pool() with edition"
+        edition = test_env.get_edition_name()
+        pool = test_env.get_pool_async(edition=edition)
+        async with pool.acquire() as conn:
+            self.assertEqual(conn.edition, edition)
+        await pool.close()
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_env.py

@@ -41,6 +41,7 @@
 #   PYO_TEST_WALLET_PASSWORD: password for wallet file (thin mode, mTLS)
 #   PYO_TEST_DRIVER_MODE: python-oracledb mode (thick or thin) to use
 #   PYO_TEST_EXTERNAL_USER: user for testing external authentication
+#   PYO_TEST_EDITION_NAME: name of edition for editioning tests
 #
 # PYO_TEST_CONNECT_STRING can be set to an Easy Connect string, or a
 # Net Service Name from a tnsnames.ora file or external naming service,
@@ -74,6 +75,7 @@
 DEFAULT_MAIN_USER = "pythontest"
 DEFAULT_PROXY_USER = "pythontestproxy"
 DEFAULT_CONNECT_STRING = "localhost/orclpdb1"
+DEFAULT_EDITION_NAME = "pythonedition"
 
 # dictionary containing all parameters; these are acquired as needed by the
 # methods below (which should be used instead of consulting this dictionary
@@ -242,6 +244,10 @@ def get_connect_string():
     )
 
 
+def get_edition_name():
+    return get_value("EDITION_NAME", "Edition Name", DEFAULT_EDITION_NAME)
+
+
 def get_is_drcp():
     value = PARAMETERS.get("IS_DRCP")
     if value is None: