Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/sqlalchemy/dialects/sqlite/base.py: 35%

1# dialects/sqlite/base.py 

2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors 

3# <see AUTHORS file> 

4# 

5# This module is part of SQLAlchemy and is released under 

6# the MIT License: https://www.opensource.org/licenses/mit-license.php 

7# mypy: ignore-errors 

8 

9 

10r''' 

11.. dialect:: sqlite 

12 :name: SQLite 

13 :normal_support: 3.12+ 

14 :best_effort: 3.7.16+ 

15 

16.. _sqlite_datetime: 

17 

18Date and Time Types 

19------------------- 

20 

21SQLite does not have built-in DATE, TIME, or DATETIME types, and pysqlite does 

22not provide out of the box functionality for translating values between Python 

23`datetime` objects and a SQLite-supported format. SQLAlchemy's own 

24:class:`~sqlalchemy.types.DateTime` and related types provide date formatting 

25and parsing functionality when SQLite is used. The implementation classes are 

26:class:`_sqlite.DATETIME`, :class:`_sqlite.DATE` and :class:`_sqlite.TIME`. 

27These types represent dates and times as ISO formatted strings, which also 

28nicely support ordering. There's no reliance on typical "libc" internals for 

29these functions so historical dates are fully supported. 

30 

31Ensuring Text affinity 

32^^^^^^^^^^^^^^^^^^^^^^ 

33 

34The DDL rendered for these types is the standard ``DATE``, ``TIME`` 

35and ``DATETIME`` indicators. However, custom storage formats can also be 

36applied to these types. When the 

37storage format is detected as containing no alpha characters, the DDL for 

38these types is rendered as ``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, 

39so that the column continues to have textual affinity. 

40 

41.. seealso:: 

42 

43 `Type Affinity <https://www.sqlite.org/datatype3.html#affinity>`_ - 

44 in the SQLite documentation 

45 

46.. _sqlite_autoincrement: 

47 

48SQLite Auto Incrementing Behavior 

49---------------------------------- 

50 

51Background on SQLite's autoincrement is at: https://sqlite.org/autoinc.html 

52 

53Key concepts: 

54 

55* SQLite has an implicit "auto increment" feature that takes place for any 

56 non-composite primary-key column that is specifically created using 

57 "INTEGER PRIMARY KEY" for the type + primary key. 

58 

59* SQLite also has an explicit "AUTOINCREMENT" keyword, that is **not** 

60 equivalent to the implicit autoincrement feature; this keyword is not 

61 recommended for general use. SQLAlchemy does not render this keyword 

62 unless a special SQLite-specific directive is used (see below). However, 

63 it still requires that the column's type is named "INTEGER". 

64 

65Using the AUTOINCREMENT Keyword 

66^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

67 

68To specifically render the AUTOINCREMENT keyword on the primary key column 

69when rendering DDL, add the flag ``sqlite_autoincrement=True`` to the Table 

70construct:: 

71 

72 Table( 

73 "sometable", 

74 metadata, 

75 Column("id", Integer, primary_key=True), 

76 sqlite_autoincrement=True, 

77 ) 

78 

79Allowing autoincrement behavior SQLAlchemy types other than Integer/INTEGER 

80^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

81 

82SQLite's typing model is based on naming conventions. Among other things, this 

83means that any type name which contains the substring ``"INT"`` will be 

84determined to be of "integer affinity". A type named ``"BIGINT"``, 

85``"SPECIAL_INT"`` or even ``"XYZINTQPR"``, will be considered by SQLite to be 

86of "integer" affinity. However, **the SQLite autoincrement feature, whether 

87implicitly or explicitly enabled, requires that the name of the column's type 

88is exactly the string "INTEGER"**. Therefore, if an application uses a type 

89like :class:`.BigInteger` for a primary key, on SQLite this type will need to 

90be rendered as the name ``"INTEGER"`` when emitting the initial ``CREATE 

91TABLE`` statement in order for the autoincrement behavior to be available. 

92 

93One approach to achieve this is to use :class:`.Integer` on SQLite 

94only using :meth:`.TypeEngine.with_variant`:: 

95 

96 table = Table( 

97 "my_table", 

98 metadata, 

99 Column( 

100 "id", 

101 BigInteger().with_variant(Integer, "sqlite"), 

102 primary_key=True, 

103 ), 

104 ) 

105 

106Another is to use a subclass of :class:`.BigInteger` that overrides its DDL 

107name to be ``INTEGER`` when compiled against SQLite:: 

108 

109 from sqlalchemy import BigInteger 

110 from sqlalchemy.ext.compiler import compiles 

111 

112 

113 class SLBigInteger(BigInteger): 

114 pass 

115 

116 

117 @compiles(SLBigInteger, "sqlite") 

118 def bi_c(element, compiler, **kw): 

119 return "INTEGER" 

120 

121 

122 @compiles(SLBigInteger) 

123 def bi_c(element, compiler, **kw): 

124 return compiler.visit_BIGINT(element, **kw) 

125 

126 

127 table = Table( 

128 "my_table", metadata, Column("id", SLBigInteger(), primary_key=True) 

129 ) 

130 

131.. seealso:: 

132 

133 :meth:`.TypeEngine.with_variant` 

134 

135 :ref:`sqlalchemy.ext.compiler_toplevel` 

136 

137 `Datatypes In SQLite Version 3 <https://sqlite.org/datatype3.html>`_ 

138 

139.. _sqlite_transactions: 

140 

141Transactions with SQLite and the sqlite3 driver 

142----------------------------------------------- 

143 

144As a file-based database, SQLite's approach to transactions differs from 

145traditional databases in many ways. Additionally, the ``sqlite3`` driver 

146standard with Python (as well as the async version ``aiosqlite`` which builds 

147on top of it) has several quirks, workarounds, and API features in the 

148area of transaction control, all of which generally need to be addressed when 

149constructing a SQLAlchemy application that uses SQLite. 

150 

151Legacy Transaction Mode with the sqlite3 driver 

152^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

153 

154The most important aspect of transaction handling with the sqlite3 driver is 

155that it defaults (which will continue through Python 3.15 before being 

156removed in Python 3.16) to legacy transactional behavior which does 

157not strictly follow :pep:`249`. The way in which the driver diverges from the 

158PEP is that it does not "begin" a transaction automatically as dictated by 

159:pep:`249` except in the case of DML statements, e.g. INSERT, UPDATE, and 

160DELETE. Normally, :pep:`249` dictates that a BEGIN must be emitted upon 

161the first SQL statement of any kind, so that all subsequent operations will 

162be established within a transaction until ``connection.commit()`` has been 

163called. The ``sqlite3`` driver, in an effort to be easier to use in 

164highly concurrent environments, skips this step for DQL (e.g. SELECT) statements, 

165and also skips it for DDL (e.g. CREATE TABLE etc.) statements for more legacy 

166reasons. Statements such as SAVEPOINT are also skipped. 

167 

168In modern versions of the ``sqlite3`` driver as of Python 3.12, this legacy 

169mode of operation is referred to as 

170`"legacy transaction control" <https://docs.python.org/3/library/sqlite3.html#sqlite3-transaction-control-isolation-level>`_, and is in 

171effect by default due to the ``Connection.autocommit`` parameter being set to 

172the constant ``sqlite3.LEGACY_TRANSACTION_CONTROL``. Prior to Python 3.12, 

173the ``Connection.autocommit`` attribute did not exist. 

174 

175The implications of legacy transaction mode include: 

176 

177* **Incorrect support for transactional DDL** - statements like CREATE TABLE, ALTER TABLE, 

178 CREATE INDEX etc. will not automatically BEGIN a transaction if one were not 

179 started already, leading to the changes by each statement being 

180 "autocommitted" immediately unless BEGIN were otherwise emitted first. Very 

181 old (pre Python 3.6) versions of SQLite would also force a COMMIT for these 

182 operations even if a transaction were present, however this is no longer the 

183 case. 

184* **SERIALIZABLE behavior not fully functional** - SQLite's transaction isolation 

185 behavior is normally consistent with SERIALIZABLE isolation, as it is a file- 

186 based system that locks the database file entirely for write operations, 

187 preventing COMMIT until all reader transactions (and associated file locks) 

188 have completed. However, sqlite3's legacy transaction mode fails to emit BEGIN for SELECT 

189 statements, which causes these SELECT statements to no longer be "repeatable", 

190 failing one of the consistency guarantees of SERIALIZABLE. 

191* **Incorrect behavior for SAVEPOINT** - as the SAVEPOINT statement does not 

192 imply a BEGIN, a new SAVEPOINT emitted before a BEGIN will function on its 

193 own but fails to participate in the enclosing transaction, meaning a ROLLBACK 

194 of the transaction will not rollback elements that were part of a released 

195 savepoint. 

196 

197Legacy transaction mode first existed in order to faciliate working around 

198SQLite's file locks. Because SQLite relies upon whole-file locks, it is easy to 

199get "database is locked" errors, particularly when newer features like "write 

200ahead logging" are disabled. This is a key reason why ``sqlite3``'s legacy 

201transaction mode is still the default mode of operation; disabling it will 

202produce behavior that is more susceptible to locked database errors. However 

203note that **legacy transaction mode will no longer be the default** in a future 

204Python version (3.16 as of this writing). 

205 

206.. _sqlite_enabling_transactions: 

207 

208Enabling Non-Legacy SQLite Transactional Modes with the sqlite3 or aiosqlite driver 

209^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

210 

211Current SQLAlchemy support allows either for setting the 

212``.Connection.autocommit`` attribute, most directly by using a 

213:func:`._sa.create_engine` parameter, or if on an older version of Python where 

214the attribute is not available, using event hooks to control the behavior of 

215BEGIN. 

216 

217* **Enabling modern sqlite3 transaction control via the autocommit connect parameter** (Python 3.12 and above) 

218 

219 To use SQLite in the mode described at `Transaction control via the autocommit attribute <https://docs.python.org/3/library/sqlite3.html#transaction-control-via-the-autocommit-attribute>`_, 

220 the most straightforward approach is to set the attribute to its recommended value 

221 of ``False`` at the connect level using :paramref:`_sa.create_engine.connect_args``:: 

222 

223 from sqlalchemy import create_engine 

224 

225 engine = create_engine( 

226 "sqlite:///myfile.db", connect_args={"autocommit": False} 

227 ) 

228 

229 This parameter is also passed through when using the aiosqlite driver:: 

230 

231 from sqlalchemy.ext.asyncio import create_async_engine 

232 

233 engine = create_async_engine( 

234 "sqlite+aiosqlite:///myfile.db", connect_args={"autocommit": False} 

235 ) 

236 

237 The parameter can also be set at the attribute level using the :meth:`.PoolEvents.connect` 

238 event hook, however this will only work for sqlite3, as aiosqlite does not yet expose this 

239 attribute on its ``Connection`` object:: 

240 

241 from sqlalchemy import create_engine, event 

242 

243 engine = create_engine("sqlite:///myfile.db") 

244 

245 

246 @event.listens_for(engine, "connect") 

247 def do_connect(dbapi_connection, connection_record): 

248 # enable autocommit=False mode 

249 dbapi_connection.autocommit = False 

250 

251* **Using SQLAlchemy to emit BEGIN in lieu of SQLite's transaction control** (all Python versions, sqlite3 and aiosqlite) 

252 

253 For older versions of ``sqlite3`` or for cross-compatiblity with older and 

254 newer versions, SQLAlchemy can also take over the job of transaction control. 

255 This is achieved by using the :meth:`.ConnectionEvents.begin` hook 

256 to emit the "BEGIN" command directly, while also disabling SQLite's control 

257 of this command using the :meth:`.PoolEvents.connect` event hook to set the 

258 ``Connection.isolation_level`` attribute to ``None``:: 

259 

260 

261 from sqlalchemy import create_engine, event 

262 

263 engine = create_engine("sqlite:///myfile.db") 

264 

265 

266 @event.listens_for(engine, "connect") 

267 def do_connect(dbapi_connection, connection_record): 

268 # disable sqlite3's emitting of the BEGIN statement entirely. 

269 dbapi_connection.isolation_level = None 

270 

271 

272 @event.listens_for(engine, "begin") 

273 def do_begin(conn): 

274 # emit our own BEGIN. sqlite3 still emits COMMIT/ROLLBACK correctly 

275 conn.exec_driver_sql("BEGIN") 

276 

277 When using the asyncio variant ``aiosqlite``, refer to ``engine.sync_engine`` 

278 as in the example below:: 

279 

280 from sqlalchemy import create_engine, event 

281 from sqlalchemy.ext.asyncio import create_async_engine 

282 

283 engine = create_async_engine("sqlite+aiosqlite:///myfile.db") 

284 

285 

286 @event.listens_for(engine.sync_engine, "connect") 

287 def do_connect(dbapi_connection, connection_record): 

288 # disable aiosqlite's emitting of the BEGIN statement entirely. 

289 dbapi_connection.isolation_level = None 

290 

291 

292 @event.listens_for(engine.sync_engine, "begin") 

293 def do_begin(conn): 

294 # emit our own BEGIN. aiosqlite still emits COMMIT/ROLLBACK correctly 

295 conn.exec_driver_sql("BEGIN") 

296 

297.. _sqlite_isolation_level: 

298 

299Using SQLAlchemy's Driver Level AUTOCOMMIT Feature with SQLite 

300^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

301 

302SQLAlchemy has a comprehensive database isolation feature with optional 

303autocommit support that is introduced in the section :ref:`dbapi_autocommit`. 

304 

305For the ``sqlite3`` and ``aiosqlite`` drivers, SQLAlchemy only includes 

306built-in support for "AUTOCOMMIT". Note that this mode is currently incompatible 

307with the non-legacy isolation mode hooks documented in the previous 

308section at :ref:`sqlite_enabling_transactions`. 

309 

310To use the ``sqlite3`` driver with SQLAlchemy driver-level autocommit, 

311create an engine setting the :paramref:`_sa.create_engine.isolation_level` 

312parameter to "AUTOCOMMIT":: 

313 

314 eng = create_engine("sqlite:///myfile.db", isolation_level="AUTOCOMMIT") 

315 

316When using the above mode, any event hooks that set the sqlite3 ``Connection.autocommit`` 

317parameter away from its default of ``sqlite3.LEGACY_TRANSACTION_CONTROL`` 

318as well as hooks that emit ``BEGIN`` should be disabled. 

319 

320Additional Reading for SQLite / sqlite3 transaction control 

321^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

322 

323Links with important information on SQLite, the sqlite3 driver, 

324as well as long historical conversations on how things got to their current state: 

325 

326* `Isolation in SQLite <https://www.sqlite.org/isolation.html>`_ - on the SQLite website 

327* `Transaction control <https://docs.python.org/3/library/sqlite3.html#transaction-control>`_ - describes the sqlite3 autocommit attribute as well 

328 as the legacy isolation_level attribute. 

329* `sqlite3 SELECT does not BEGIN a transaction, but should according to spec <https://github.com/python/cpython/issues/54133>`_ - imported Python standard library issue on github 

330* `sqlite3 module breaks transactions and potentially corrupts data <https://github.com/python/cpython/issues/54949>`_ - imported Python standard library issue on github 

331 

332 

333INSERT/UPDATE/DELETE...RETURNING 

334--------------------------------- 

335 

336The SQLite dialect supports SQLite 3.35's ``INSERT|UPDATE|DELETE..RETURNING`` 

337syntax. ``INSERT..RETURNING`` may be used 

338automatically in some cases in order to fetch newly generated identifiers in 

339place of the traditional approach of using ``cursor.lastrowid``, however 

340``cursor.lastrowid`` is currently still preferred for simple single-statement 

341cases for its better performance. 

342 

343To specify an explicit ``RETURNING`` clause, use the 

344:meth:`._UpdateBase.returning` method on a per-statement basis:: 

345 

346 # INSERT..RETURNING 

347 result = connection.execute( 

348 table.insert().values(name="foo").returning(table.c.col1, table.c.col2) 

349 ) 

350 print(result.all()) 

351 

352 # UPDATE..RETURNING 

353 result = connection.execute( 

354 table.update() 

355 .where(table.c.name == "foo") 

356 .values(name="bar") 

357 .returning(table.c.col1, table.c.col2) 

358 ) 

359 print(result.all()) 

360 

361 # DELETE..RETURNING 

362 result = connection.execute( 

363 table.delete() 

364 .where(table.c.name == "foo") 

365 .returning(table.c.col1, table.c.col2) 

366 ) 

367 print(result.all()) 

368 

369.. versionadded:: 2.0 Added support for SQLite RETURNING 

370 

371 

372.. _sqlite_foreign_keys: 

373 

374Foreign Key Support 

375------------------- 

376 

377SQLite supports FOREIGN KEY syntax when emitting CREATE statements for tables, 

378however by default these constraints have no effect on the operation of the 

379table. 

380 

381Constraint checking on SQLite has three prerequisites: 

382 

383* At least version 3.6.19 of SQLite must be in use 

384* The SQLite library must be compiled *without* the SQLITE_OMIT_FOREIGN_KEY 

385 or SQLITE_OMIT_TRIGGER symbols enabled. 

386* The ``PRAGMA foreign_keys = ON`` statement must be emitted on all 

387 connections before use -- including the initial call to 

388 :meth:`sqlalchemy.schema.MetaData.create_all`. 

389 

390SQLAlchemy allows for the ``PRAGMA`` statement to be emitted automatically for 

391new connections through the usage of events:: 

392 

393 from sqlalchemy.engine import Engine 

394 from sqlalchemy import event 

395 

396 

397 @event.listens_for(Engine, "connect") 

398 def set_sqlite_pragma(dbapi_connection, connection_record): 

399 # the sqlite3 driver will not set PRAGMA foreign_keys 

400 # if autocommit=False; set to True temporarily 

401 ac = dbapi_connection.autocommit 

402 dbapi_connection.autocommit = True 

403 

404 cursor = dbapi_connection.cursor() 

405 cursor.execute("PRAGMA foreign_keys=ON") 

406 cursor.close() 

407 

408 # restore previous autocommit setting 

409 dbapi_connection.autocommit = ac 

410 

411.. warning:: 

412 

413 When SQLite foreign keys are enabled, it is **not possible** 

414 to emit CREATE or DROP statements for tables that contain 

415 mutually-dependent foreign key constraints; 

416 to emit the DDL for these tables requires that ALTER TABLE be used to 

417 create or drop these constraints separately, for which SQLite has 

418 no support. 

419 

420.. seealso:: 

421 

422 `SQLite Foreign Key Support <https://www.sqlite.org/foreignkeys.html>`_ 

423 - on the SQLite web site. 

424 

425 :ref:`event_toplevel` - SQLAlchemy event API. 

426 

427 :ref:`use_alter` - more information on SQLAlchemy's facilities for handling 

428 mutually-dependent foreign key constraints. 

429 

430.. _sqlite_on_conflict_ddl: 

431 

432ON CONFLICT support for constraints 

433----------------------------------- 

434 

435.. seealso:: This section describes the :term:`DDL` version of "ON CONFLICT" for 

436 SQLite, which occurs within a CREATE TABLE statement. For "ON CONFLICT" as 

437 applied to an INSERT statement, see :ref:`sqlite_on_conflict_insert`. 

438 

439SQLite supports a non-standard DDL clause known as ON CONFLICT which can be applied 

440to primary key, unique, check, and not null constraints. In DDL, it is 

441rendered either within the "CONSTRAINT" clause or within the column definition 

442itself depending on the location of the target constraint. To render this 

443clause within DDL, the extension parameter ``sqlite_on_conflict`` can be 

444specified with a string conflict resolution algorithm within the 

445:class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`, 

446:class:`.CheckConstraint` objects. Within the :class:`_schema.Column` object, 

447there 

448are individual parameters ``sqlite_on_conflict_not_null``, 

449``sqlite_on_conflict_primary_key``, ``sqlite_on_conflict_unique`` which each 

450correspond to the three types of relevant constraint types that can be 

451indicated from a :class:`_schema.Column` object. 

452 

453.. seealso:: 

454 

455 `ON CONFLICT <https://www.sqlite.org/lang_conflict.html>`_ - in the SQLite 

456 documentation 

457 

458.. versionadded:: 1.3 

459 

460 

461The ``sqlite_on_conflict`` parameters accept a string argument which is just 

462the resolution name to be chosen, which on SQLite can be one of ROLLBACK, 

463ABORT, FAIL, IGNORE, and REPLACE. For example, to add a UNIQUE constraint 

464that specifies the IGNORE algorithm:: 

465 

466 some_table = Table( 

467 "some_table", 

468 metadata, 

469 Column("id", Integer, primary_key=True), 

470 Column("data", Integer), 

471 UniqueConstraint("id", "data", sqlite_on_conflict="IGNORE"), 

472 ) 

473 

474The above renders CREATE TABLE DDL as: 

475 

476.. sourcecode:: sql 

477 

478 CREATE TABLE some_table ( 

479 id INTEGER NOT NULL, 

480 data INTEGER, 

481 PRIMARY KEY (id), 

482 UNIQUE (id, data) ON CONFLICT IGNORE 

483 ) 

484 

485 

486When using the :paramref:`_schema.Column.unique` 

487flag to add a UNIQUE constraint 

488to a single column, the ``sqlite_on_conflict_unique`` parameter can 

489be added to the :class:`_schema.Column` as well, which will be added to the 

490UNIQUE constraint in the DDL:: 

491 

492 some_table = Table( 

493 "some_table", 

494 metadata, 

495 Column("id", Integer, primary_key=True), 

496 Column( 

497 "data", Integer, unique=True, sqlite_on_conflict_unique="IGNORE" 

498 ), 

499 ) 

500 

501rendering: 

502 

503.. sourcecode:: sql 

504 

505 CREATE TABLE some_table ( 

506 id INTEGER NOT NULL, 

507 data INTEGER, 

508 PRIMARY KEY (id), 

509 UNIQUE (data) ON CONFLICT IGNORE 

510 ) 

511 

512To apply the FAIL algorithm for a NOT NULL constraint, 

513``sqlite_on_conflict_not_null`` is used:: 

514 

515 some_table = Table( 

516 "some_table", 

517 metadata, 

518 Column("id", Integer, primary_key=True), 

519 Column( 

520 "data", Integer, nullable=False, sqlite_on_conflict_not_null="FAIL" 

521 ), 

522 ) 

523 

524this renders the column inline ON CONFLICT phrase: 

525 

526.. sourcecode:: sql 

527 

528 CREATE TABLE some_table ( 

529 id INTEGER NOT NULL, 

530 data INTEGER NOT NULL ON CONFLICT FAIL, 

531 PRIMARY KEY (id) 

532 ) 

533 

534 

535Similarly, for an inline primary key, use ``sqlite_on_conflict_primary_key``:: 

536 

537 some_table = Table( 

538 "some_table", 

539 metadata, 

540 Column( 

541 "id", 

542 Integer, 

543 primary_key=True, 

544 sqlite_on_conflict_primary_key="FAIL", 

545 ), 

546 ) 

547 

548SQLAlchemy renders the PRIMARY KEY constraint separately, so the conflict 

549resolution algorithm is applied to the constraint itself: 

550 

551.. sourcecode:: sql 

552 

553 CREATE TABLE some_table ( 

554 id INTEGER NOT NULL, 

555 PRIMARY KEY (id) ON CONFLICT FAIL 

556 ) 

557 

558.. _sqlite_on_conflict_insert: 

559 

560INSERT...ON CONFLICT (Upsert) 

561----------------------------- 

562 

563.. seealso:: This section describes the :term:`DML` version of "ON CONFLICT" for 

564 SQLite, which occurs within an INSERT statement. For "ON CONFLICT" as 

565 applied to a CREATE TABLE statement, see :ref:`sqlite_on_conflict_ddl`. 

566 

567From version 3.24.0 onwards, SQLite supports "upserts" (update or insert) 

568of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` 

569statement. A candidate row will only be inserted if that row does not violate 

570any unique or primary key constraints. In the case of a unique constraint violation, a 

571secondary action can occur which can be either "DO UPDATE", indicating that 

572the data in the target row should be updated, or "DO NOTHING", which indicates 

573to silently skip this row. 

574 

575Conflicts are determined using columns that are part of existing unique 

576constraints and indexes. These constraints are identified by stating the 

577columns and conditions that comprise the indexes. 

578 

579SQLAlchemy provides ``ON CONFLICT`` support via the SQLite-specific 

580:func:`_sqlite.insert()` function, which provides 

581the generative methods :meth:`_sqlite.Insert.on_conflict_do_update` 

582and :meth:`_sqlite.Insert.on_conflict_do_nothing`: 

583 

584.. sourcecode:: pycon+sql 

585 

586 >>> from sqlalchemy.dialects.sqlite import insert 

587 

588 >>> insert_stmt = insert(my_table).values( 

589 ... id="some_existing_id", data="inserted value" 

590 ... ) 

591 

592 >>> do_update_stmt = insert_stmt.on_conflict_do_update( 

593 ... index_elements=["id"], set_=dict(data="updated value") 

594 ... ) 

595 

596 >>> print(do_update_stmt) 

597 {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) 

598 ON CONFLICT (id) DO UPDATE SET data = ?{stop} 

599 

600 >>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["id"]) 

601 

602 >>> print(do_nothing_stmt) 

603 {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) 

604 ON CONFLICT (id) DO NOTHING 

605 

606.. versionadded:: 1.4 

607 

608.. seealso:: 

609 

610 `Upsert 

611 <https://sqlite.org/lang_UPSERT.html>`_ 

612 - in the SQLite documentation. 

613 

614 

615Specifying the Target 

616^^^^^^^^^^^^^^^^^^^^^ 

617 

618Both methods supply the "target" of the conflict using column inference: 

619 

620* The :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` argument 

621 specifies a sequence containing string column names, :class:`_schema.Column` 

622 objects, and/or SQL expression elements, which would identify a unique index 

623 or unique constraint. 

624 

625* When using :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` 

626 to infer an index, a partial index can be inferred by also specifying the 

627 :paramref:`_sqlite.Insert.on_conflict_do_update.index_where` parameter: 

628 

629 .. sourcecode:: pycon+sql 

630 

631 >>> stmt = insert(my_table).values(user_email="a@b.com", data="inserted data") 

632 

633 >>> do_update_stmt = stmt.on_conflict_do_update( 

634 ... index_elements=[my_table.c.user_email], 

635 ... index_where=my_table.c.user_email.like("%@gmail.com"), 

636 ... set_=dict(data=stmt.excluded.data), 

637 ... ) 

638 

639 >>> print(do_update_stmt) 

640 {printsql}INSERT INTO my_table (data, user_email) VALUES (?, ?) 

641 ON CONFLICT (user_email) 

642 WHERE user_email LIKE '%@gmail.com' 

643 DO UPDATE SET data = excluded.data 

644 

645The SET Clause 

646^^^^^^^^^^^^^^^ 

647 

648``ON CONFLICT...DO UPDATE`` is used to perform an update of the already 

649existing row, using any combination of new values as well as values 

650from the proposed insertion. These values are specified using the 

651:paramref:`_sqlite.Insert.on_conflict_do_update.set_` parameter. This 

652parameter accepts a dictionary which consists of direct values 

653for UPDATE: 

654 

655.. sourcecode:: pycon+sql 

656 

657 >>> stmt = insert(my_table).values(id="some_id", data="inserted value") 

658 

659 >>> do_update_stmt = stmt.on_conflict_do_update( 

660 ... index_elements=["id"], set_=dict(data="updated value") 

661 ... ) 

662 

663 >>> print(do_update_stmt) 

664 {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) 

665 ON CONFLICT (id) DO UPDATE SET data = ? 

666 

667.. warning:: 

668 

669 The :meth:`_sqlite.Insert.on_conflict_do_update` method does **not** take 

670 into account Python-side default UPDATE values or generation functions, 

671 e.g. those specified using :paramref:`_schema.Column.onupdate`. These 

672 values will not be exercised for an ON CONFLICT style of UPDATE, unless 

673 they are manually specified in the 

674 :paramref:`_sqlite.Insert.on_conflict_do_update.set_` dictionary. 

675 

676Updating using the Excluded INSERT Values 

677^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

678 

679In order to refer to the proposed insertion row, the special alias 

680:attr:`~.sqlite.Insert.excluded` is available as an attribute on 

681the :class:`_sqlite.Insert` object; this object creates an "excluded." prefix 

682on a column, that informs the DO UPDATE to update the row with the value that 

683would have been inserted had the constraint not failed: 

684 

685.. sourcecode:: pycon+sql 

686 

687 >>> stmt = insert(my_table).values( 

688 ... id="some_id", data="inserted value", author="jlh" 

689 ... ) 

690 

691 >>> do_update_stmt = stmt.on_conflict_do_update( 

692 ... index_elements=["id"], 

693 ... set_=dict(data="updated value", author=stmt.excluded.author), 

694 ... ) 

695 

696 >>> print(do_update_stmt) 

697 {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) 

698 ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author 

699 

700Additional WHERE Criteria 

701^^^^^^^^^^^^^^^^^^^^^^^^^ 

702 

703The :meth:`_sqlite.Insert.on_conflict_do_update` method also accepts 

704a WHERE clause using the :paramref:`_sqlite.Insert.on_conflict_do_update.where` 

705parameter, which will limit those rows which receive an UPDATE: 

706 

707.. sourcecode:: pycon+sql 

708 

709 >>> stmt = insert(my_table).values( 

710 ... id="some_id", data="inserted value", author="jlh" 

711 ... ) 

712 

713 >>> on_update_stmt = stmt.on_conflict_do_update( 

714 ... index_elements=["id"], 

715 ... set_=dict(data="updated value", author=stmt.excluded.author), 

716 ... where=(my_table.c.status == 2), 

717 ... ) 

718 >>> print(on_update_stmt) 

719 {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) 

720 ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author 

721 WHERE my_table.status = ? 

722 

723 

724Skipping Rows with DO NOTHING 

725^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 

726 

727``ON CONFLICT`` may be used to skip inserting a row entirely 

728if any conflict with a unique constraint occurs; below this is illustrated 

729using the :meth:`_sqlite.Insert.on_conflict_do_nothing` method: 

730 

731.. sourcecode:: pycon+sql 

732 

733 >>> stmt = insert(my_table).values(id="some_id", data="inserted value") 

734 >>> stmt = stmt.on_conflict_do_nothing(index_elements=["id"]) 

735 >>> print(stmt) 

736 {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING 

737 

738 

739If ``DO NOTHING`` is used without specifying any columns or constraint, 

740it has the effect of skipping the INSERT for any unique violation which 

741occurs: 

742 

743.. sourcecode:: pycon+sql 

744 

745 >>> stmt = insert(my_table).values(id="some_id", data="inserted value") 

746 >>> stmt = stmt.on_conflict_do_nothing() 

747 >>> print(stmt) 

748 {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT DO NOTHING 

749 

750.. _sqlite_type_reflection: 

751 

752Type Reflection 

753--------------- 

754 

755SQLite types are unlike those of most other database backends, in that 

756the string name of the type usually does not correspond to a "type" in a 

757one-to-one fashion. Instead, SQLite links per-column typing behavior 

758to one of five so-called "type affinities" based on a string matching 

759pattern for the type. 

760 

761SQLAlchemy's reflection process, when inspecting types, uses a simple 

762lookup table to link the keywords returned to provided SQLAlchemy types. 

763This lookup table is present within the SQLite dialect as it is for all 

764other dialects. However, the SQLite dialect has a different "fallback" 

765routine for when a particular type name is not located in the lookup map; 

766it instead implements the SQLite "type affinity" scheme located at 

767https://www.sqlite.org/datatype3.html section 2.1. 

768 

769The provided typemap will make direct associations from an exact string 

770name match for the following types: 

771 

772:class:`_types.BIGINT`, :class:`_types.BLOB`, 

773:class:`_types.BOOLEAN`, :class:`_types.BOOLEAN`, 

774:class:`_types.CHAR`, :class:`_types.DATE`, 

775:class:`_types.DATETIME`, :class:`_types.FLOAT`, 

776:class:`_types.DECIMAL`, :class:`_types.FLOAT`, 

777:class:`_types.INTEGER`, :class:`_types.INTEGER`, 

778:class:`_types.NUMERIC`, :class:`_types.REAL`, 

779:class:`_types.SMALLINT`, :class:`_types.TEXT`, 

780:class:`_types.TIME`, :class:`_types.TIMESTAMP`, 

781:class:`_types.VARCHAR`, :class:`_types.NVARCHAR`, 

782:class:`_types.NCHAR` 

783 

784When a type name does not match one of the above types, the "type affinity" 

785lookup is used instead: 

786 

787* :class:`_types.INTEGER` is returned if the type name includes the 

788 string ``INT`` 

789* :class:`_types.TEXT` is returned if the type name includes the 

790 string ``CHAR``, ``CLOB`` or ``TEXT`` 

791* :class:`_types.NullType` is returned if the type name includes the 

792 string ``BLOB`` 

793* :class:`_types.REAL` is returned if the type name includes the string 

794 ``REAL``, ``FLOA`` or ``DOUB``. 

795* Otherwise, the :class:`_types.NUMERIC` type is used. 

796 

797.. _sqlite_partial_index: 

798 

799Partial Indexes 

800--------------- 

801 

802A partial index, e.g. one which uses a WHERE clause, can be specified 

803with the DDL system using the argument ``sqlite_where``:: 

804 

805 tbl = Table("testtbl", m, Column("data", Integer)) 

806 idx = Index( 

807 "test_idx1", 

808 tbl.c.data, 

809 sqlite_where=and_(tbl.c.data > 5, tbl.c.data < 10), 

810 ) 

811 

812The index will be rendered at create time as: 

813 

814.. sourcecode:: sql 

815 

816 CREATE INDEX test_idx1 ON testtbl (data) 

817 WHERE data > 5 AND data < 10 

818 

819.. _sqlite_dotted_column_names: 

820 

821Dotted Column Names 

822------------------- 

823 

824Using table or column names that explicitly have periods in them is 

825**not recommended**. While this is generally a bad idea for relational 

826databases in general, as the dot is a syntactically significant character, 

827the SQLite driver up until version **3.10.0** of SQLite has a bug which 

828requires that SQLAlchemy filter out these dots in result sets. 

829 

830The bug, entirely outside of SQLAlchemy, can be illustrated thusly:: 

831 

832 import sqlite3 

833 

834 assert sqlite3.sqlite_version_info < ( 

835 3, 

836 10, 

837 0, 

838 ), "bug is fixed in this version" 

839 

840 conn = sqlite3.connect(":memory:") 

841 cursor = conn.cursor() 

842 

843 cursor.execute("create table x (a integer, b integer)") 

844 cursor.execute("insert into x (a, b) values (1, 1)") 

845 cursor.execute("insert into x (a, b) values (2, 2)") 

846 

847 cursor.execute("select x.a, x.b from x") 

848 assert [c[0] for c in cursor.description] == ["a", "b"] 

849 

850 cursor.execute( 

851 """ 

852 select x.a, x.b from x where a=1 

853 union 

854 select x.a, x.b from x where a=2 

855 """ 

856 ) 

857 assert [c[0] for c in cursor.description] == ["a", "b"], [ 

858 c[0] for c in cursor.description 

859 ] 

860 

861The second assertion fails: 

862 

863.. sourcecode:: text 

864 

865 Traceback (most recent call last): 

866 File "test.py", line 19, in <module> 

867 [c[0] for c in cursor.description] 

868 AssertionError: ['x.a', 'x.b'] 

869 

870Where above, the driver incorrectly reports the names of the columns 

871including the name of the table, which is entirely inconsistent vs. 

872when the UNION is not present. 

873 

874SQLAlchemy relies upon column names being predictable in how they match 

875to the original statement, so the SQLAlchemy dialect has no choice but 

876to filter these out:: 

877 

878 

879 from sqlalchemy import create_engine 

880 

881 eng = create_engine("sqlite://") 

882 conn = eng.connect() 

883 

884 conn.exec_driver_sql("create table x (a integer, b integer)") 

885 conn.exec_driver_sql("insert into x (a, b) values (1, 1)") 

886 conn.exec_driver_sql("insert into x (a, b) values (2, 2)") 

887 

888 result = conn.exec_driver_sql("select x.a, x.b from x") 

889 assert result.keys() == ["a", "b"] 

890 

891 result = conn.exec_driver_sql( 

892 """ 

893 select x.a, x.b from x where a=1 

894 union 

895 select x.a, x.b from x where a=2 

896 """ 

897 ) 

898 assert result.keys() == ["a", "b"] 

899 

900Note that above, even though SQLAlchemy filters out the dots, *both 

901names are still addressable*:: 

902 

903 >>> row = result.first() 

904 >>> row["a"] 

905 1 

906 >>> row["x.a"] 

907 1 

908 >>> row["b"] 

909 1 

910 >>> row["x.b"] 

911 1 

912 

913Therefore, the workaround applied by SQLAlchemy only impacts 

914:meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` in the public API. In 

915the very specific case where an application is forced to use column names that 

916contain dots, and the functionality of :meth:`_engine.CursorResult.keys` and 

917:meth:`.Row.keys()` is required to return these dotted names unmodified, 

918the ``sqlite_raw_colnames`` execution option may be provided, either on a 

919per-:class:`_engine.Connection` basis:: 

920 

921 result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql( 

922 """ 

923 select x.a, x.b from x where a=1 

924 union 

925 select x.a, x.b from x where a=2 

926 """ 

927 ) 

928 assert result.keys() == ["x.a", "x.b"] 

929 

930or on a per-:class:`_engine.Engine` basis:: 

931 

932 engine = create_engine( 

933 "sqlite://", execution_options={"sqlite_raw_colnames": True} 

934 ) 

935 

936When using the per-:class:`_engine.Engine` execution option, note that 

937**Core and ORM queries that use UNION may not function properly**. 

938 

939SQLite-specific table options 

940----------------------------- 

941 

942One option for CREATE TABLE is supported directly by the SQLite 

943dialect in conjunction with the :class:`_schema.Table` construct: 

944 

945* ``WITHOUT ROWID``:: 

946 

947 Table("some_table", metadata, ..., sqlite_with_rowid=False) 

948 

949* 

950 ``STRICT``:: 

951 

952 Table("some_table", metadata, ..., sqlite_strict=True) 

953 

954 .. versionadded:: 2.0.37 

955 

956.. seealso:: 

957 

958 `SQLite CREATE TABLE options 

959 <https://www.sqlite.org/lang_createtable.html>`_ 

960 

961.. _sqlite_include_internal: 

962 

963Reflecting internal schema tables 

964---------------------------------- 

965 

966Reflection methods that return lists of tables will omit so-called 

967"SQLite internal schema object" names, which are considered by SQLite 

968as any object name that is prefixed with ``sqlite_``. An example of 

969such an object is the ``sqlite_sequence`` table that's generated when 

970the ``AUTOINCREMENT`` column parameter is used. In order to return 

971these objects, the parameter ``sqlite_include_internal=True`` may be 

972passed to methods such as :meth:`_schema.MetaData.reflect` or 

973:meth:`.Inspector.get_table_names`. 

974 

975.. versionadded:: 2.0 Added the ``sqlite_include_internal=True`` parameter. 

976 Previously, these tables were not ignored by SQLAlchemy reflection 

977 methods. 

978 

979.. note:: 

980 

981 The ``sqlite_include_internal`` parameter does not refer to the 

982 "system" tables that are present in schemas such as ``sqlite_master``. 

983 

984.. seealso:: 

985 

986 `SQLite Internal Schema Objects <https://www.sqlite.org/fileformat2.html#intschema>`_ - in the SQLite 

987 documentation. 

988 

989''' # noqa 

