From df860532b440657af15086e6338add6e987bbe8f Mon Sep 17 00:00:00 2001 From: Christopher Jones Date: Tue, 12 Nov 2024 10:11:20 +1100 Subject: [PATCH] Review fixes. Add link --- doc/build/core/engines.rst | 3 +- lib/sqlalchemy/dialects/oracle/base.py | 17 +++++---- lib/sqlalchemy/dialects/oracle/cx_oracle.py | 16 ++++---- lib/sqlalchemy/dialects/oracle/oracledb.py | 41 ++++++++++++++------- 4 files changed, 46 insertions(+), 31 deletions(-) diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 82820b090c..108a939a9e 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -209,7 +209,8 @@ DBAPI:: engine = create_engine("oracle+oracledb://scott:tiger@tnsalias") -The Oracle dialect uses the obsolete cx_Oracle driver as the default DBAPI:: +For historical reasons, the Oracle dialect uses the obsolete cx_Oracle driver +as the default DBAPI:: engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/?service_name=freepdb1") diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index 9fcc75d22c..e83204b39c 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -7,7 +7,8 @@ # mypy: ignore-errors -r""".. dialect:: oracle +r""" +.. dialect:: oracle :name: Oracle :normal_support: 11+ :best_effort: 9+ @@ -54,7 +55,7 @@ Database also supports two custom options specified using dialect kwargs: with a 'BY DEFAULT' identity column. * ``oracle_order``: when ``True``, renders the ORDER keyword, indicating the identity is definitively ordered. May be necessary to provide deterministic - ordering using Oracle RAC. + ordering using Oracle Real Application Clusters (RAC). Using a SEQUENCE (all Oracle Database versions) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -84,7 +85,7 @@ custom option specified using dialect kwargs: * ``oracle_order``: when ``True``, renders the ORDER keyword, indicating the sequence is definitively ordered. May be necessary to provide deterministic - ordering using Oracle Real Application Clusters (RAC). + ordering using Oracle RAC. .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the option of an autoincrementing @@ -118,9 +119,9 @@ Valid values for ``isolation_level`` include: .. note:: The implementation for the :meth:`_engine.Connection.get_isolation_level` method as implemented by the - Oracle Database dialects necessarily force the start of a transaction using - the Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function; - otherwise no level is normally readable. + Oracle Database dialects necessarily force the start of a transaction using the + Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function; otherwise no + level is normally readable. Additionally, the :meth:`_engine.Connection.get_isolation_level` method will raise an exception if the ``v$transaction`` view is not available due to @@ -415,8 +416,8 @@ will also include these constraints. Note the following caveats: * When using the :meth:`_reflection.Inspector.get_check_constraints` method, - Oracle Database dialects build a special "IS NOT NULL" constraint for columns - that specify "NOT NULL". This constraint is **not** returned by default; to + Oracle Database builds a special "IS NOT NULL" constraint for columns that + specify "NOT NULL". This constraint is **not** returned by default; to include the "IS NOT NULL" constraints, pass the flag ``include_all=True``:: from sqlalchemy import create_engine, inspect diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 2113defc93..babb916a60 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -381,14 +381,6 @@ series. This setting can be modified as follows:: if dbapitype is CLOB: del inputsizes[bindparam] -.. _cx_oracle_returning: - -RETURNING Support ------------------ - -The cx_Oracle dialect implements RETURNING using OUT parameters. -The dialect supports RETURNING fully. - .. _cx_oracle_lob: LOB Datatypes @@ -404,6 +396,14 @@ buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`, which takes place only engine-wide. +.. _cx_oracle_returning: + +RETURNING Support +----------------- + +The cx_Oracle dialect implements RETURNING using OUT parameters. +The dialect supports RETURNING fully. + Two Phase Transactions Not Supported ------------------------------------ diff --git a/lib/sqlalchemy/dialects/oracle/oracledb.py b/lib/sqlalchemy/dialects/oracle/oracledb.py index b7cd5034a1..541d088cd1 100644 --- a/lib/sqlalchemy/dialects/oracle/oracledb.py +++ b/lib/sqlalchemy/dialects/oracle/oracledb.py @@ -111,14 +111,23 @@ terminated by a firewall:: } ) +The Easy Connect syntax has been enhanced during the life of Oracle Database. +Review the documentation for your database version. The current documentation +is at `Understanding the Easy Connect Naming Method +`_. + +The general syntax is similar to:: + + [[protocol:]//]host[:port][/[service_name]][?parameter_name=value{¶meter_name=value}] + Note that although the SQLAlchemy URL syntax ``hostname:port/dbname`` looks -like Oracle's Easy Connect syntax, it is different. It requires a system -identifier (SID) for the ``dbname`` component of the URL:: +like Oracle's Easy Connect syntax, it is different. SQLAlchemy's URL requires a +system identifier (SID) for the ``dbname`` component:: engine = create_engine("oracle+oracledb://scott:tiger@hostname:port/sid") -Easy Connect syntax does not support SIDs. It uses services names, which are -the preferred choice for connecting to Oracle Database +Easy Connect syntax does not support SIDs. It uses services names, which are +the preferred choice for connecting to Oracle Database. Passing python-oracledb connect arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -249,6 +258,10 @@ connection pooling:: with engine.connect() as conn: print(conn.scalar(text("select 1 from dual"))) +Refer to the python-oracledb documentation for `oracledb.create_pool() +`_ +for the arguments that can be used when creating a connection pool. + .. _drcp: Using Oracle Database Resident Connection Pooling (DRCP) @@ -449,14 +462,6 @@ follows:: if dbapitype is CLOB: del inputsizes[bindparam] -.. _oracledb_returning: - -RETURNING Support ------------------ - -The oracledb dialect implements RETURNING using OUT parameters. The dialect -supports RETURNING fully. - .. _oracledb_lob: LOB Datatypes @@ -470,6 +475,14 @@ To disable the use of the type handlers and deliver LOB objects as classic buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`. +.. _oracledb_returning: + +RETURNING Support +----------------- + +The oracledb dialect implements RETURNING using OUT parameters. The dialect +supports RETURNING fully. + Two Phase Transaction Support ----------------------------- @@ -480,8 +493,6 @@ the Core level via :meth:`_engine.Connection.begin_twophase` and .. versionchanged:: 2.0.32 added support for two phase transactions -.. versionadded:: 2.0.0 added support for the python-oracledb driver. - .. _oracledb_numeric: Precision Numerics @@ -523,6 +534,8 @@ SQLAlchemy type (or a subclass of such). been reworked to take advantage of newer driver features as well as better integration of outputtypehandlers. +.. versionadded:: 2.0.0 added support for the python-oracledb driver. + """ # noqa from __future__ import annotations -- 2.47.3