diff --git a/docs/guide/database-basics.md b/docs/guide/database-basics.md new file mode 100644 index 0000000..b98b057 --- /dev/null +++ b/docs/guide/database-basics.md @@ -0,0 +1,207 @@ +Database basics +=============== + +Yii has a database access layer built on top of PHP's [PDO](http://www.php.net/manual/en/ref.pdo.php). It provides +uniform API and solves some inconsistencies between different DBMS. By default Yii supports MySQL, SQLite, PostgreSQL, +Oracle and MSSQL. + +Configuration +------------- + +In order to start using database you need to configure database connection component first by adding `db` component +to application configuration (for "basic" web application it's `config/web.php`) like the following: + +```php +return array( + // ... + 'components' => array( + // ... + 'db' => array( + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=mydatabase', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', + ), + ), + // ... +); +``` + +After component is configured you can access using the following syntax: + +```php +$connection = \Yii::$app->db; +``` + +You can refer to [[\yii\db\Connection]] for a list of properties you can configure. Also note that you can define more +than one connection components and use both at the same time if needed: + +```php +$primaryConnection = \Yii::$app->db; +$secondaryConnection = \Yii::$app->secondDb; +``` + +If you don't want to define connection as application component you can instantiate it directly: + +```php +$connection = new \yii\db\Connection(array( + 'dsn' => $dsn, + 'username' => $username, + 'password' => $password, +)); +$connection->open(); +``` + +Basic SQL queries +----------------- + +Once you have a connection instance you can execute SQL queries using [[\yii\db\Command]]. + +### SELECT + +When query returns a set of rows: + +```php +$command = $connection->createCommand('SELECT * FROM tbl_post'); +$posts = $command->queryAll(); +``` + +When only a single row is returned: + +```php +$command = $connection->createCommand('SELECT * FROM tbl_post LIMIT 1'); +$post = $command->query(); +``` + +When there are multiple values from the same column: + +```php +$command = $connection->createCommand('SELECT title FROM tbl_post'); +$titles = $command->queryColumn(); +``` + +When there's a scalar value: + +```php +$command = $connection->createCommand('SELECT COUNT(*) FROM tbl_post'); +$postCount = $command->queryScalar(); +``` + +### UPDATE, INSERT, DELETE etc. + +If SQL executed doesn't return any data you can use command's `execute` method: + +```php +$command = $connection->createCommand('UPDATE tbl_post SET status=1'); +$command->execute(); +``` + +Alternatively the following syntax is possible: + +```php +// INSERT +$connection->createCommand()->insert('tbl_user', array( + 'name' => 'Sam', + 'age' => 30, +))->execute(); + +// INSERT multiple rows at once +$connection->createCommand()->batchInsert('tbl_user', array('name', 'age'), array( + array('Tom', 30), + array('Jane', 20), + array('Linda', 25), +))->execute(); + +// UPDATE +$connection->createCommand()->update('tbl_user', array( + 'status' => 1, +), 'age > 30')->execute(); + +// DELETE +$connection->createCommand()->delete('tbl_user', 'status = 0')->execute(); +``` + + +Prepared statements +------------------- + +In order to securely pass query parameters you can use prepared statements: + +```php +$command = $connection->createCommand('SELECT * FROM tbl_post WHERE id=:id'); +$command->bindValue(':id', $_GET['id']); +$post = $command->query(); +``` + +Another usage is performing a query multiple times while preparing it only once: + +```php +$command = $connection->createCommand('DELETE FROM tbl_post WHERE id=:id'); +$command->bindParam(':id', $id); + +$id = 1; +$command->execute(); + +$id = 2; +$command->execute(); +``` + +Transactions +------------ + +If the underlying DBMS supports transactions, you can perform transactional SQL queries like the following: + +```php +$transaction = $connection->beginTransaction(); +try { + $connection->createCommand($sql1)->execute(); + $connection->createCommand($sql2)->execute(); + // ... executing other SQL statements ... + $transaction->commit(); +} catch(Exception $e) { + $transaction->rollback(); +} +``` + +Working with database schema +---------------------------- + +### Getting schema information + +You can get a [[\yii\db\Schema]] instance like the following: + +```php +$schema = $connection->getSchema(); +``` + +It contains a set of methods allowing you to retrieve various information about the database: + +```php +$tables = $schema->getTableNames(); +``` + +For the full reference check [[\yii\db\Schema]]. + +### Modifying schema + +Aside from basic SQL queries [[\yii\db\Command]] contains a set of methods allowing to modify database schema: + +- createTable, renameTable, dropTable, truncateTable +- addColumn, renameColumn, dropColumn, alterColumn +- addPrimaryKey, dropPrimaryKey +- addForeignKey, dropForeignKey +- createIndex, dropIndex + +These can be used as follows: + +```php +// UPDATE +$connection->createCommand()->createTable('tbl_post', array( + 'id' => 'pk', + 'title' => 'string', + 'text' => 'text', +); +``` + +For the full reference check [[\yii\db\Command]]. diff --git a/docs/guide/index.md b/docs/guide/index.md index e9e23d6..0ab8f55 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -23,7 +23,7 @@ Base concepts Database ======== -- [Database Access Objects](dao.md) +- [Basics](database-basics.md) - [Query Builder](query-builder.md) - [ActiveRecord](active-record.md) - [Database Migration](migration.md)