990from __future__ import annotations 

991 

992import datetime 

993import numbers 

994import re 

995from typing import Optional 

996 

997from .json import JSON 

998from .json import JSONIndexType 

999from .json import JSONPathType 

1000from ... import exc 

1001from ... import schema as sa_schema 

1002from ... import sql 

1003from ... import text 

1004from ... import types as sqltypes 

1005from ... import util 

1006from ...engine import default 

1007from ...engine import processors 

1008from ...engine import reflection 

1009from ...engine.reflection import ReflectionDefaults 

1010from ...sql import coercions 

1011from ...sql import compiler 

1012from ...sql import elements 

1013from ...sql import roles 

1014from ...sql import schema 

1015from ...types import BLOB # noqa 

1016from ...types import BOOLEAN # noqa 

1017from ...types import CHAR # noqa 

1018from ...types import DECIMAL # noqa 

1019from ...types import FLOAT # noqa 

1020from ...types import INTEGER # noqa 

1021from ...types import NUMERIC # noqa 

1022from ...types import REAL # noqa 

1023from ...types import SMALLINT # noqa 

1024from ...types import TEXT # noqa 

1025from ...types import TIMESTAMP # noqa 

1026from ...types import VARCHAR # noqa 

1027 

1028 

1029class _SQliteJson(JSON): 

