TL;DR:

• To run multiple SQL statements and/or DDL statements in a transactional manner, use sql.planner.WithInternalExecutor(), sqlutil.InternalExecutorFactory.TxnWithExecutor(), or descs.CollectionFactory.TxnWithExecutor(). (example)
• To run other single statements under a planner context, use query functions under planner (e.g. sql.planner.QueryRowEx() or sql.planner.WithInternalExecutor())
• Otherwise, use sqlutil.InternalExecutorFactory.MakeInternalExecutorWithoutTxn().

We'd like to migrate the existing usages of internal executor to the interfaces above. Once these are all using the new interfaces, we will remove the txn parameter in the query functions (e.g. ie.ExecEx()) and use ie.extraTxnState.txn.

Motivation

The previous design of the internal executor is either incorrect or inefficient when running with an outer txn, as it always creates a new set of txn-related metadata (such as descriptor collection and schema change job records) for its child conn executor. This is not intuitive, since it violates a rather deep principle that these metadata and a txn have a 1:1 relationship. The lack of such coupling has caused issues such as filetable corruption, unnecessary rescanning of the descriptors, etc.

New interfaces

The new internal executor interfaces (implemented in #82477, #86427, and parts of #87067) are meant to solve this problem. They ensure that the internal executor, if used with an outer txn, is bound with the correct metadata, which will be passed to the child conn executor. When the internal executor is closed, the sql transaction will be committed.

Epic: CRDB-19135

Jira issue: CRDB-21069

Epic CRDB-19135