php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-11-17 06:48:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

Fixes #10084: Improved DB docs

Browse Source
This commit is contained in:
Alexander Makarov
2015-11-04 12:08:18 +03:00
parent ff00930f15
commit 95f251edd1
2 changed files with 41 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/guide/db-dao.md
View File

@@ -113,26 +113,24 @@ Once you have a database connection instance, you can execute a SQL query by tak
The following example shows various ways of fetching data from a database: The following example shows various ways of fetching data from a database:
```php ```php
$db = new yii\db\Connection(...);
// return a set of rows. each row is an associative array of column names and values. // return a set of rows. each row is an associative array of column names and values.
// an empty array is returned if no results // an empty array is returned if no results
$posts = $db->createCommand('SELECT * FROM post') $posts = Yii::$app->db->createCommand('SELECT * FROM post')
->queryAll(); ->queryAll();
// return a single row (the first row) // return a single row (the first row)
// false is returned if no results // false is returned if no results
$post = $db->createCommand('SELECT * FROM post WHERE id=1') $post = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=1')
->queryOne(); ->queryOne();
// return a single column (the first column) // return a single column (the first column)
// an empty array is returned if no results // an empty array is returned if no results
$titles = $db->createCommand('SELECT title FROM post') $titles = Yii::$app->db->createCommand('SELECT title FROM post')
->queryColumn(); ->queryColumn();
// return a scalar // return a scalar
// false is returned if no results // false is returned if no results
$count = $db->createCommand('SELECT COUNT(*) FROM post') $count = Yii::$app->db->createCommand('SELECT COUNT(*) FROM post')
->queryScalar(); ->queryScalar();
``` ```
@@ -167,7 +165,7 @@ When creating a DB command from a SQL with parameters, you should almost always
to prevent SQL injection attacks. For example, to prevent SQL injection attacks. For example,
```php ```php
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status') $post = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status')
->bindValue(':id', $_GET['id']) ->bindValue(':id', $_GET['id'])
->bindValue(':status', 1) ->bindValue(':status', 1)
->queryOne(); ->queryOne();
@@ -187,11 +185,11 @@ The following example shows alternative ways of binding parameters:
```php ```php
$params = [':id' => $_GET['id'], ':status' => 1]; $params = [':id' => $_GET['id'], ':status' => 1];
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status') $post = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status')
->bindValues($params) ->bindValues($params)
->queryOne(); ->queryOne();
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status', $params) $post = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status', $params)
->queryOne(); ->queryOne();
``` ```
@@ -200,7 +198,7 @@ Besides preventing SQL injection attacks, it may also improve performance by pre
executing it multiple times with different parameters. For example, executing it multiple times with different parameters. For example,
```php ```php
$command = $db->createCommand('SELECT * FROM post WHERE id=:id'); $command = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=:id');
$post1 = $command->bindValue(':id', 1)->queryOne(); $post1 = $command->bindValue(':id', 1)->queryOne();
$post2 = $command->bindValue(':id', 2)->queryOne(); $post2 = $command->bindValue(':id', 2)->queryOne();
@@ -210,7 +208,7 @@ Because [[yii\db\Command::bindParam()|bindParam()]] supports binding parameters
can also be written like the following: can also be written like the following:
```php ```php
$command = $db->createCommand('SELECT * FROM post WHERE id=:id') $command = Yii::$app->db->createCommand('SELECT * FROM post WHERE id=:id')
->bindParam(':id', $id); ->bindParam(':id', $id);
$id = 1; $id = 1;
@@ -231,7 +229,7 @@ The `queryXyz()` methods introduced in the previous sections all deal with SELEC
For queries that do not bring back data, you should call the [[yii\db\Command::execute()]] method instead. For example, For queries that do not bring back data, you should call the [[yii\db\Command::execute()]] method instead. For example,
```php ```php
$db->createCommand('UPDATE post SET status=1 WHERE id=1') Yii::$app->db->createCommand('UPDATE post SET status=1 WHERE id=1')
->execute(); ->execute();
``` ```
@@ -243,16 +241,16 @@ SQLs. These methods will properly quote table and column names and bind paramete
```php ```php
// INSERT (table name, column values) // INSERT (table name, column values)
$db->createCommand()->insert('user', [ Yii::$app->db->createCommand()->insert('user', [
'name' => 'Sam', 'name' => 'Sam',
'age' => 30, 'age' => 30,
])->execute(); ])->execute();
// UPDATE (table name, column values, condition) // UPDATE (table name, column values, condition)
$db->createCommand()->update('user', ['status' => 1], 'age > 30')->execute(); Yii::$app->db->createCommand()->update('user', ['status' => 1], 'age > 30')->execute();
// DELETE (table name, condition) // DELETE (table name, condition)
$db->createCommand()->delete('user', 'status = 0')->execute(); Yii::$app->db->createCommand()->delete('user', 'status = 0')->execute();
``` ```
You may also call [[yii\db\Command::batchInsert()|batchInsert()]] to insert multiple rows in one shot, which is much You may also call [[yii\db\Command::batchInsert()|batchInsert()]] to insert multiple rows in one shot, which is much
@@ -260,7 +258,7 @@ more efficient than inserting one row at a time:
```php ```php
// table name, column names, column values // table name, column names, column values
$db->createCommand()->batchInsert('user', ['name', 'age'], [ Yii::$app->db->createCommand()->batchInsert('user', ['name', 'age'], [
['Tom', 30], ['Tom', 30],
['Jane', 20], ['Jane', 20],
['Linda', 25], ['Linda', 25],
@@ -282,7 +280,7 @@ For example,
```php ```php
// executes this SQL for MySQL: SELECT COUNT(`id`) FROM `employee` // executes this SQL for MySQL: SELECT COUNT(`id`) FROM `employee`
$count = $db->createCommand("SELECT COUNT([[id]]) FROM {{employee}}") $count = Yii::$app->db->createCommand("SELECT COUNT([[id]]) FROM {{employee}}")
->queryScalar(); ->queryScalar();
``` ```
@@ -313,7 +311,7 @@ when configuring the DB connection. For example,
```php ```php
// executes this SQL for MySQL: SELECT COUNT(`id`) FROM `tbl_employee` // executes this SQL for MySQL: SELECT COUNT(`id`) FROM `tbl_employee`
$count = $db->createCommand("SELECT COUNT([[id]]) FROM {{%employee}}") $count = Yii::$app->db->createCommand("SELECT COUNT([[id]]) FROM {{%employee}}")
->queryScalar(); ->queryScalar();
``` ```
@@ -327,7 +325,7 @@ none of these queries is executed.
The following code shows a typical way of using transactions: The following code shows a typical way of using transactions:
```php ```php
$db->transaction(function($db) { Yii::$app->db->transaction(function($db) {
$db->createCommand($sql1)->execute(); $db->createCommand($sql1)->execute();
$db->createCommand($sql2)->execute(); $db->createCommand($sql2)->execute();
// ... executing other SQL statements ... // ... executing other SQL statements ...
@@ -337,11 +335,11 @@ $db->transaction(function($db) {
The above code is equivalent to the following: The above code is equivalent to the following:
```php ```php
$transaction = $db->beginTransaction(); $transaction = Yii::$app->db->beginTransaction();
try { try {
$db->createCommand($sql1)->execute(); Yii::$app->db->createCommand($sql1)->execute();
$db->createCommand($sql2)->execute(); Yii::$app->db->createCommand($sql2)->execute();
// ... executing other SQL statements ... // ... executing other SQL statements ...
$transaction->commit(); $transaction->commit();
@@ -370,13 +368,13 @@ it will use the default isolation level set by your database system. You can ove
```php ```php
$isolationLevel = \yii\db\Transaction::REPEATABLE_READ; $isolationLevel = \yii\db\Transaction::REPEATABLE_READ;
$db->transaction(function ($db) { Yii::$app->db->transaction(function ($db) {
.... ....
}, $isolationLevel); }, $isolationLevel);
// or alternatively // or alternatively
$transaction = $db->beginTransaction($isolationLevel); $transaction = Yii::$app->db->beginTransaction($isolationLevel);
``` ```
Yii provides four constants for the most common isolation levels: Yii provides four constants for the most common isolation levels:
@@ -409,7 +407,7 @@ You have to call [[yii\db\Transaction::setIsolationLevel()]] in this case after
If your DBMS supports Savepoint, you may nest multiple transactions like the following: If your DBMS supports Savepoint, you may nest multiple transactions like the following:
```php ```php
$db->transaction(function ($db) { Yii::$app->db->transaction(function ($db) {
// outer transaction // outer transaction
$db->transaction(function ($db) { $db->transaction(function ($db) {
@@ -421,13 +419,13 @@ $db->transaction(function ($db) {
Or alternatively, Or alternatively,
```php ```php
$outerTransaction = $db->beginTransaction(); $outerTransaction = Yii::$app->db->beginTransaction();
try { try {
$db->createCommand($sql1)->execute(); Yii::$app->db->createCommand($sql1)->execute();
$innerTransaction = $db->beginTransaction(); $innerTransaction = Yii::$app->db->beginTransaction();
try { try {
$db->createCommand($sql2)->execute(); Yii::$app->db->createCommand($sql2)->execute();
$innerTransaction->commit(); $innerTransaction->commit();
} catch (\Exception $e) { } catch (\Exception $e) {
$innerTransaction->rollBack(); $innerTransaction->rollBack();
@@ -487,18 +485,18 @@ Such read-write splitting is accomplished automatically with this configuration.
```php ```php
// create a Connection instance using the above configuration // create a Connection instance using the above configuration
$db = Yii::createObject($config); Yii::$app->db = Yii::createObject($config);
// query against one of the slaves // query against one of the slaves
$rows = $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll(); $rows = Yii::$app->db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
// query against the master // query against the master
$db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute(); Yii::$app->db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute();
``` ```
> Info: Queries performed by calling [[yii\db\Command::execute()]] are considered as write queries, while > Info: Queries performed by calling [[yii\db\Command::execute()]] are considered as write queries, while
all other queries done through one of the "query" methods of [[yii\db\Command]] are read queries. all other queries done through one of the "query" methods of [[yii\db\Command]] are read queries.
You can get the currently active slave connection via `$db->slave`. You can get the currently active slave connection via `Yii::$app->db->slave`.
The `Connection` component supports load balancing and failover between slaves. The `Connection` component supports load balancing and failover between slaves.
When performing a read query for the first time, the `Connection` component will randomly pick a slave and When performing a read query for the first time, the `Connection` component will randomly pick a slave and
@@ -569,12 +567,12 @@ the master connection. For example,
```php ```php
// the transaction is started on the master connection // the transaction is started on the master connection
$transaction = $db->beginTransaction(); $transaction = Yii::$app->db->beginTransaction();
try { try {
// both queries are performed against the master // both queries are performed against the master
$rows = $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll(); $rows = Yii::$app->db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
$db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute(); Yii::$app->db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute();
$transaction->commit(); $transaction->commit();
} catch(\Exception $e) { } catch(\Exception $e) {
@@ -586,19 +584,19 @@ try {
If you want to start a transaction with the slave connection, you should explicitly do so, like the following: If you want to start a transaction with the slave connection, you should explicitly do so, like the following:
```php ```php
$transaction = $db->slave->beginTransaction(); $transaction = Yii::$app->db->slave->beginTransaction();
``` ```
Sometimes, you may want to force using the master connection to perform a read query. This can be achieved Sometimes, you may want to force using the master connection to perform a read query. This can be achieved
with the `useMaster()` method: with the `useMaster()` method:
```php ```php
$rows = $db->useMaster(function ($db) { $rows = Yii::$app->db->useMaster(function ($db) {
return $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll(); return $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
}); });
``` ```
You may also directly set `$db->enableSlaves` to be false to direct all queries to the master connection. You may also directly set `Yii::$app->db->enableSlaves` to be false to direct all queries to the master connection.
## Working with Database Schema <span id="database-schema"></span> ## Working with Database Schema <span id="database-schema"></span>
@@ -625,7 +623,7 @@ These methods can be used like the following:
```php ```php
// CREATE TABLE // CREATE TABLE
$db->createCommand()->createTable('post', [ Yii::$app->db->createCommand()->createTable('post', [
'id' => 'pk', 'id' => 'pk',
'title' => 'string', 'title' => 'string',
'text' => 'text', 'text' => 'text',
@@ -636,7 +634,7 @@ You can also retrieve the definition information about a table through
the [[yii\db\Connection::getTableSchema()|getTableSchema()]] method of a DB connection. For example, the [[yii\db\Connection::getTableSchema()|getTableSchema()]] method of a DB connection. For example,
```php ```php
$table = $db->getTableSchema('post'); $table = Yii::$app->db->getTableSchema('post');
``` ```
The method returns a [[yii\db\TableSchema]] object which contains the information about the table's columns, The method returns a [[yii\db\TableSchema]] object which contains the information about the table's columns,

2
framework/db/Command.php
View File

@@ -44,6 +44,8 @@ use yii\base\NotSupportedException;
* *
* To build SELECT SQL statements, please use [[QueryBuilder]] instead. * To build SELECT SQL statements, please use [[QueryBuilder]] instead.
* *
* @see http://www.yiiframework.com/doc-2.0/guide-db-dao.html
*
* @property string $rawSql The raw SQL with parameter values inserted into the corresponding placeholders in * @property string $rawSql The raw SQL with parameter values inserted into the corresponding placeholders in
* [[sql]]. This property is read-only. * [[sql]]. This property is read-only.
* @property string $sql The SQL statement to be executed. * @property string $sql The SQL statement to be executed.