1030 def result_processor(self, dialect, coltype): 

1031 default_processor = super().result_processor(dialect, coltype) 

1032 

1033 def process(value): 

1034 try: 

1035 return default_processor(value) 

1036 except TypeError: 

1037 if isinstance(value, numbers.Number): 

1038 return value 

1039 else: 

1040 raise 

1041 

1042 return process 

1043 

1044 

1045class _DateTimeMixin: 

1046 _reg = None 

1047 _storage_format = None 

1048 

1049 def __init__(self, storage_format=None, regexp=None, **kw): 

1050 super().__init__(**kw) 

1051 if regexp is not None: 

1052 self._reg = re.compile(regexp) 

1053 if storage_format is not None: 

1054 self._storage_format = storage_format 

1055 

1056 @property 

1057 def format_is_text_affinity(self): 

1058 """return True if the storage format will automatically imply 

1059 a TEXT affinity. 

1060 

1061 If the storage format contains no non-numeric characters, 

1062 it will imply a NUMERIC storage format on SQLite; in this case, 

1063 the type will generate its DDL as DATE_CHAR, DATETIME_CHAR, 

1064 TIME_CHAR. 

1065 

1066 """ 

1067 spec = self._storage_format % { 

1068 "year": 0, 

1069 "month": 0, 

1070 "day": 0, 

1071 "hour": 0, 

1072 "minute": 0, 

1073 "second": 0, 

1074 "microsecond": 0, 

1075 } 

