Merge branch 'master' into split-debug

.github/workflows/active-record.yml

@@ -26,7 +26,7 @@ jobs:
     name: PHP ${{ matrix.php }}-active-record-${{ matrix.os }}
 
     env:
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       EXTENSIONS: pdo, pdo_mysql, pdo_oci, pdo_pgsql, pdo_sqlite, pdo_sqlsrv-5.10.1
 
     runs-on: ${{ matrix.os }}

.github/workflows/db-mssql.yml

@@ -26,7 +26,7 @@ jobs:
     name: PHP ${{ matrix.php }}-mssql-${{ matrix.mssql }}
 
     env:
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       CURRENT_PACKAGE: db-mssql
       EXTENSIONS: pdo, pdo_sqlsrv-5.10.1
 

.github/workflows/db-mysql.yml

@@ -26,7 +26,7 @@ jobs:
     name: PHP ${{ matrix.php }}-mysql-${{ matrix.mysql }}
 
     env:
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       CURRENT_PACKAGE: db-mysql
       EXTENSIONS: pdo, pdo_mysql
 

.github/workflows/db-oracle.yml

@@ -27,7 +27,7 @@ jobs:
 
     env:
       CURRENT_PACKAGE: db-oracle
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       EXTENSIONS: pdo, pdo_oci
 
     runs-on: ${{ matrix.os }}

.github/workflows/db-pgsql.yml

@@ -26,7 +26,7 @@ jobs:
     name: PHP ${{ matrix.php }}-pgsql-${{ matrix.pgsql }}
 
     env:
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       CURRENT_PACKAGE: db-pgsql
       EXTENSIONS: pdo, pdo_pgsql
 

.github/workflows/db-sqlite.yml

@@ -26,7 +26,7 @@ jobs:
     name: PHP ${{ matrix.php }}-sqlite-${{ matrix.os }}
 
     env:
-      COMPOSER_ROOT_VERSION: dev-master
+      COMPOSER_ROOT_VERSION: 1.0.0
       CURRENT_PACKAGE: db-sqlite
       EXTENSIONS: pdo, pdo_sqlite
 

.gitignore

@@ -31,7 +31,8 @@ composer.phar
 
 # phpunit itself is not needed
 phpunit.phar
-phpunit.result.cache
+.phpunit.result.cache
+tests/Support/runtime/
 
 # local phpunit config
 /phpunit.xml

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Yii Database Change Log
+
+## 1.0.1 under development
+
+- no changes in this release.
+
+## 1.0.0 April 12, 2023
+
+- Initial release.

README.md

@@ -10,6 +10,16 @@ such as [MariaDB], [MSSQL], [MySQL], [Oracle], [PostgreSQL], and [SQLite].
 
 Using the package, you can perform common database tasks such as creating, reading, updating, and deleting
 records in a database table, as well as executing raw SQL queries.
+
+```php
+$rows = (new Query($db))  
+    ->select(['id', 'email'])  
+    ->from('{{%user}}')  
+    ->where(['last_name' => 'Smith'])  
+    ->limit(10)  
+    ->all();
+```
+
 The package is designed to be flexible
 and can be extended to support extra database types or to customize the way it interacts with databases.
 
@@ -36,6 +46,11 @@ similar to the way you would use ORM (Object-Relational Mapping) frameworks like
 
 [Check the documentation](/docs/en/README.md) to learn about usage.
 
+## Support
+
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/db/68) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
+
 ## Testing
 
 [Check the testing instructions](/docs/en/testing.md) to learn about testing.

UPGRADE.md

@@ -1,13 +1,14 @@
-Upgrading Instructions for Yii Framework Database 3.0
-=====================================================
+# Upgrading Instructions for Yii Database
 
-This file contains the upgrade notes for the database layer Yii 3.0.
-These notes highlight changes that could break your application when you upgrade Yii from one version to another.
+This file contains the upgrade notes for the Yii Database.
+These notes highlight changes that could break your application when you upgrade it from one version to another.
 Even though we try to ensure backwards compatibility (BC) as much as possible, sometimes
-it is not possible or very complicated to avoid it and still create a good solution to
+it isn't possible or very complicated to avoid it and still create a good solution to
 a problem. While upgrade to Yii 3.0 might require substantial changes to both your application and extensions,
 the changes are bearable and require "refactoring", not "rewrite".
-All the "Yes, it is" cool stuff and Yii soul are still in place.
+All the "Yes, it is" cool stuff, and Yii soul is still in place.
 
 Changes summary:
-* `Yiisoft\Db\Connection::$charset` has been removed. All support PDO classes allow you to specify the connection charset in the DSN.
+
+* `Yiisoft\Db\Connection::$charset` has been removed. All supported PDO classes allow you to specify the connection
+  charset in the DSN.

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "yiisoft/db",
     "type": "library",
