gh-137205: Document how to safely use PRAGMA during SQLite transactions

[erlend-aasland]

cc. @zzzeek

• Issue: Sending the sqlite3 autocommit parameter renders this PRAGMA command a no-op #137205

---

📚 Documentation preview 📚: https://cpython-previews--137505.org.readthedocs.build/

[StanFromIreland]

Looks fine to me.

PS. You may have accidentally added the 3.12 back port label.

[erlend-aasland]

Looks fine to me.

Thanks for the review.

PS. You may have accidentally added the 3.12 back port label.

autocommit was added in 3.12; I prefer to also amend the 3.12 docs.

@zzzeek: would you like to review this?

[erlend-aasland]

I made some amendments:

• 345043f bco. @zzzeek's remark
• 000e4c5 bco. @layday's suggestion

[erlend-aasland]

cc. @layday

[zzzeek]

I wish the state of affairs was better here, but while I can think of various API features that would make this less klunky, I dont think any of them would be worth it, so here we are.

[erlend-aasland]

I don't think a decorator is worth it. Since PRAGMAs are mostly used during the setup of a database connection, I think @layday's approach is the most sane: connect using autocommit=False, execute your PRAGMAs, then set the autocommit attr to whatever suits your application best.

[zzzeek]

my API features would be either:

1. a context manager

with conn.autocommit_block:
    # ...

2. a PRAGMA method

   cursor.pragma("FOREIGN KEYS=ON")

3. include commonly needed pragmas as part of connect() . A bitwise enum is sort of nice here but doesnt work for pragmas that have numeric arguments

   # doesnt work for every kind of pragma but looks nice
   conn = sqlite3.connect(...., pragmas=Pragma.FOREIGN_KEYS_ON | Pragma.JOURNAL_MODE_PERSIST)

in your comment I assume you meant "connect with autocommit=True".

[erlend-aasland]

1. It's a nice idea, but we already have a context manager for transactions. I'm not sure it is worth it to introduce a context manager for the opposite.
2. & 3: I would prefer to not add more APIs with side effects. Moreover, I would prefer to not manage an enum of supported PRAGMAs.

[...] in your comment I assume you meant "connect with autocommit=True".

Yes, thanks.

[layday]

There's a few things I don't like about the proposed workaround:

• It's rather verbose. Pragmas are typically only set once on connect, so it's sufficient to initialise connect with autocommit=True before flipping it off.
• It has the appearance of a bodge, though it's decidedly less bad than manually executing a ROLLBACK or COMMIT followed by a BEGIN.
• Entering autocommit implicitly emits a COMMIT, which has a 'spooky action at a distance' feel to it.
• Enabling foreign keys is more important than any Python-specific recommendation made by the docs, and if autocommit=False doesn't support the FK pragma out of the box, that vastly reduces its usefulness.

I don't really know what'd work better, but I'm gravitating towards an init hook that'd be executed before the first BEGIN, mirroring SQLA's listens_for idiom. I don't think that's in the scope of this PR though, so I'd personally be happy if the suggestion was rephrased to:

Suggested change

	cur = con.cursor()
	* Else, initialize the connection with ``autocommit=True``
	and set the :attr:`!autocommit` attribute to ``False``
	after executing the ``PRAGMA`` statement:
	.. testcode::
	con = sqlite3.connect(":memory:", autocommit=True)
	cur.execute("PRAGMA foreign_keys = ON")
	con.autocommit = False # Enable implicit transaction control.

---

a context manager

I don't think an autocommit context manager is generally useful, and I can see it being misused to break out of a transaction for any number of reasons, e.g. to fetch changes made by another connection with WAL on.

a PRAGMA method

I don't know how this would work, but SQLite has pragmas which have no effect outside of a transaction - defer_foreign_keys is one of them. If the idea is that pragma(...) would exit a transaction to set the provided pragma, then the driver's gonna have to encode specific knowledge of SQLite pragmas.

[SamsiFPV]

What's the state on this? I'd like to see this in the docs asap, so others don't trip over this like I did.