What exactly does future=True do in sqlalchemy's create_engine() function?

Question

I'm reading through the SQLAlchemy 1.4 / 2.0 tutorial. In it, they suggest creating an engine via

from sqlalchemy import create_engine
engine = create_engine("sqlite+pysqlite:///:memory:", echo=True, future=True)

Digging into the docs for create_engine() it says,

:param future: Use the 2.0 style :class:_future.Engine and
:class:_future.Connection API.

What exactly does this mean? What functions or classes won't work if I exclude future=True? (Note that I'm using SQLAlchemy 1.4.26)

Answer 1

The "future" flag is a mechanism to allow a seamless shift from prior versions of SQLAlchemy to the new v2.0. The interim version (v1.4) has a foot on each side of the transition. Here is the note from the 1.4 tutorial:

A Note on the Future

This tutorial describes a new API that’s released in SQLAlchemy 1.4 known as 2.0 style. The purpose of the 2.0-style API is to provide forwards compatibility with SQLAlchemy 2.0, which is planned as the next generation of SQLAlchemy.

In order to provide the full 2.0 API, a new flag called future will be used, which will be seen as the tutorial describes the Engine and Session objects. These flags fully enable 2.0-compatibility mode and allow the code in the tutorial to proceed fully. When using the future flag with the create_engine() function, the object returned is a subclass of sqlalchemy.engine.Engine described as sqlalchemy.future.Engine. This tutorial will be referring to sqlalchemy.future.Engine.

See the site for more information: SQLAlchemy 1.4 Tutorial