1076 return bool(re.search(r"[^0-9]", spec)) 

1077 

1078 def adapt(self, cls, **kw): 

1079 if issubclass(cls, _DateTimeMixin): 

1080 if self._storage_format: 

1081 kw["storage_format"] = self._storage_format 

1082 if self._reg: 

1083 kw["regexp"] = self._reg 

1084 return super().adapt(cls, **kw) 

1085 

1086 def literal_processor(self, dialect): 

1087 bp = self.bind_processor(dialect) 

1088 

1089 def process(value): 

1090 return "'%s'" % bp(value) 

1091 

1092 return process 

1093 

1094 

1095class DATETIME(_DateTimeMixin, sqltypes.DateTime): 

1096 r"""Represent a Python datetime object in SQLite using a string. 

1097 

1098 The default string storage format is:: 

1099 

1100 "%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" 

1101 

1102 e.g.: 

1103 

1104 .. sourcecode:: text 

1105 

1106 2021-03-15 12:05:57.105542 

1107 

1108 The incoming storage format is by default parsed using the 

1109 Python ``datetime.fromisoformat()`` function. 

1110 

1111 .. versionchanged:: 2.0 ``datetime.fromisoformat()`` is used for default 

1112 datetime string parsing. 

1113 

1114 The storage format can be customized to some degree using the 

1115 ``storage_format`` and ``regexp`` parameters, such as:: 

1116 

1117 import re 

1118 from sqlalchemy.dialects.sqlite import DATETIME 

1119 

1120 dt = DATETIME( 

1121 storage_format=( 

1122 "%(year)04d/%(month)02d/%(day)02d %(hour)02d:%(minute)02d:%(second)02d" 

1123 ), 

1124 regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)", 

1125 ) 

1126 

1127 :param truncate_microseconds: when ``True`` microseconds will be truncated 

1128 from the datetime. Can't be specified together with ``storage_format`` 

1129 or ``regexp``. 

1130 

1131 :param storage_format: format string which will be applied to the dict 

1132 with keys year, month, day, hour, minute, second, and microsecond. 

1133 

1134 :param regexp: regular expression which will be applied to incoming result 

1135 rows, replacing the use of ``datetime.fromisoformat()`` to parse incoming 

1136 strings. If the regexp contains named groups, the resulting match dict is 

1137 applied to the Python datetime() constructor as keyword arguments. 

1138 Otherwise, if positional groups are used, the datetime() constructor 

1139 is called with positional arguments via 

1140 ``*map(int, match_obj.groups(0))``. 

1141 

1142 """ # noqa 

