feat: update transaction documentation

docs/cli.md

@@ -158,29 +158,30 @@ module.exports = {
 };
 ```
 
-The following is an example of a migration that performs two changes in the database, using an automatically-managed transaction to ensure that all instructions are successfully executed or rolled back in case of failure:
+The following is an example of a migration that performs two changes in the database, 
+using an automatically-managed transaction to ensure that all instructions are successfully executed or rolled back in case of failure:
 
 ```js
 const { DataTypes } = require('@sequelize/core');
 
 module.exports = {
   up: (queryInterface, Sequelize) => {
-    return queryInterface.sequelize.transaction(t => {
+    return queryInterface.sequelize.transaction(transaction => {
       return Promise.all([
         queryInterface.addColumn('Person', 'petName', {
           type: DataTypes.STRING
-        }, { transaction: t }),
+        }, { transaction }),
         queryInterface.addColumn('Person', 'favoriteColor', {
           type: DataTypes.STRING,
-        }, { transaction: t })
+        }, { transaction })
       ]);
     });
   },
   down: (queryInterface, Sequelize) => {
-    return queryInterface.sequelize.transaction(t => {
+    return queryInterface.sequelize.transaction(transaction => {
       return Promise.all([
-        queryInterface.removeColumn('Person', 'petName', { transaction: t }),
-        queryInterface.removeColumn('Person', 'favoriteColor', { transaction: t })
+        queryInterface.removeColumn('Person', 'petName', { transaction }),
+        queryInterface.removeColumn('Person', 'favoriteColor', { transaction })
       ]);
     });
   }
@@ -227,7 +228,7 @@ const { DataTypes } = require('@sequelize/core');
 
 module.exports = {
   async up(queryInterface) {
-    const transaction = await queryInterface.sequelize.transaction();
+    const transaction = await queryInterface.sequelize.startUnmanagedTransaction();
     try {
       await queryInterface.addColumn(
         'Person',
@@ -253,7 +254,7 @@ module.exports = {
     }
   },
   async down(queryInterface) {
-    const transaction = await queryInterface.sequelize.transaction();
+    const transaction = await queryInterface.sequelize.startUnmanagedTransaction();
     try {
       await queryInterface.removeColumn('Person', 'petName', { transaction });
       await transaction.commit();

docs/other-topics/aws-lambda.md

@@ -579,7 +579,7 @@ a simplification of the method's logic for queries without transactions:
 class Sequelize {
   // (...)
 
-  query(sql, options) {
+  async query(sql, options) {
     // (...)
 
     const connection = await this.connectionManager.getConnection(options);

docs/other-topics/upgrade.md

@@ -68,14 +68,22 @@ If you do that, we recommend pinning the Sequelize version your project uses as
 
 :::info
 
-[CLS Transactions](../querying/transactions.md#automatically-pass-transactions-to-all-queries) are now enabled by default.
+[CLS Transactions](../querying/transactions.md#disabling-cls) are now enabled by default.
 You can use the [`disableClsTransactions`](pathname:///api/v7/interfaces/_sequelize_core.index.Options.html#disableClsTransactions) global option to disable them.
 
 :::
 
 Sequelize's CLS implementation has been migrated to use Node's built-in AsyncLocalStorage. This means you do not need to install the `continuation-local-storage` or `cls-hooked` packages anymore,
 and that the `Sequelize.useCLS` method has been removed.
 
+### Unmanaged transactions
+
+*Pull Request [#15292](https://github.com/sequelize/sequelize/pull/15292)*
+
+In order to discourage [unmanaged transactions](../querying/transactions.md#unmanaged-transactions), which we consider to be error-prone, `sequelize.transaction()` cannot be used to create unmanaged transactions anymore.
+You must use `sequelize.startUnmanagedTransaction()` for that.
+[Managed transactions](../querying/transactions.md#managed-transactions-recommended) continue to use `sequelize.transaction()`.
+
 ### `$bind` parameters in strings must not be escaped anymore
 
 *Pull Request [#14447]*