From bfa58eaacaf4a86985d7a1c4135ea27ae3e6e2de Mon Sep 17 00:00:00 2001 From: Wilmer Arambula <42547589+terabytesoftw@users.noreply.github.com> Date: Wed, 8 Mar 2023 11:48:49 -0300 Subject: [PATCH] Docs part 4. (#587) --- docs/en/command/ddl.md | 566 +++++++++++++++++++++++++++++++++++++ docs/en/command/dml.md | 109 +++++++ docs/en/getting-started.md | 16 ++ 3 files changed, 691 insertions(+) create mode 100644 docs/en/command/ddl.md create mode 100644 docs/en/command/dml.md diff --git a/docs/en/command/ddl.md b/docs/en/command/ddl.md new file mode 100644 index 000000000..c6bb8cc5c --- /dev/null +++ b/docs/en/command/ddl.md @@ -0,0 +1,566 @@ +# Data Definition Language (DDL) commands + +Data Definition Language (DDL) is a set of SQL statements that allows you 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 so on. + +## Add `CHECK` constraint + +To add a `CHECK` constraint to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::addCheck()` method. + +The following example shows how to add a `CHECK` constraint to an existing table. + +```php +createCommand()->addCheck('ck-customer-status', '{{%customer}}', 'status > 0')->execute(); +``` + +## Adding a new column + +To add a new column to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::addColumn()` method. + +The following example shows how to add a new column to an existing table. + +```php +createCommand()->addColumn( + '{{%customer}}', + 'profile_id', + $db->getSchema()->createColumnSchemaBuilder('integer') +)->execute(); +``` + +## Add comment to column + +To add a comment to an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::addCommentOnColumn()` +method. + +The following example shows how to add a comment to an existing column. + +```php +createCommand()->addCommentOnColumn('{{%customer}}', 'name', 'This is a customer name')->execute(); +``` + +## Add comment to table + +To add a comment to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::addCommentOnTable()` method. + +The following example shows how to add a comment to an existing table. + +```php +createCommand()->addCommentOnTable('{{%customer}}', 'This is a customer table')->execute(); +``` + +## Add default value to column + +To add a default value to an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::addDefaultValue()` +method. + +The following example shows how to add a default value to an existing column. + +```php +createCommand()->addDefaultValue('df-customer-name', '{{%customer}}', 'name', 'John Doe')->execute(); +``` + +## Adding a foreign key + +To add a foreign key to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::addForeignKey()` method. + +The following example shows how to add a foreign key to an existing table. + +```php +createCommand()->addForeignKey( + 'fk-customer-profile_id', + '{{%customer}}', + 'profile_id', + '{{%profile}}', + 'id', + 'CASCADE', + 'CASCADE' +)->execute(); +``` + +## Adding a primary key + +To add a primary key to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::addPrimaryKey()` method. + +The following example shows how to add a primary key to an existing table. + +```php +createCommand()->addPrimaryKey('pk-customer-id', '{{%customer}}', 'id')->execute(); +``` + +## Add `UNIQUE` constraint + +To add a unique constraint to an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::addUnique()` +method. + +The following example shows how to add a unique constraint to an existing column. + +```php +createCommand()->addUnique('uq-customer-name', '{{%customer}}', 'name')->execute(); +``` + +## Alter column + +To change an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::alterColumn()` method. + +The following example shows how to change an existing column. + +```php +createCommand()->alterColumn( + '{{%customer}}', + 'profile_id', + $db->getSchema()->createColumnSchemaBuilder('integer')->notNull() +)->execute(); +``` + +## Adding an index + +To add an index to an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::createIndex()` method. + +The following example shows how to add an index to an existing table. + +```php +createCommand()->createIndex('idx-customer-name', '{{%customer}}', 'name')->execute(); +``` + +### Unique index + +You can create a unique index by specifying the `unique` option in the `$indexType` parameter, it's supported by all +dbms. + +```php +createCommand()->createIndex('idx_test_name', 'test', 'id', 'UNIQUE')->execute(); +``` + +### Clustered index + +In `MSSQL`, you can create a clustered index by specifying the `clustered` option in the `$indexType` parameter. + +```php +createCommand()->createIndex('idx_test_name', 'test', 'id', 'CLUSTERED')->execute(); +``` + +### Non-clustered index + +In `MSSQL`, you can create a non-clustered index by specifying the `nonclustered` option in the `$indexType` parameter. + +```php +createCommand()->createIndex('idx_test_name', 'test', 'id', 'NONCLUSTERED')->execute(); +``` + +### Fulltext index + +In `Mysql` and `MariaDB`, you can create a fulltext index by specifying the `fulltext` option in the `$indexType` +parameter. + +```php +createCommand()->createIndex('idx_test_name', 'test', 'name', 'FULLTEXT')->execute(); +``` + +### Bitmap index + +In `Oracle`, you can create a bitmap index by specifying the `bitmap` option in the `$indexType` parameter. + +```php +createCommand()->createIndex('idx_test_name', 'test', 'id', 'BITMAP')->execute(); +``` + +## Creating a table + +To create a table, you can use the `Yiisoft\Db\Command\CommandInterface::createTable()` method. + +The following example shows how to create a table in an agnostic way. + +```php +createCommand()->createTable( + '{{%customer}}', + [ + 'id' => 'pk', + 'name' => 'string(255) NOT NULL', + 'email' => 'string(255) NOT NULL', + 'status' => 'integer NOT NULL', + 'created_at' => 'datetime NOT NULL', + ], +)->execute(); + +This results in the following SQL execution in `MSSQL`. + +```sql +CREATE TABLE [customer] ( + [id] int IDENTITY PRIMARY KEY, + [name] nvarchar(255) NOT NULL, + [email] nvarchar(255) NOT NULL, + [status] int NOT NULL, + [created_at] datetime NOT NULL +) +``` + +This results in the following SQL execution in `MySQL`/`MariaDB`. + +```sql +CREATE TABLE `customer` ( + `id` int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, + `name` varchar(255) NOT NULL, + `email` varchar(255) NOT NULL, + `status` int(11) NOT NULL, + `created_at` datetime(0) NOT NULL +) +``` + +This results in the following SQL execution in `Oracle`. + +```sql +CREATE TABLE "customer" ( + "id" NUMBER(10) NOT NULL PRIMARY KEY, + "name" VARCHAR2(255) NOT NULL, + "email" VARCHAR2(255) NOT NULL, + "status" NUMBER(10) NOT NULL, + "created_at" TIMESTAMP NOT NULL +) +``` + +This results in the following SQL execution in `PostgreSQL`. + +```sql +CREATE TABLE "customer" ( + "id" serial NOT NULL PRIMARY KEY, + "name" varchar(255) NOT NULL, + "email" varchar(255) NOT NULL, + "status" integer NOT NULL, + "created_at" timestamp(0) NOT NULL +) +``` + +This results in the following SQL execution in `SQLite`. + +```sql +CREATE TABLE "customer" ( + `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL, + `name` varchar(255) NOT NULL, + `email` varchar(255) NOT NULL, + `status` integer NOT NULL, + `created_at` datetime NOT NULL +) +``` + +## Drop `CHECK` constraint + +To drop an existing `CHECK` constraint, you can use the `Yiisoft\Db\Command\CommandInterface::dropCheck()` method. + +The following example shows how to drop an existing `CHECK` constraint. + +```php +createCommand()->dropCheck('ck-customer-status', '{{%customer}}')->execute(); +``` + +## Drop column + +To drop an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::dropColumn()` method. + +The following example shows how to drop an existing column. + +```php +createCommand()->dropColumn('{{%customer}}', 'profile_id')->execute(); +``` + +## Drop comment from column + +To drop a comment from an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::dropCommentFromColumn()` +method. + +The following example shows how to drop a comment from an existing column. + +```php +createCommand()->dropCommentFromColumn('{{%customer}}', 'name')->execute(); +``` + +## Drop comment from table + +To drop a comment from an existing table, you can use the `Yiisoft\Db\Command\CommandInterface::dropCommentFromTable()` +method. + +The following example shows how to drop a comment from an existing table. + +```php +createCommand()->dropCommentFromTable('{{%customer}}')->execute(); +``` + +## Drop default value from column + +To drop a default value from an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::dropDefaultValue()` +method. + +The following example shows how to drop a default value from an existing column. + +```php +createCommand()->dropDefaultValue('df-customer-name', '{{%customer}}')->execute(); +``` + +## Dropping a foreign key + +To drop an existing foreign key, you can use the `Yiisoft\Db\Command\CommandInterface::dropForeignKey()` method. + +The following example shows how to drop an existing foreign key. + +```php +createCommand()->dropForeignKey('fk-customer-profile_id', '{{%customer}}')->execute(); +``` + +## Dropping an index + +To drop an existing index, you can use the `Yiisoft\Db\Command\CommandInterface::dropIndex()` method. + +The following example shows how to drop an existing index. + +```php +createCommand()->dropIndex('idx-customer-name', '{{%customer}}')->execute(); +``` + +## Drop a primary key + +To drop an existing primary key, you can use the `Yiisoft\Db\Command\CommandInterface::dropPrimaryKey()` method. + +The following example shows how to drop an existing primary key. + +```php +createCommand()->dropPrimaryKey('pk-customer-id', '{{%customer}}')->execute(); +``` + +## Drop a table + +To drop a table, you can use the `Yiisoft\Db\Command\CommandInterface::dropTable()` method. + +The following example shows how to drop a table. + +```php +createCommand()->dropTable('{{%customer}}')->execute(); +``` + +## Drop `UNIQUE` constraint + +To drop a unique constraint from an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::dropUnique()` +method. + +The following example shows how to drop a unique constraint from an existing column. + +```php +createCommand()->dropUnique('uq-customer-name', '{{%customer}}')->execute(); +``` + +## Rename a column + +To rename an existing column, you can use the `Yiisoft\Db\Command\CommandInterface::renameColumn()` method. + +The following example shows how to rename an existing column. + +```php +createCommand()->renameColumn('{{%customer}}', 'profile_id', 'profile_id_new')->execute(); +``` + +## Truncate a table + +To truncate a table, you can use the `Yiisoft\Db\Command\CommandInterface::truncateTable()` method. + +The following example shows how to truncate a table. + +```php +createCommand()->truncateTable('{{%customer}}')->execute(); +``` diff --git a/docs/en/command/dml.md b/docs/en/command/dml.md new file mode 100644 index 000000000..1f04113fc --- /dev/null +++ b/docs/en/command/dml.md @@ -0,0 +1,109 @@ +# Data Manipulation Language (DML) Commands + +DML is a set of SQL statements that are used to manipulate data in a database. + +The DML statements are used to perform the following operations. + +## Batch insert + +To insert many rows into a table, you can use the `Yiisoft\Db\Command\CommandInterface::batchInsert()` method. + +The following example shows how to insert many rows into a table. + +```php +createCommand()->batchInsert( + '{{%customer}}', + ['name', 'email'], + [ + ['user1', 'email1@email.com'], + ['user2', 'email2@email.com'], + ['user3', 'email3@email.com'], + ] +)->execute(); +``` + +## Delete rows + +To delete rows from a table, you can use the `Yiisoft\Db\Command\CommandInterface::delete()` method. + +The following example shows how to delete rows from a table. + +```php +createCommand()->delete('{{%customer}}', ['id' => 1])->execute(); +``` + +## Reset sequence + +To reset the sequence of a table, you can use the `Yiisoft\Db\Command\CommandInterface::resetSequence()` method. + +The following example shows how to reset the sequence of a table. + +```php +createCommand()->resetSequence('{{%customer}}', 1)->execute(); +``` + +## Update + +To update rows in a table, you can use the `Yiisoft\Db\Command\CommandInterface::update()` method. + +The following example shows how to update rows in a table. + +```php +createCommand()->update('{{%customer}}', ['status' => 2], ['id' > 1])->execute(); +``` + +## Upsert + +To upsert rows in a table, you can use the `Yiisoft\Db\Command\CommandInterface::upsert()` method. + +The following example shows how to upsert rows in a table. + +```php +createCommand()->upsert( + 'pages', + [ + 'name' => 'Front page', + 'url' => 'http://example.com/', // url is unique + 'visits' => 0, + ], + [ + 'visits' => new \Yiisoft\Db\Expression\Expression('visits + 1'), + ], + $params, +)->execute(); +``` diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 3cd22ffd6..4219f6760 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -109,3 +109,19 @@ $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. It's a powerful tool that can be used to create complex **SQL** statements in a simple way. + + +## Working with a database + +[Yii DB](https://github.com/yiisoft/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) + + + +