1143 

1144 _storage_format = ( 

1145 "%(year)04d-%(month)02d-%(day)02d " 

1146 "%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" 

1147 ) 

1148 

1149 def __init__(self, *args, **kwargs): 

1150 truncate_microseconds = kwargs.pop("truncate_microseconds", False) 

1151 super().__init__(*args, **kwargs) 

1152 if truncate_microseconds: 

1153 assert "storage_format" not in kwargs, ( 

1154 "You can specify only " 

1155 "one of truncate_microseconds or storage_format." 

1156 ) 

1157 assert "regexp" not in kwargs, ( 

1158 "You can specify only one of " 

1159 "truncate_microseconds or regexp." 

1160 ) 

1161 self._storage_format = ( 

1162 "%(year)04d-%(month)02d-%(day)02d " 

1163 "%(hour)02d:%(minute)02d:%(second)02d" 

1164 ) 

1165 

1166 def bind_processor(self, dialect): 

1167 datetime_datetime = datetime.datetime 

1168 datetime_date = datetime.date 

1169 format_ = self._storage_format 

1170 

1171 def process(value): 

1172 if value is None: 

1173 return None 

1174 elif isinstance(value, datetime_datetime): 

1175 return format_ % { 

1176 "year": value.year, 

1177 "month": value.month, 

1178 "day": value.day, 

1179 "hour": value.hour, 

1180 "minute": value.minute, 

1181 "second": value.second, 

1182 "microsecond": value.microsecond, 

1183 } 

