From b2df5be7ee8b5ee7ae67323b5018ca37bbf0ce2a Mon Sep 17 00:00:00 2001 From: jonathan vanasco Date: Mon, 27 Sep 2021 15:15:33 -0400 Subject: Deprecate create_engine.implicit_returning The :paramref:`_sa.create_engine.implicit_returning` parameter is deprecated on the :func:`_sa.create_engine` function only; the parameter remains available on the :class:`_schema.Table` object. This parameter was originally intended to enable the "implicit returning" feature of SQLAlchemy when it was first developed and was not enabled by default. Under modern use, there's no reason this parameter should be disabled, and it has been observed to cause confusion as it degrades performance and makes it more difficult for the ORM to retrieve recently inserted server defaults. The parameter remains available on :class:`_schema.Table` to specifically suit database-level edge cases which make RETURNING infeasible, the sole example currently being SQL Server's limitation that INSERT RETURNING may not be used on a table that has INSERT triggers on it. Also removed from the Oracle dialect some logic that would upgrade an Oracle 8/8i server version to use implicit returning if the parameter were explictly passed; these versions of Oracle still support RETURNING so the feature is now enabled for all Oracle versions. Fixes: #6962 Change-Id: Ib338e300cd7c8026c3083043f645084a8211aed8 --- lib/sqlalchemy/dialects/oracle/base.py | 10 +++++++--- lib/sqlalchemy/engine/create.py | 9 +++++---- lib/sqlalchemy/engine/interfaces.py | 8 -------- lib/sqlalchemy/testing/assertsql.py | 31 ++++++++++++++++++++++------- lib/sqlalchemy/testing/suite/test_insert.py | 24 ++++++---------------- 5 files changed, 42 insertions(+), 40 deletions(-) (limited to 'lib') diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index 9e62b931d..5d9c7beec 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -1443,6 +1443,8 @@ class OracleDialect(default.DefaultDialect): supports_unicode_binds = False max_identifier_length = 128 + implicit_returning = True + supports_simple_order_by_label = False cte_follows_insert = True @@ -1508,9 +1510,11 @@ class OracleDialect(default.DefaultDialect): def initialize(self, connection): super(OracleDialect, self).initialize(connection) - self.implicit_returning = self.__dict__.get( - "implicit_returning", self.server_version_info > (10,) - ) + # Oracle 8i has RETURNING: + # https://docs.oracle.com/cd/A87860_01/doc/index.htm + + # so does Oracle8: + # https://docs.oracle.com/cd/A64702_01/doc/index.htm if self._is_oracle_8: self.colspecs = self.colspecs.copy() diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 6e5a07098..b10e72601 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -34,6 +34,11 @@ from ..sql import compiler 'expressions, or an "empty set" SELECT, at statement execution' "time.", ), + implicit_returning=( + "2.0", + "The :paramref:`_sa.create_engine.implicit_returning` parameter " + "is deprecated and will be removed in a future release. ", + ), ) def create_engine(url, **kwargs): """Create a new :class:`_engine.Engine` instance. @@ -350,8 +355,6 @@ def create_engine(url, **kwargs): :paramref:`_engine.Connection.execution_options.logging_token` - - :param max_identifier_length: integer; override the max_identifier_length determined by the dialect. if ``None`` or zero, has no effect. This is the database's configured maximum number of characters that may be @@ -411,13 +414,11 @@ def create_engine(url, **kwargs): "sqlalchemy.pool" logger. Defaults to a hexstring of the object's id. - .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. - :param pool_pre_ping: boolean, if True will enable the connection pool "pre-ping" feature that tests connections for liveness upon each checkout. diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 38d2c7a57..48b7e35a0 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -94,14 +94,6 @@ class Dialect(object): in order to get their value. This is currently oriented towards PostgreSQL. - ``implicit_returning`` - use RETURNING or equivalent during INSERT execution in order to load - newly generated primary keys and other column defaults in one execution, - which are then available via inserted_primary_key. - If an insert statement has returning() specified explicitly, - the "implicit" functionality is not used and inserted_primary_key - will not be available. - ``colspecs`` A dictionary of TypeEngine classes from sqlalchemy.types mapped to subclasses that are specific to the dialect class. This diff --git a/lib/sqlalchemy/testing/assertsql.py b/lib/sqlalchemy/testing/assertsql.py index ca0bc6726..9816c99b7 100644 --- a/lib/sqlalchemy/testing/assertsql.py +++ b/lib/sqlalchemy/testing/assertsql.py @@ -186,7 +186,9 @@ class CompiledSQL(SQLMatchRule): self.is_consumed = True self.errormessage = None else: - self.errormessage = self._failure_message(params) % { + self.errormessage = self._failure_message( + execute_observed, params + ) % { "received_statement": _received_statement, "received_parameters": _received_parameters, } @@ -203,7 +205,7 @@ class CompiledSQL(SQLMatchRule): else: return None - def _failure_message(self, expected_params): + def _failure_message(self, execute_observed, expected_params): return ( "Testing for compiled statement\n%r partial params %s, " "received\n%%(received_statement)r with params " @@ -223,7 +225,7 @@ class RegexSQL(CompiledSQL): self.params = params self.dialect = dialect - def _failure_message(self, expected_params): + def _failure_message(self, execute_observed, expected_params): return ( "Testing for compiled statement ~%r partial params %s, " "received %%(received_statement)r with params " @@ -263,11 +265,8 @@ class DialectSQL(CompiledSQL): return received_stmt, execute_observed.context.compiled_parameters - def _compare_sql(self, execute_observed, received_statement): + def _dialect_adjusted_statement(self, paramstyle): stmt = re.sub(r"[\n\t]", "", self.statement) - # convert our comparison statement to have the - # paramstyle of the received - paramstyle = execute_observed.context.dialect.paramstyle if paramstyle == "pyformat": stmt = re.sub(r":([\w_]+)", r"%(\1)s", stmt) else: @@ -280,9 +279,27 @@ class DialectSQL(CompiledSQL): elif paramstyle == "numeric": repl = None stmt = re.sub(r":([\w_]+)", repl, stmt) + return stmt + def _compare_sql(self, execute_observed, received_statement): + paramstyle = execute_observed.context.dialect.paramstyle + stmt = self._dialect_adjusted_statement(paramstyle) return received_statement == stmt + def _failure_message(self, execute_observed, expected_params): + paramstyle = execute_observed.context.dialect.paramstyle + return ( + "Testing for compiled statement\n%r partial params %s, " + "received\n%%(received_statement)r with params " + "%%(received_parameters)r" + % ( + self._dialect_adjusted_statement(paramstyle).replace( + "%", "%%" + ), + repr(expected_params).replace("%", "%%"), + ) + ) + class CountStatements(AssertRule): def __init__(self, count): diff --git a/lib/sqlalchemy/testing/suite/test_insert.py b/lib/sqlalchemy/testing/suite/test_insert.py index 3c22f50b2..080bb486e 100644 --- a/lib/sqlalchemy/testing/suite/test_insert.py +++ b/lib/sqlalchemy/testing/suite/test_insert.py @@ -1,5 +1,3 @@ -from .. import config -from .. import engines from .. import fixtures from ..assertions import eq_ from ..config import requirements @@ -19,8 +17,6 @@ class LastrowidTest(fixtures.TablesTest): __requires__ = "implements_get_lastrowid", "autoincrement_insert" - __engine_options__ = {"implicit_returning": False} - @classmethod def define_tables(cls, metadata): Table( @@ -30,6 +26,7 @@ class LastrowidTest(fixtures.TablesTest): "id", Integer, primary_key=True, test_needs_autoincrement=True ), Column("data", String(50)), + implicit_returning=False, ) Table( @@ -37,6 +34,7 @@ class LastrowidTest(fixtures.TablesTest): metadata, Column("id", Integer, primary_key=True, autoincrement=False), Column("data", String(50)), + implicit_returning=False, ) def _assert_round_trip(self, table, conn): @@ -110,18 +108,10 @@ class InsertBehaviorTest(fixtures.TablesTest): ) @requirements.autoincrement_insert - def test_autoclose_on_insert(self): - if requirements.returning.enabled: - engine = engines.testing_engine( - options={"implicit_returning": False} - ) - else: - engine = config.db - - with engine.begin() as conn: - r = conn.execute( - self.tables.autoinc_pk.insert(), dict(data="some data") - ) + def test_autoclose_on_insert(self, connection): + r = connection.execute( + self.tables.autoinc_pk.insert(), dict(data="some data") + ) assert r._soft_closed assert not r.closed assert r.is_insert @@ -306,8 +296,6 @@ class ReturningTest(fixtures.TablesTest): __requires__ = "returning", "autoincrement_insert" __backend__ = True - __engine_options__ = {"implicit_returning": True} - def _assert_round_trip(self, table, conn): row = conn.execute(table.select()).first() eq_( -- cgit v1.2.1