Merge branch 'master' into split-debug

.github/workflows/active-record.yml

@@ -56,6 +56,7 @@ jobs:
         ports:
           - 1521:1521
         env:
+          ORACLE_DATABASE : yiitest
           ORACLE_PASSWORD : root
         options: >-
           --name=oci

.github/workflows/db-oracle.yml

@@ -52,6 +52,7 @@ jobs:
         ports:
           - 1521:1521
         env:
+          ORACLE_DATABASE : yiitest
           ORACLE_PASSWORD : root
         options: >-
           --name=oci

README.md

@@ -34,11 +34,11 @@ similar to the way you would use ORM (Object-Relational Mapping) frameworks like
 
 ## Usage 
 
-[Check the documentation docs](/docs/en/getting-started.md) to learn about usage.
+[Check the documentation](/docs/en/README.md) to learn about usage.
 
 ## Testing
 
-[Check the documentation](/docs/en/testing.md) to learn about testing.
+[Check the testing instructions](/docs/en/testing.md) to learn about testing.
 
 ## Support the project
 

docs/en/getting-started.md → docs/en/README.md

@@ -19,12 +19,12 @@ you have to take extra effort to create a database agnostic application.
 
 [Yii DB](https://github.com/yiisoft/db) supports the following databases out of the box:
 
-1. [MSSQL](https://www.microsoft.com/en-us/sql-server/sql-server-2019) version **2017, 2019, 2022**.
-2. [MySQL](https://www.mysql.com/) version **5.7 - 8.0**.
-3. [MariaDB](https://mariadb.org/) version **10.4 - 10.9**.
-4. [Oracle](https://www.oracle.com/database/) version **18c - 21c**.
-5. [PostgreSQL](https://www.postgresql.org/) version **9.6 - 15**. 
-6. [SQLite](https://www.sqlite.org/index.html) version **3.3 and above**.
+- [MSSQL](https://www.microsoft.com/en-us/sql-server/sql-server-2019) of versions **2017, 2019, 2022**.
+- [MySQL](https://www.mysql.com/) of versions **5.7 - 8.0**.
+- [MariaDB](https://mariadb.org/) of versions **10.4 - 10.9**.
+- [Oracle](https://www.oracle.com/database/) of versions **18c - 21c**.
+- [PostgreSQL](https://www.postgresql.org/) of versions **9.6 - 15**. 
+- [SQLite](https://www.sqlite.org/index.html) of version **3.3 and above**.
 
 ## Installation
 
@@ -71,11 +71,11 @@ First, you need to [configure database schema cache](schema-cache.md).
 
 You can create a database connection instance using a [DI container](https://github.com/yiisoft/di) or without it.
 
-1. [MSSQL Server](/docs/en/connection/mssql.md)
-2. [MySQL/MariaDB Server](/docs/en/connection/mysql.md)
-3. [Oracle Server](/docs/en/connection/oracle.md)
-4. [PostgreSQL Server](/docs/en/connection/pgsql.md)
-5. [SQLite Server](/docs/en/connection/sqlite.md)
+- [MSSQL Server](/docs/en/connection/mssql.md)
+- [MySQL/MariaDB Server](/docs/en/connection/mysql.md)
+- [Oracle Server](/docs/en/connection/oracle.md)
+- [PostgreSQL Server](/docs/en/connection/pgsql.md)
+- [SQLite Server](/docs/en/connection/sqlite.md)
 
 > Info: When you create a DB connection instance, the actual connection to the database isn't established until
 > you execute the first SQL or call the `Yiisoft\Db\Connection\ConnectionInterface::open()` method explicitly.
@@ -84,8 +84,8 @@ You can create a database connection instance using a [DI container](https://git
 
 Logger and profiler are optional. You can use them if you need to log and profile your queries.
 
-1. [Logger](/docs/en/connection/logger.md)
-2. [Profiler](/docs/en/connection/profiler.md)
+- [Logger](/docs/en/connection/logger.md)
+- [Profiler](/docs/en/connection/profiler.md)
 
 ## Execute SQL queries
 
@@ -130,7 +130,7 @@ SQL statements in a more convenient way.
 It's a powerful tool to create complex SQL statements in a simple way.
 
 
-## Working with a database
+## Commands
 
 [Yii DB](https://github.com/yiisoft/db) provides a `Command` class that represents an **SQL** statement to be executed
 against a database.

docs/en/command/ddl.md

@@ -3,7 +3,7 @@
 Data Definition Language (DDL) is a set of SQL statements to define the database structure.
 
 DDL statements are used to create and change the database objects in a database.
-These objects can be tables, indexes, views, stored procedures, triggers, and more.
+These objects can be tables, indexes, views, stored procedures, triggers, and so on.
 
 ## Tables
 
@@ -58,7 +58,8 @@ CREATE TABLE `customer` (
 
 ### Drop a table
 
-To drop a table, you can use the `Yiisoft\Db\Command\CommandInterface::dropTable()` method:
+To drop a table with schema declaration and and all its data, you can use the 
+`Yiisoft\Db\Command\CommandInterface::dropTable()` method:
 
 ```php
 <?php
@@ -71,9 +72,12 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->dropTable('{{%customer}}')->execute();
 ```
 
+> Warning: All existing data will be deleted.
+
 ### Truncate a table
 
-To clear all data of a table, you can use the `Yiisoft\Db\Command\CommandInterface::truncateTable()` method:
+To clear just the data of a table without removing schema declaration, you can use the 
+`Yiisoft\Db\Command\CommandInterface::truncateTable()` method:
 
 ```php
 <?php
@@ -86,6 +90,8 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->truncateTable('{{%customer}}')->execute();
 ```
 
+> Warning: All existing data will be deleted.
+
 ## Columns
 
 ### Add a new column
@@ -436,7 +442,6 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->dropCheck('{{%customer}}', 'ck-customer-status')->execute();
 ```
 
-
 ## Comments
 
 ### Add comment to a column

docs/en/command/dml.md

@@ -1,12 +1,18 @@
 # Data Manipulation Language (DML) commands
 
-DML is a set of SQL statements to manipulate data in a database.
+DML is a set of SQL statements used to manipulate data in a database.
 
-You can use the DML statements to perform the following operations.
+You can use the DML to perform the following operations:
+
+- [Batch insert](#batch-insert)
+- [Delete rows](#delete-rows)
+- [Reset sequence](#reset-sequence)
+- [Update](#update)
+- [Upsert](#upsert)
 
 ## Batch insert
 
-To insert many rows into a table, you can use the `Yiisoft\Db\Command\CommandInterface::batchInsert()` method:~~~~
+To insert multiple rows into a table, you can use the `Yiisoft\Db\Command\CommandInterface::batchInsert()` method:
 
 ```php
 <?php
@@ -83,6 +89,7 @@ you can use the `Yiisoft\Db\Command\CommandInterface::upsert()` method:
 declare(strict_types=1);
 
 use Yiisoft\Db\Connection\ConnectionInterface;
+use Yiisoft\Db\Expression\Expression;
 
 /** @var ConnectionInterface $db */
 $db->createCommand()->upsert(
@@ -92,9 +99,9 @@ $db->createCommand()->upsert(
         'url' => 'https://example.com/', // URL is unique
         'visits' => 0,
     ],
-    [
-        'visits' => new \Yiisoft\Db\Expression\Expression('visits + 1'),
+    updateColumns: [
+        'visits' => new Expression('visits + 1'),
     ],
-    $params,
+    params: $params,
 )->execute();
 ```

docs/en/connection/logger.md

@@ -6,6 +6,7 @@ You can configure a logger that implements `Psr\Log\LoggerInterface::class` in t
 
 In the following example, you configure [Yii Logging Library](https://github.com/yiisoft/log) with a
 [file target](https://github.com/yiisoft/log-target-file).
+
 Create a file `config/common/di/logger.php`:
 
 ```php
@@ -28,7 +29,8 @@ return [
 ];
 ```
 
-Create a file `config/common/di/db-pgsql.php`:
+Depending on used DBMS, create a file with database connection configuration. For example, when using PostgreSQL, it 
+will be `config/common/di/db-pgsql.php`:
 
 ```php
 <?php
@@ -57,3 +59,5 @@ return [
     ],
 ];
 ```
+
+For other DBMS refer to ["Create connecton"](/docs/en/README.md#create-connection) section.

docs/en/connection/mssql.md

@@ -49,7 +49,7 @@ return [
 ```
 
 To configure the connection without [DI container](https://github.com/yiisoft/di),
-you need to follow the following steps.
+you need to follow these steps.
 
 ```php
 <?php

docs/en/connection/mysql.md

@@ -64,7 +64,7 @@ return [
 ];
 ```
 
-To configure without [DI container](https://github.com/yiisoft/di), you need to follow the following steps.
+To configure without [DI container](https://github.com/yiisoft/di), you need to follow these steps.
 
 ```php
 <?php

docs/en/connection/oracle.md

@@ -46,7 +46,7 @@ return [
 ];
 ```
 
-To configure without [DI container](https://github.com/yiisoft/di), you need to follow the following steps.
+To configure without [DI container](https://github.com/yiisoft/di), you need to follow these steps.
 
 ```php
 <?php

docs/en/connection/pgsql.md

@@ -46,7 +46,7 @@ return [
 ];
 ```
 
-To configure without a [DI container](https://github.com/yiisoft/di), you need to follow the following steps.
+To configure without a [DI container](https://github.com/yiisoft/di), you need to follow these steps.
 
 ```php
 <?php

docs/en/connection/profiler.md

@@ -1,11 +1,11 @@
 # Connecting with profiler
 
-[Yii DB](https://github.com/yiisoft/db) used [Yii Profiler](https://github.com/yiisoft/profiler), a tool for collecting
-and analyzing database queries useful for debugging and optimizing database performance.
+[Yii DB](https://github.com/yiisoft/db) can be used with [Yii Profiler](https://github.com/yiisoft/profiler), a tool for
+collecting and analyzing database queries useful for debugging and optimizing database performance.
 
 When you install [Yii Profiler](https://github.com/yiisoft/profiler) it's automatically configured in the
 [DI container](https://github.com/yiisoft/di) for [Yii Config](https://github.com/yiisoft/config),
-so you can use it in your application.
+so you can use it in your application right away.
 
 The following describes how to configure it manually.
 
@@ -31,7 +31,8 @@ return [
 ];
 ```
 
-Create a file `config/common/di/db-pgsql.php`.
+Depending on used DBMS, create a file with database connection configuration. For example, when using PostgreSQL, it
+will be `config/common/di/db-pgsql.php`:
 
 ```php
 <?php
@@ -60,3 +61,5 @@ return [
     ],
 ];
 ```
+
+For other DBMS refer to ["Create connecton"](/docs/en/README.md#create-connection) section.

docs/en/connection/sqlite.md

@@ -40,7 +40,7 @@ return [
 ];
 ```
 
-To configure without [DI container](https://github.com/yiisoft/di), you need to follow the following steps.
+To configure without [DI container](https://github.com/yiisoft/di), you need to follow these steps.
 
 ```php
 <?php

docs/en/queries/bind-parameters.md

@@ -1,6 +1,6 @@
 # Bind parameters
 
-There are two use-cases for biding parameters:
+There are two use-cases for binding parameters:
 
 - When you do the same query with different data many times.
 - When you need to insert values into SQL string to prevent **SQL injection attacks**.
@@ -9,7 +9,7 @@ You can do binding by using named placeholders (`:name`) or positional placehold
 pass values as a separate argument.
 
 > Info: In many places in higher abstraction layers, like **query builder**, you often specify an
-**array of values** and Yii does parameter binding for you, so there is no need to specify
+**array of values** and Yii DB does parameter binding for you, so there is no need to specify
 parameters manually.
 
 ## Bind a single value

docs/en/queries/create-command-fetch-data.md

@@ -15,14 +15,14 @@ $command = $db->createCommand('SELECT * FROM {{%customer}}');
 
 In the command, there are different methods to **fetch data**:
 
-- `queryAll()`
-- `queryOne()`
-- `queryColumn()`
-- `queryScalar()`
-- `query()`
-
-> Note: To preserve precision, the data fetched from databases are always strings, even if the corresponding
-> database column types are numerical.
+- [queryAll()](#query-all)
+- [queryOne()](#query-one)
+- [queryColumn()](#query-column)
+- [queryScalar()](#query-scalar)
+- [query()](#query)
+
+> Note: To preserve precision, all data fetched from databases in the string type, even if the corresponding 
+> database column types are different, numerical for example.
 > You may need to use type conversion to convert them into the corresponding PHP types.
 
 ### Query all
@@ -182,16 +182,3 @@ foreach ($command as $row) {
     // do something with $row
 }
 ```
-
-The result is:
-
-```php
-Yiisoft\Db\Query\Data\DataReader#4710
-(
-    [Yiisoft\Db\Query\Data\DataReader:index] => -1
-    [Yiisoft\Db\Query\Data\DataReader:statement] => PDOStatement#4711
-    (
-        [queryString] => 'SELECT * FROM customer'
-    )
-)
-```

docs/en/queries/execute-command.md

@@ -1,16 +1,19 @@
 # Execute a command
 
-The methods introduced in the [Create a command and fetch data](create-command-fetch-data.md) all deals with
+All methods introduced in the [Create a command and fetch data](create-command-fetch-data.md) deal with
 `SELECT` queries which fetch data from databases.
 
-For queries that don't bring back data, you should call the `Yiisoft\Db\Command\CommandInterface::execute()` method.
+For queries that don't return any data, you should call the `Yiisoft\Db\Command\CommandInterface::execute()` method:
 
-If the query is successful, `Yiisoft\Db\Command\CommandInterface::execute()` will return the number of rows the command
-execution affected.
-It returns `0` if no rows the command affected no rows.
-If the query fails, it throws a `Yiisoft\Db\Exception\Exception`.
+- If the query is successful, `Yiisoft\Db\Command\CommandInterface::execute()` will return the number of rows affected 
+by the command execution.
+- If no rows were affected by the command execution, it returns `0`. 
+- If the query fails, it throws a `Yiisoft\Db\Exception\Exception`.
 
-For example, the following code executes a non-`SELECT` query and affected row count is `1`.
+Let's say there is a customer table, with row having `1` id is present and row having `1000` id is missing. And 
+non-`SELECT` queries are being executed for both of them.
+
+Then, in the following code affected row count will be `1`, because the row has been found and successfully updated:
 
 ```php
 <?php
@@ -21,11 +24,11 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 
 /** @var ConnectionInterface $db */
 
-$command = $db->createCommand('UPDATE {{%customer}} SET [[status]] = 2 WHERE [[id]] = 1');
+$command = $db->createCommand("UPDATE {{%customer}} SET [[name]] = 'John' WHERE [[id]] = 1");
 $rowCount = $command->execute(); // 1
 ```
 
-The following query and affects now rows.
+This query however affects no rows, because no rows were found by the given condition in `WHERE` clause:
 
 ```php
 <?php
@@ -36,11 +39,11 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 
 /** @var ConnectionInterface $db */
 
-$command = $db->createCommand('UPDATE {{%customer}} SET [[status]] = 2 WHERE [[id]] = 1000');
+$command = $db->createCommand("UPDATE {{%customer}} SET [[name]] = 'John' WHERE [[id]] = 1000");
 $rowCount = $command->execute(); // 0
 ```
 
-In case of bad SQL, there's an exception.
+In case of invalid SQL, the according exception will be thrown.
 
 ```php
 <?php