Codecov Report

❌ Patch coverage is 95.65217% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.39%. Comparing base (5873578) to head (0486988).
⚠️ Report is 1 commits behind head on main.

@@            Coverage Diff             @@
##             main    #2636      +/-   ##
==========================================
+ Coverage   90.37%   90.39%   +0.01%     
==========================================
  Files          52       52              
  Lines        7983     8017      +34     
==========================================
+ Hits         7215     7247      +32     
- Misses        768      770       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

I pitched Claude the idea of having the plugin function able to yield conn with a completely new connection which would then be used by the rest of the stack, to allow for fancy ideas like having per-actor connections that persist across requests, or something like https://github.com/datasette/datasette-transactions

Quoting the response in full because it's worth recording somewhere:

This is a fascinating idea. Let me think through it carefully.

---

yield conn --- Connection Substitution via wrap_write

The idea: if the generator yields a connection object instead of None, Datasette uses that yielded connection for the write instead of the default shared write connection. This would let a plugin:

1. Hold open a dedicated connection per actor --- reused across requests
2. Hold a transaction open across multiple HTTP requests --- exactly what datasette-transactions does, but without needing to bypass execute_write_fn entirely

How datasette-transactions works today

The plugin completely sidesteps Datasette's write system. It:

• Opens its own sqlite3.connect(db.path, isolation_level=None, check_same_thread=False) connections
• Manages them in a global TransactionManager singleton
• Registers its own routes (/-/transactions/begin/..., /-/transactions/{uuid}, etc.)
• Never touches execute_write_fn at all --- it runs SQL directly against its own connections

This means writes done through datasette-transactions don't trigger any of the normal Datasette write hooks --- no wrap_write, no track_event. They're invisible to the rest of the plugin ecosystem.

What yield conn could enable

If wrap_write allowed yielding a substitute connection:

@hookimpl
def wrap_write(datasette, database, request):
    # Look up whether this actor has an open transaction
    tx_state = get_transaction_for_actor(request)
    if tx_state is None:
        return None  # Use default connection

    def wrapper(conn):
        # Yield a different connection --- this one has an open transaction
        yield tx_state.connection

    return wrapper

Then writes going through the normal Datasette API (row insert/update/delete/drop, canned queries) would automatically be redirected to the actor's dedicated transactional connection. This would mean:

• The existing Datasette table UI and JSON API would just work inside transactions
• Other wrap_write plugins (audit, change groups, authorizer) would still fire
• track_event would still fire
• No need for separate routes or a custom SQL execution endpoint

The tricky parts

1. The write thread model breaks down. Today, execute_write_fn serializes everything through one connection on one dedicated thread. If a plugin yields a different connection, that connection might be owned by a different thread, or might need to live longer than a single execute_write_fn call. The yielded connection would need check_same_thread=False and its own locking.

2. Transaction boundary management. The with conn: transaction wrapper in _execute_writes and the non-threaded path would need to be skipped or handled differently when a substitute connection is in use --- the plugin is managing the transaction itself. The transaction parameter being passed to the hook helps here: the plugin can see it and the hook could signal "I'm managing transactions myself."

3. Connection lifetime. The substitute connection outlives a single write call. Who closes it? The plugin would need to manage lifecycle (begin, commit/rollback, close) through its own endpoints, just like datasette-transactions does today --- but the execution of writes flows through Datasette's normal path.

4. prepare_connection hooks. Datasette calls _prepare_connection on the default write connection. A substitute connection from a plugin wouldn't have had those hooks applied unless the plugin explicitly calls datasette._prepare_connection(conn, database) or Datasette does it automatically.

Implementation sketch

The change to _apply_wrap_write would be small. Currently:

result = fn(conn)  # always uses the original conn

With yield conn support:

yielded = next(gen)
# If generator yielded a connection, use that instead
effective_conn = yielded if yielded is not None else conn
result = fn(effective_conn)

But the harder question is whether to skip the outer transaction wrapping (with conn:) when a substitute connection is used. That probably needs to be a separate flag or convention.

Is this worth building now?

I think the concept is powerful and the implementation change to _apply_wrap_write is minimal. But the real complexity is in the interaction with the write thread and transaction management --- specifically, when a plugin yields a substitute connection:

• Should execute_write_fn still send the task to the write thread? (Probably yes, to maintain serialization)
• Should the with conn: transaction wrapper use the substitute connection? (Probably not --- the plugin owns the transaction)
• Should _prepare_connection be called on substitute connections? (Probably --- but only once, not per-write)

Here's the plugin documentation Claude wrote: https://github.com/simonw/datasette/blob/ce1b4e509b39ae9b643640a1995b67e549cc13ea/docs/plugin_hooks.rst#write_wrapperdatasette-database-request-transaction