-    "description": "Yii DataBase Library",
+    "description": "Yii Database",
     "keywords": [
         "yii",
         "sql",

docs/en/README.md

@@ -1,23 +1,20 @@
 # Getting started
 
-[Yii DB](https://github.com/yiisoft/db) is DAO (Data Access Object) layer for applications
-using [PHP](https://www.php.net/).
+Yii DB is DAO (Data Access Object) layer for applications using [PHP](https://www.php.net/).
 It provides a set of classes that help you access relational databases.
 It's designed to be flexible and extensible,
 so that it can be used with different databases and different database schemas.
 Its database agnostic nature makes it easy to switch from one database to another.
 
-Built on top of [PDO](https://www.php.net/manual/en/book.pdo.php), [Yii DB](https://github.com/yiisoft/db) provides
-an object-oriented API for accessing relational databases.
+Yii DB provides an object-oriented API for accessing relational databases.
 It's the foundation for other more advanced database access methods, including [Query Builder](query-builder.md).
 
-When using [Yii DB](https://github.com/yiisoft/db), you mainly need to deal with plain SQLs and PHP arrays.
+When using Yii DB, you mainly need to deal with plain SQLs and PHP arrays.
 As a result, it's the most efficient way to access databases.
-However, because SQL syntax may vary for different databases,
-using [Yii DB](https://github.com/yiisoft/db) also means
-you have to take extra effort to create a database agnostic application.
+However, because SQL syntax may vary for different databases, using Yii DB also means 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:
+Yii DB supports the following databases out of the box:
 
 - [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**.
@@ -28,8 +25,7 @@ you have to take extra effort to create a database agnostic application.
 
 ## Installation
 
-To install [Yii DB](https://github.com/yiisoft/db), you must select the driver you want to use and install it
-with [Composer](https://getcomposer.org/).
+To install Yii DB, you must select the driver you want to use and install it with [Composer](https://getcomposer.org/).
 
 For [MSSQL](https://github.com/yiisoft/db-mssql):
 
@@ -65,17 +61,17 @@ composer require yiisoft/db-sqlite
 
 ## Configure schema cache
 
-First, you need to [configure database schema cache](schema-cache.md).
+First, you need to [configure database schema cache](schema/cache.md).
 
 ## Create connection
 
 You can create a database connection instance using a [DI container](https://github.com/yiisoft/di) or without it.
 
-- [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)
+- [MSSQL Server](connection/mssql.md)
+- [MySQL/MariaDB Server](connection/mysql.md)
+- [Oracle Server](connection/oracle.md)
+- [PostgreSQL Server](connection/pgsql.md)
+- [SQLite Server](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,30 +80,30 @@ 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.
 
-- [Logger](/docs/en/connection/logger.md)
-- [Profiler](/docs/en/connection/profiler.md)
+- [Logger](connection/logger.md)
+- [Profiler](connection/profiler.md)
 
 ## Execute SQL queries
 
 Once you have a database connection instance, you can execute an SQL query by taking the following steps:
 
-1. [Create a command and fetch data](/docs/en/queries/create-command-fetch-data.md)
-2. [Bind parameters](/docs/en/queries/bind-parameters.md)
-3. [Execute a command](/docs/en/queries/execute-command.md)
+1. [Create a command and fetch data](queries/create-command-fetch-data.md)
+2. [Bind parameters](queries/bind-parameters.md)
+3. [Execute a command](queries/execute-command.md)
+4. [Execute many commands in a transaction](queries/transactions.md)
 
 ## Quote table and column names
 
 When writing a database-agnostic code, quoting table and column names is often a headache because different databases
 have different names quoting rules.
 
-To overcome this problem, you may use the following quoting syntax introduced by [Yii DB](https://github.com/yiisoft/db):
+To overcome this problem, you may use the following quoting syntax introduced by Yii DB:
 
 - `[[column name]]`: enclose a *column name* to quote in *double square brackets*.
 - `{{%table name}}`: enclose a *table name* to quote in *double curly brackets*, and the percentage character `%`
   will be replaced with the *table prefix*.
 
-[Yii DB](https://github.com/yiisoft/db) will automatically convert such constructs into the corresponding quoted column
-or table names using the DBMS-specific syntax.
+Yii DB will automatically convert such constructs into the corresponding quoted column or table names using the DBMS-specific syntax.
 
 For example, the following code will generate an SQL statement that's valid for all supported databases:
 
@@ -125,18 +121,35 @@ $result = $db->createCommand('SELECT COUNT([[id]]) FROM {{%employee}}')->querySc
 
 ## Query Builder
 
-[Yii DB](https://github.com/yiisoft/db) provides a [Query Builder](query-builder.md) that helps you create
-SQL statements in a more convenient way.
+Yii DB provides a [Query Builder](query-builder.md) that helps you create SQL statements in a more convenient way.
 It's a powerful tool to create complex SQL statements in a simple way.
 
-
 ## Commands
 
-[Yii DB](https://github.com/yiisoft/db) provides a `Command` class that represents an **SQL** statement to be executed
-against a database.
+Yii DB provides a `Command` class that represents an **SQL** statement to be executed against a database.
 
 You can use it to execute **SQL** statements that don't return any result set, such as `INSERT`, `UPDATE`, `DELETE`,
 `CREATE TABLE`, `DROP TABLE`, `CREATE INDEX`, `DROP INDEX`, etc.
 
-- [DDL commands](/docs/en/command/ddl.md)
-- [DML commands](/docs/en/command/dml.md)
+- [DDL commands](command/ddl.md)
+- [DML commands](command/dml.md)
+
+## Schema
+
+Yii DB provides a way to inspect the metadata of a database, such as table names, column names, etc. You can do it
+via schema:
+
+- [Reading database schema](schema/usage.md)
+- [Configuring schema cache](schema/cache.md)
+
+## Extensions
+
+The following extensions are available for Yii DB.
+
+- [Active Record](https://github.com/yiisoft/active-record).
+- [Cache DB](https://github.com/yiisoft/cache-db)
+- [Data DB](https://github.com/yiisoft/data-db)
+- [Log Target DB](https://github.com/yiisoft/log-target-db)
+- [Rbac DB](https://github.com/yiisoft/rbac-db)
+- [Translator Message DB](https://github.com/yiisoft/translator-message-db)
+- [Yii DB Migration](https://github.com/yiisoft/yii-db-migration)

docs/en/command/ddl.md

@@ -315,6 +315,11 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->createIndex('test', 'idx_test_name', 'id', 'UNIQUE')->execute();
 ```
 
+> Info: Unique indexes are indexes that help maintain data integrity by ensuring that no rows of data in a table have identical
+> key values.
+> When you create a unique index for an existing table with data, values in the columns or expressions that comprise the
+> index key are checked for uniqueness.
+
 ### Add clustered index
 
 In MSSQL, you can create a clustered index by specifying the `CLUSTERED` option in the `$indexType` parameter:
@@ -330,6 +335,10 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->createIndex('test', 'idx_test_name', 'id', 'CLUSTERED')->execute();
 ```
 
+> Info: A clustered index is an index which defines the physical order in which table records are stored in a database.
+> Since there can be only one way in which records are physically stored in a database table, there can be only one
+> clustered index per table. By default a clustered index is created on a primary key column.
+
 ### Add non-clustered index
 
 In MSSQL, you can create a non-clustered index by specifying the `NONCLUSTERED` option in the `$indexType` parameter:
@@ -345,6 +354,13 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->createIndex('test', 'idx_test_name', 'id', 'NONCLUSTERED')->execute();
 ```
 
+> Info: A non-clustered index is also used to speed up search operations. Unlike a clustered index, a non-clustered index doesn’t
+> physically define the order in which records are inserted into a table. In fact, a non-clustered index is stored in a 
+> separate location from the data table.
+> 
+> A non-clustered index is like a book index, which is located separately from the main contents of the book. Since non-clustered
+> indexes are located in a separate location, there can be multiple non-clustered indexes per table.
+
 ### Add fulltext index
 
 In MySQL and MariaDB, you can create a fulltext index by specifying the `FULLTEXT` option in the `$indexType`
@@ -361,6 +377,11 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->createIndex('test', 'idx_test_name', 'name', 'FULLTEXT')->execute();
 ```
 
+> Info: Full-text indexes are created on text-based columns (`CHAR`, `VARCHAR`, or `TEXT` columns) to speed up queries and DML operations
+> on data contained within those columns. 
+> 
+> A full-text index is defined as part of a `CREATE TABLE` statement or added to an existing table using `ALTER TABLE` or `CREATE INDEX`.
+
 ### Add bitmap index
 
 In `Oracle`, you can create a bitmap index by specifying the `BITMAP` option in the `$indexType` parameter:
@@ -377,6 +398,11 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->createIndex('test', 'idx_test_name', 'id', 'BITMAP')->execute();
 ```
 
+> Info: A bitmap index is a special kind of database index which uses bitmaps or bit array. In a bitmap index, Oracle stores a
+> bitmap for each index key.
+> 
+> Each index key stores pointers to multiple rows. For example, if you create a bitmap index on the gender column of the members table.
+
 ## Constraints
 
 ### Add `UNIQUE` constraint

docs/en/command/dml.md

@@ -7,6 +7,7 @@ You can use the DML to perform the following operations:
 - [Batch insert](#batch-insert)
 - [Delete rows](#delete-rows)
 - [Reset sequence](#reset-sequence)
+- [Insert](#insert)
 - [Update](#update)
 - [Upsert](#upsert)
 
@@ -63,6 +64,21 @@ use Yiisoft\Db\Connection\ConnectionInterface;
 $db->createCommand()->resetSequence('{{%customer}}', 1)->execute();
 ```
 
+## Insert
+
+To insert a row to a table, you can use the `Yiisoft\Db\Command\CommandInterface::insert()` method:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yiisoft\Db\Connection\ConnectionInterface;
+
+/** @var ConnectionInterface $db */
+$db->createCommand()->insert('{{%customer}}', ['name' => 'John', 'age' => 18])->execute();
+```
+
 ## Update
 
 To update rows in a table, you can use the `Yiisoft\Db\Command\CommandInterface::update()` method: