データベースフォージクラス

データベースフォージクラスには、データベースの管理に役立つメソッドが含まれています。

フォージクラスの初期化 

重要

フォージクラスを初期化するには、フォージクラスがデータベースドライバーに依存しているため、データベースドライバーが既に実行されている必要があります。

フォージクラスを次のようにロードします

<?php

$forge = \Config\Database::forge();

管理するデータベースがデフォルトではない場合、別のデータベースグループ名を DB フォージローダーに渡すこともできます

<?php

$this->myforge = \Config\Database::forge('other_db');

上記の例では、接続する別のデータベースグループの名前を最初のパラメーターとして渡しています。

データベースの作成と削除 

$forge->createDatabase('db_name')

最初のパラメーターで指定されたデータベースを作成できます。成功または失敗に基づいて true/false を返します

<?php

if ($forge->createDatabase('my_db')) {
    echo 'Database created!';
}

オプションの2番目のパラメーターを true に設定すると、`IF EXISTS` ステートメントが追加されるか、データベースを作成する前にデータベースが存在するかどうかがチェックされます（DBMS によって異なります）。

<?php

$forge->createDatabase('my_db', true);
/*
 * gives CREATE DATABASE IF NOT EXISTS `my_db`
 * or will check if a database exists
 */

$forge->dropDatabase('db_name')

最初のパラメーターで指定されたデータベースを削除できます。成功または失敗に基づいて true/false を返します

<?php

if ($forge->dropDatabase('my_db')) {
    echo 'Database deleted!';
}

コマンドラインでのデータベースの作成 

CodeIgniter は、専用の `db:create` コマンドを使用して、お気に入りのターミナルからデータベースを直接作成することをサポートしています。このコマンドを使用することにより、データベースはまだ存在しないと想定されます。そうでない場合、CodeIgniter はデータベースの作成に失敗したと訴えます。

開始するには、コマンドとデータベースの名前（例： `foo`）を入力します

php spark db:create foo

すべてがうまくいけば、`Database "foo" successfully created.` メッセージが表示されるはずです。

テスト環境にいる場合、または SQLite3 ドライバーを使用している場合は、`--ext` オプションを使用して、データベースが作成されるファイルのファイル拡張子を渡すことができます。有効な値は `db` と `sqlite` で、デフォルトは `db` です。これらにはピリオドを付けないでください。

php spark db:create foo --ext sqlite

上記のコマンドは、**WRITEPATH/foo.sqlite** に db ファイルを作成します。

注意

特別な SQLite3 データベース名 `:memory:` を使用する場合、コマンドは引き続き成功メッセージを生成しますが、データベースファイルは作成されません。これは、SQLite3 がインメモリデータベースを使用するためです。

テーブルの作成 

テーブルを作成するときに、いくつかのことを行うことができます。フィールドの追加、テーブルへのキーの追加、列の変更などです。CodeIgniter はこれを実現するためのメカニズムを提供しています。

フィールドの追加 

$forge->addField()

フィールドは通常、連想配列を介して作成されます。配列内には、フィールドのデータ型に関連する `type` キーを含める必要があります。

たとえば、`INT`、`VARCHAR`、`TEXT` などです。多くのデータ型（たとえば `VARCHAR`）には、`constraint` キーも必要です。

<?php

$fields = [
    'users' => [
        'type'       => 'VARCHAR',
        'constraint' => 100,
    ],
];
// will translate to "users VARCHAR(100)" when the field is added.

さらに、次のキーと値を使用できます

`unsigned`/true : フィールド定義に `UNSIGNED` を生成します。
`default`/値 : フィールド定義に `DEFAULT` 制約を生成します。
`null`/true : フィールド定義に `NULL` を生成します。これが無い場合、フィールドはデフォルトで `NOT NULL` になります。
`auto_increment`/true : フィールドに auto_increment フラグを生成します。フィールドタイプは `INTEGER` など、これをサポートするタイプである必要があります。
`unique`/true : フィールド定義に一意のキーを生成します。

<?php

$fields = [
    'id' => [
        'type'           => 'INT',
        'constraint'     => 5,
        'unsigned'       => true,
        'auto_increment' => true,
    ],
    'title' => [
        'type'       => 'VARCHAR',
        'constraint' => '100',
        'unique'     => true,
    ],
    'author' => [
        'type'       => 'VARCHAR',
        'constraint' => 100,
        'default'    => 'King of Town',
    ],
    'description' => [
        'type' => 'TEXT',
        'null' => true,
    ],
    'status' => [
        'type'       => 'ENUM',
        'constraint' => ['publish', 'pending', 'draft'],
        'default'    => 'pending',
    ],
];
$forge->addField($fields);

フィールドを定義した後、`$forge->addField($fields)` を使用して追加し、createTable() メソッドを呼び出すことができます。

データ型に関する注意事項

浮動小数点型

FLOAT や DOUBLE などの浮動小数点型は、近似値を表します。そのため、正確な値が必要な場合は使用しないでください。

mysql> CREATE TABLE t (f FLOAT, d DOUBLE);
mysql> INSERT INTO t VALUES(99.9, 99.9);

mysql> SELECT * FROM t WHERE f=99.9;
Empty set (0.00 sec)

mysql> SELECT * FROM t WHERE f > 99.89 AND f < 99.91;
+------+------+
| f    | d    |
+------+------+
| 99.9 | 99.9 |
+------+------+
1 row in set (0.01 sec)

金額データなど、正確な精度を維持することが重要な場合は、DECIMAL または NUMERIC を使用する必要があります。

TEXT

SQLSRV では TEXT を使用しないでください。非推奨です。 ntext、text、および image (Transact-SQL) - SQL Server | Microsoft Learn を参照してください。

デフォルト値としてのRaw SQL文字列

バージョン 4.2.0 での新機能。

v4.2.0 以降、$forge->addField() は、生の SQL 文字列を表す CodeIgniter\Database\RawSql インスタンスを受け入れます。

<?php

use CodeIgniter\Database\RawSql;

$fields = [
    'id' => [
        'type'           => 'INT',
        'constraint'     => 5,
        'unsigned'       => true,
        'auto_increment' => true,
    ],
    'created_at' => [
        'type'    => 'TIMESTAMP',
        'default' => new RawSql('CURRENT_TIMESTAMP'),
    ],
];
$forge->addField($fields);
/*
gives:
    "id" INT(5) UNSIGNED NOT NULL AUTO_INCREMENT,
    "created_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
*/

警告

RawSql を使用する場合、データは手動でエスケープする必要があります。そうしないと、SQL インジェクションが発生する可能性があります。

文字列をフィールドとして渡す

フィールドの作成方法を正確に知っている場合は、addField() を使用して文字列をフィールド定義に渡すことができます。

<?php

$forge->addField("label varchar(100) NOT NULL DEFAULT 'default label'");

注意

生の文字列をフィールドとして渡した場合、それらのフィールドに対して addKey() を呼び出すことはできません。

注意

addField() の複数回の呼び出しは累積されます。

id フィールドの作成

id フィールドの作成には特別な例外があります。型が id のフィールドは、自動的に INT(9) の自動インクリメント主キーとして割り当てられます。

<?php

$forge->addField('id');
// gives `id` INT(9) NOT NULL AUTO_INCREMENT

一般的に、テーブルにはキーが必要です。これは $forge->addKey('field') で実現できます。オプションの2番目のパラメータを true に設定すると主キーになり、3番目のパラメータを true に設定すると一意キーになります。4番目のパラメータで名前を指定できます。テーブルが既に存在する場合、addKey() の後に createTable() または processIndexes() を呼び出す必要があることに注意してください。

複数列の非主キーは配列として送信する必要があります。以下の出力例は MySQL のものです。

<?php

$forge->addKey('blog_id', true);
// gives PRIMARY KEY `blog_id` (`blog_id`)

$forge->addKey('blog_id', true);
$forge->addKey('site_id', true);
// gives PRIMARY KEY `blog_id_site_id` (`blog_id`, `site_id`)

$forge->addKey('blog_name');
// gives KEY `blog_name` (`blog_name`)

$forge->addKey(['blog_name', 'blog_label'], false, false, 'my_key_name');
// gives KEY `my_key_name` (`blog_name`, `blog_label`)

$forge->addKey(['blog_id', 'uri'], false, true, 'my_key_name');
// gives UNIQUE KEY `my_key_name` (`blog_id`, `uri`)

$forge->addPrimaryKey()

$forge->addUniqueKey()

コードの可読性を高めるために、特定のメソッドを使用して主キーと一意キーを追加することもできます。

<?php

$forge->addPrimaryKey('blog_id', 'pd_name');
// gives PRIMARY KEY `pd_name` (`blog_id`)

$forge->addUniqueKey(['blog_id', 'uri'], 'key_name');
// gives UNIQUE KEY `key_name` (`blog_id`, `uri`)

注意

主キーを追加すると、MySQL と SQLite は名前が指定されていても PRIMARY という名前を想定します。

外部キーの追加 

外部キーは、テーブル間の関係とアクションを強制するのに役立ちます。外部キーをサポートするテーブルの場合、forge で直接追加できます。

<?php

$forge->addForeignKey('users_id', 'users', 'id');
// gives CONSTRAINT `TABLENAME_users_id_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`)

$forge->addForeignKey(['users_id', 'users_name'], 'users', ['id', 'name']);
// gives CONSTRAINT `TABLENAME_users_id_foreign` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`)

制約の「更新時」と「削除時」のプロパティ、および名前について、目的のアクションを指定できます。

<?php

$forge->addForeignKey('users_id', 'users', 'id', 'CASCADE', 'CASCADE', 'my_fk_name');
// gives CONSTRAINT `my_fk_name` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`) ON DELETE CASCADE ON UPDATE CASCADE

$forge->addForeignKey('users_id', 'users', 'id', '', 'CASCADE');
// gives CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`) ON DELETE CASCADE

$forge->addForeignKey(['users_id', 'users_name'], 'users', ['id', 'name'], 'CASCADE', 'CASCADE', 'my_fk_name');
// gives CONSTRAINT `my_fk_name` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`) ON DELETE CASCADE ON UPDATE CASCADE

注意

SQLite3 は外部キーの名前付けをサポートしていません。CodeIgniter は、prefix_table_column_foreign によってそれらを参照します。

テーブルの作成 

フィールドとキーを宣言した後、次の方法で新しいテーブルを作成できます。

<?php

$forge->createTable('table_name');
// gives CREATE TABLE table_name

オプションの2番目のパラメータを true に設定すると、テーブルがまだ存在しない場合にのみテーブルが作成されます。

<?php

$forge->createTable('table_name', true);
// creates table only if table does not exist

MySQL の ENGINE など、オプションのテーブル属性を渡すこともできます。

<?php

$attributes = ['ENGINE' => 'InnoDB'];
$forge->createTable('table_name', false, $attributes);
// produces: CREATE TABLE `table_name` (...) ENGINE = InnoDB DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci

注意

CHARACTER SET 属性または COLLATE 属性 (あるいはその両方) を指定しない限り、createTable() は、設定されている *charset* 値と *DBCollat* 値が空でない限り、常にそれらをこれらの値と共に追加します (MySQL のみ)。

テーブルの削除 

DROP TABLE 文を実行し、オプションで IF EXISTS 句を追加します。

<?php

// Produces: DROP TABLE `table_name`
$forge->dropTable('table_name');

// Produces: DROP TABLE IF EXISTS `table_name`
$forge->dropTable('table_name', true);

3 番目のパラメータを渡して CASCADE オプションを追加できます。これは、外部キーを持つテーブルの削除を処理するために一部のドライバで必要になる場合があります。

<?php

// Produces: DROP TABLE `table_name` CASCADE
$forge->dropTable('table_name', false, true);

テーブルの変更 

テーブルへのフィールドの追加 

$forge->addColumn()

addColumn() メソッドは、既存のテーブルを変更するために使用されます。テーブルの作成と同じフィールド配列を受け取り、追加のフィールドを追加するために使用できます。

注意

テーブルを作成する場合とは異なり、null が指定されていない場合、列は NOT NULL ではなく NULL になります。

<?php

$fields = [
    'preferences' => ['type' => 'TEXT'],
];
$forge->addColumn('table_name', $fields);
// Executes: ALTER TABLE `table_name` ADD `preferences` TEXT

MySQL または CUBIRD を使用している場合は、AFTER 句と FIRST 句を利用して新しい列を配置できます。

例

<?php

// Will place the new column after the `another_field` column:
$fields = [
    'preferences' => ['type' => 'TEXT', 'after' => 'another_field'],
];

// Will place the new column at the start of the table definition:
$fields = [
    'preferences' => ['type' => 'TEXT', 'first' => true],
];

テーブルからのフィールドの削除 

$forge->dropColumn()

テーブルから列を削除するために使用されます。

<?php

$forge->dropColumn('table_name', 'column_to_drop'); // to drop one single column

テーブルから複数の列を削除するために使用されます。

<?php

$forge->dropColumn('table_name', 'column_1,column_2');      // by proving comma separated column names
$forge->dropColumn('table_name', ['column_1', 'column_2']); // by proving array of column names

テーブル内のフィールドの変更 

$forge->modifyColumn()

このメソッドの使い方は addColumn() と同じですが、新しい列を追加するのではなく、既存の列を変更するという点が異なります。名前を変更するには、フィールド定義配列に「name」キーを追加します。

<?php

$fields = [
    'old_name' => [
        'name' => 'new_name',
        'type' => 'TEXT',
        'null' => false,
    ],
];
$forge->modifyColumn('table_name', $fields);
// gives ALTER TABLE `table_name` CHANGE `old_name` `new_name` TEXT NOT NULL

注意

modifyColumn() は、予期せず NULL/NOT NULL を変更する場合があります。そのため、null キーの値を常に指定することをお勧めします。テーブルを作成する場合とは異なり、null が指定されていない場合、列は NOT NULL ではなく NULL になります。

注意

バグのため、v4.3.4 より前では、'null' => false を指定しても、SQLite3 は NOT NULL を設定しない場合があります。

注意

バグのため、v4.3.4 より前では、'null' => true を指定しても、Postgres と SQLSRV は NOT NULL を設定します。

テーブルへのキーの追加 

バージョン 4.3.0 での新機能。

addKey()、addPrimaryKey()、addUniqueKey()、addForeignKey()、および processIndexes() を使用して、既存のテーブルにキーを追加できます。

<?php

$this->forge->addKey(['category', 'name'], false, false, 'category_name');
$this->forge->addPrimaryKey('id', 'pk_actions');
$this->forge->addForeignKey('userid', 'user', 'id', '', '', 'userid_fk');
$this->forge->processIndexes('actions');
/* gives:
ALTER TABLE `actions` ADD KEY `category_name` (`category`, `name`);
ALTER TABLE `actions` ADD CONSTRAINT `pk_actions` PRIMARY KEY(`id`);
ALTER TABLE `actions` ADD CONSTRAINT `userid_fk` FOREIGN KEY (`userid`) REFERENCES `user`(`id`);
*/

主キーの削除 

バージョン 4.3.0 での新機能。

DROP PRIMARY KEY を実行します。

<?php

// MySQLi Produces: ALTER TABLE `tablename` DROP PRIMARY KEY
// Others Produces: ALTER TABLE `tablename` DROP CONSTRAINT `pk_tablename`
$forge->dropPrimaryKey('tablename');

キーの削除 

DROP KEY を実行します。

<?php

// For Indexes Produces:        DROP INDEX `users_index` ON `tablename`
// For Unique Indexes Produces: ALTER TABLE `tablename` DROP CONSTRAINT `users_index`
$forge->dropKey('tablename', 'users_index', false);

外部キーの削除 

DROP FOREIGN KEY を実行します。

<?php

// Produces: ALTER TABLE `tablename` DROP FOREIGN KEY `users_foreign`
$forge->dropForeignKey('tablename', 'users_foreign');

テーブルの名前変更 

テーブルの名前変更を実行します。

<?php

$forge->renameTable('old_table_name', 'new_table_name');
// gives ALTER TABLE `old_table_name` RENAME TO `new_table_name`

クラスリファレンス 

class CodeIgniter\Database\Forge

addColumn($table[, $field = []])

パラメータ:

$table (string) – 列を追加するテーブル名
$field (array) – 列定義

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

既存のテーブルに列を追加します。使用方法：テーブルにフィールドを追加するを参照してください。

addField($field)

パラメータ:

$field (array) – 追加するフィールド定義

戻り値:

\CodeIgniter\Database\Forge インスタンス (メソッドチェーン)

戻り値の型:

\CodeIgniter\Database\Forge

テーブルの作成に使用されるセットにフィールドを追加します。使用方法：フィールドの追加を参照してください。

addForeignKey($fieldName, $tableName, $tableField[, $onUpdate = '', $onDelete = '', $fkName = ''])

パラメータ:

$fieldName (string|string[]) – キーフィールドの名前またはフィールドの配列
$tableName (string) – 親テーブルの名前
$tableField (string|string[]) – 親テーブルのフィールド名またはフィールドの配列
$onUpdate (string) – 「更新時」に実行するアクション
$onDelete (string) – 「削除時」に実行するアクション
$fkName (string) – 外部キーの名前。これはSQLite3では機能しません

戻り値:

\CodeIgniter\Database\Forge インスタンス (メソッドチェーン)

戻り値の型:

\CodeIgniter\Database\Forge

テーブルの作成に使用されるセットに外部キーを追加します。使用方法：外部キーの追加を参照してください。

注意

$fkName はv4.3.0以降で使用できます。

addKey($key[, $primary = false[, $unique = false[, $keyName = '']]])

パラメータ:

$key (mixed) – キーフィールドの名前またはフィールドの配列
$primary (bool) – プライマリキーにする場合はtrue、そうでない場合はfalseを設定します
$unique (bool) – ユニークキーにする場合はtrue、そうでない場合はfalseを設定します
$keyName (string) – 追加するキーの名前

戻り値:

\CodeIgniter\Database\Forge インスタンス (メソッドチェーン)

戻り値の型:

\CodeIgniter\Database\Forge

テーブルの作成に使用されるセットにキーを追加します。使用方法：キーの追加を参照してください。

注意

$keyName はv4.3.0以降で使用できます。

addPrimaryKey($key[, $keyName = ''])

パラメータ:

$key (mixed) – キーフィールドの名前またはフィールドの配列
$keyName (string) – 追加するキーの名前

戻り値:

\CodeIgniter\Database\Forge インスタンス (メソッドチェーン)

戻り値の型:

\CodeIgniter\Database\Forge

テーブルの作成に使用されるセットにプライマリキーを追加します。使用方法：キーの追加を参照してください。

注意

$keyName はv4.3.0以降で使用できます。

addUniqueKey($key[, $keyName = ''])

パラメータ:

$key (mixed) – キーフィールドの名前またはフィールドの配列
$keyName (string) – 追加するキーの名前

戻り値:

\CodeIgniter\Database\Forge インスタンス (メソッドチェーン)

戻り値の型:

\CodeIgniter\Database\Forge

テーブルの作成に使用されるセットにユニークキーを追加します。使用方法：キーの追加を参照してください。

注意

$keyName はv4.3.0以降で使用できます。

createDatabase($dbName[, $ifNotExists = false])

パラメータ:

$db_name (string) – 作成するデータベースの名前
$ifNotExists (string) – IF NOT EXISTS 句を追加するか、データベースが存在するかどうかを確認する場合はtrueに設定します

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

新しいデータベースを作成します。使用方法：データベースの作成と削除を参照してください。

createTable($table[, $if_not_exists = false[, array $attributes = []]])

パラメータ:

$table (string) – 作成するテーブルの名前
$if_not_exists (string) – IF NOT EXISTS 句を追加する場合はtrueに設定します
$attributes (string) – テーブル属性の連想配列

戻り値:

成功時はクエリオブジェクト、失敗時はfalse

戻り値の型:

mixed

新しいテーブルを作成します。使用方法：テーブルの作成を参照してください。

dropColumn($table, $column_name)

パラメータ:

$table (string) – テーブル名
$column_names (mixed) – カンマ区切りの文字列または列名の配列

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

テーブルから単一または複数の列を削除します。使用方法：テーブルからのフィールドの削除を参照してください。

dropDatabase($dbName)

パラメータ:

$dbName (string) – 削除するデータベースの名前

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

データベースを削除します。使用方法：データベースの作成と削除を参照してください。

dropKey($table, $keyName[, $prefixKeyName = true])

パラメータ:

$table (string) – キーを持つテーブルの名前
$keyName (string) – 削除するキーの名前
$prefixKeyName (string) – $keyName にデータベースプレフィックスを追加する必要がある場合

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

インデックスまたはユニークインデックスを削除します。

注意

$keyName と $prefixKeyName はv4.3.0以降で使用できます。

dropPrimaryKey($table[, $keyName = ''])

パラメータ:

$table (string) – プライマリキーを削除するテーブルの名前
$keyName (string) – 削除するプライマリキーの名前

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

テーブルからプライマリキーを削除します。

注意

$keyName はv4.3.0以降で使用できます。

dropTable($table_name[, $if_exists = false])

パラメータ:

$table (string) – 削除するテーブルの名前
$if_exists (string) – IF EXISTS 句を追加する場合はtrueに設定します

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

テーブルを削除します。使用方法：テーブルの削除を参照してください。

processIndexes($table)

バージョン 4.3.0 での新機能。

パラメータ:

$table (string) – インデックスを追加するテーブルの名前

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

addKey()、addPrimaryKey()、addUniqueKey()、およびaddForeignKey() の後に使用して、既存のテーブルにインデックスを追加します。テーブルへのキーの追加を参照してください。

modifyColumn($table, $field)

パラメータ:

$table (string) – テーブル名
$field (array) – 列定義

戻り値:

成功の場合は true、失敗の場合は false

戻り値の型:

bool

テーブルの列を変更します。使用方法：テーブルのフィールドの変更を参照してください。

renameTable($table_name, $new_table_name)

パラメータ:

$table (string) – 現在のテーブル名
$new_table_name (string) – テーブルの新しい名前

戻り値:

成功時はクエリオブジェクト、失敗時はfalse

戻り値の型:

mixed

テーブルの名前を変更します。使用方法：テーブル名の変更を参照してください。

データベースフォージクラス

$forge->addField()

データ型に関する注意事項

浮動小数点型

TEXT

デフォルト値としてのRaw SQL文字列

文字列をフィールドとして渡す

id フィールドの作成

$forge->addKey()

$forge->addPrimaryKey()

$forge->addUniqueKey()

$forge->addColumn()

$forge->dropColumn()

$forge->modifyColumn()