1184 elif isinstance(value, datetime_date): 

1185 return format_ % { 

1186 "year": value.year, 

1187 "month": value.month, 

1188 "day": value.day, 

1189 "hour": 0, 

1190 "minute": 0, 

1191 "second": 0, 

1192 "microsecond": 0, 

1193 } 

1194 else: 

1195 raise TypeError( 

1196 "SQLite DateTime type only accepts Python " 

1197 "datetime and date objects as input." 

1198 ) 

1199 

1200 return process 

1201 

1202 def result_processor(self, dialect, coltype): 

1203 if self._reg: 

1204 return processors.str_to_datetime_processor_factory( 

1205 self._reg, datetime.datetime 

1206 ) 

1207 else: 

1208 return processors.str_to_datetime 

1209 

1210 

1211class DATE(_DateTimeMixin, sqltypes.Date): 

1212 r"""Represent a Python date object in SQLite using a string. 

1213 

1214 The default string storage format is:: 

1215 

1216 "%(year)04d-%(month)02d-%(day)02d" 

1217 

1218 e.g.: 

1219 

1220 .. sourcecode:: text 

1221 

1222 2011-03-15 

1223 

1224 The incoming storage format is by default parsed using the 

1225 Python ``date.fromisoformat()`` function. 

1226 

1227 .. versionchanged:: 2.0 ``date.fromisoformat()`` is used for default 

1228 date string parsing. 

1229 

1230 

1231 The storage format can be customized to some degree using the 

1232 ``storage_format`` and ``regexp`` parameters, such as:: 

1233 

1234 import re 

1235 from sqlalchemy.dialects.sqlite import DATE 

1236 

1237 d = DATE( 

1238 storage_format="%(month)02d/%(day)02d/%(year)04d", 

1239 regexp=re.compile("(?P<month>\d+)/(?P<day>\d+)/(?P<year>\d+)"), 

1240 ) 

1241 

1242 :param storage_format: format string which will be applied to the 

1243 dict with keys year, month, and day. 

1244 

1245 :param regexp: regular expression which will be applied to 

1246 incoming result rows, replacing the use of ``date.fromisoformat()`` to 

1247 parse incoming strings. If the regexp contains named groups, the resulting 

1248 match dict is applied to the Python date() constructor as keyword 

1249 arguments. Otherwise, if positional groups are used, the date() 

1250 constructor is called with positional arguments via 

1251 ``*map(int, match_obj.groups(0))``. 

1252 

1253 """ 

1254 

1255 _storage_format = "%(year)04d-%(month)02d-%(day)02d" 

1256 

1257 def bind_processor(self, dialect): 

1258 datetime_date = datetime.date 

1259 format_ = self._storage_format 

1260 

1261 def process(value): 

1262 if value is None: 

1263 return None 

1264 elif isinstance(value, datetime_date): 

1265 return format_ % { 

1266 "year": value.year, 

1267 "month": value.month, 

1268 "day": value.day, 

1269 } 

1270 else: 

1271 raise TypeError( 

1272 "SQLite Date type only accepts Python " 

1273 "date objects as input." 

1274 ) 

1275 

1276 return process 

1277 

1278 def result_processor(self, dialect, coltype): 

1279 if self._reg: