資料庫建構類別¶
資料庫建構類別將包含幫助你管理資料庫的方法。
初始化資料庫建構類別¶
重要
為了初始化 資料庫建構類別，你的資料庫驅動必須是正常執行的狀態，因為 資料庫建構類別將倚賴於它。
依照以下方法載入資料庫建構類別：
$forge = \Config\Database::forge();
你可將另外的資料庫群組名稱傳給資料庫建構載入器，預防你要管理的資料庫並不是你的預設資料庫：
$this->myforge = \Config\Database::forge('other_db');
在上述範例，我們傳入了一個不同的資料庫群組名稱作為參數來連接資料庫。
建立與刪除資料庫¶
$forge->createDatabase(『db_name』)
你能夠透過傳入參數至 createDatabase 方法來指定要建立的資料庫名稱，依據成功或失敗將回傳 TRUE/FALSE 。
if ($forge->createDatabase('my_db'))
{
echo 'Database created!';
}
這個方法有第二個可選參數，用於加入 IF EXISTS 語法至查詢中，以檢查是否已經有相同名稱的資料庫存在（這將取決於你所使用的 DBMS）。
$forge->createDatabase('my_db', TRUE);
// gives CREATE DATABASE IF NOT EXISTS my_db
// or will check if a database exists
$forge->dropDatabase(『db_name』)
你能夠透過傳入參數至 dropDatabase 方法來刪除你所指定的資料庫名稱，依據成功或失敗將回傳 TRUE/FALSE 。
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
// will create the db file in WRITEPATH/foo.sqlite
備註
使用特殊的 SQLite3 資料庫名稱 :memory: 時，這個指令也會回應你成功的訊息，但不會建立任何資料庫檔案。這是因為此時的 SQLite3 將會使用記憶體資料庫。
新建與棄用資料表¶
在建立資料表時，你可能有幾件需要做到的事。加入欄位、宣告主鍵、改變資料列。對於這個需求，CodeIgniter 提出了一種機制。
新增欄位¶
欄位通常是透過鍵值陣列建立的，在這個鍵值陣列中你必須包含一個與這個欄位相關的資料類型 「type」 鍵，例如：INT 、 VARCHAR ，以及 TEXT 等。許多資料型別（例如 VARCHAR ），會需要定義 「constraint」 鍵，約束它的最大資料長度。
$fields = [
'users' => [
'type' => 'VARCHAR',
'constraint' => 100,
],
];
// 將轉化為 "users VARCHAR(100)"
除此之外，還可以使用以下的鍵值進行定義：
- unsigned/true : 在欄位定義中產生 「UNSIGNED」 。
- default/value : 在欄位中定義產生一個預設值。
- null/true : 在欄位中定義產生 「NULL」 ，若沒有這個設定將會預設為 「NOT NULL」 。
- auto_increment/true : 將欄位設定為自動遞增。請注意，你所設定欄位型別必須職員這個功能，例如 integer 。
- unique/true : 替欄位定義產生一個唯一鍵。
$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); 方法，然後呼叫 createTable() 方法執行新增欄位的動作。
$forge->addField()
你將可以把上述的陣列傳入到這個方法中。
將字串作為欄位傳遞¶
如果你清楚地知道要如何創建一個欄位，你就可以將 SQL 字串傳入 addField() 方法。
$forge->addField("label varchar(100) NOT NULL DEFAULT 'default label'");
備註
若你傳入了 SQL 字串後作為欄位設定，就不能再繼續呼叫 addKey() 方法。
備註
在呼叫 createTable() 之前，多次的 addField() 呼叫將會累積你所定義的動作。
新建一個 id 欄位¶
在建立 id 欄位時會有一個特殊的例外。具有 id 名稱的欄位將自動被設定為 INT(9) 且自動遞增主鍵。
$forge->addField('id');
// gives id INT(9) NOT NULL AUTO_INCREMENT
新增資料庫鍵¶
一般來說，你的資料表會有一個主鍵，這可以透過 $forge->addKey(『field』) 來實作。這個方法有第二的可選參數，將它設定為 TRUE 時，它將會是主鍵；當它的第三個可選參數被設定為 TRUE 時，它則會成為唯一鍵。注意：在呼叫 addKey() 後必須呼叫 createTable() 。
多資料欄位且非主鍵的話必須以陣列的形式傳送，下面是 MySQL 的輸出範例。
$forge->addKey('blog_id', TRUE);
// 給予 PRIMARY KEY `blog_id` (`blog_id`)
$forge->addKey('blog_id', TRUE);
$forge->addKey('site_id', TRUE);
// 給予 PRIMARY KEY `blog_id_site_id` (`blog_id`, `site_id`)
$forge->addKey('blog_name');
// 給予 KEY `blog_name` (`blog_name`)
$forge->addKey(['blog_name', 'blog_label']);
// 給予 KEY `blog_name_blog_label` (`blog_name`, `blog_label`)
$forge->addKey(['blog_id', 'uri'], FALSE, TRUE);
// 給予 UNIQUE KEY `blog_id_uri` (`blog_id`, `uri`)
為了使程式碼更容易閱讀，還可以使用特定的方法加入主鍵與唯一鍵：
$forge->addPrimaryKey('blog_id');
// 給予 PRIMARY KEY `blog_id` (`blog_id`)
$forge->addUniqueKey(['blog_id', 'uri']);
// 給予 UNIQUE KEY `blog_id_uri` (`blog_id`, `uri`)
新增外來鍵¶
外來鍵有助於資料表的關聯操作，對於需要使用外來鍵的資料表，你可以直接在資料庫建構類別中加入外來鍵：
$forge->addForeignKey('users_id','users','id');
// 給予 CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`)
$forge->addForeignKey(['users_id', 'users_name'],'users',['id', 'name']);
// 給予 CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`)
你可以額外約束 「on delete」 與 「on update」 屬性：
$forge->addForeignKey('users_id','users','id','CASCADE','CASCADE');
// 給予 CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`) ON DELETE CASCADE ON UPDATE CASCADE
$forge->addForeignKey(['users_id', 'users_name'],'users',['id', 'name'],'CASCADE','CASCADE');
// 給予 CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`) ON DELETE CASCADE ON UPDATE CASCADE
新建資料表¶
在宣告了欄位與外來鍵之後，你就可以新建一個資料表了：
$forge->createTable('table_name');
// 給予 CREATE TABLE table_name
將可選的第二參數傳入 TRUE ，將在查詢中增加 「IF NOT EXISTS」 子句：
$forge->createTable('table_name', TRUE);
// 給予 CREATE TABLE IF NOT EXISTS table_name
你也可以傳遞可選的資料表屬性，比如 MySQL 的 ENGINE ：
$attributes = ['ENGINE' => 'InnoDB'];
$forge->createTable('table_name', FALSE, $attributes);
// 生成: 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 子句。
// 生成: DROP TABLE table_name
$forge->dropTable('table_name');
// 生成: DROP TABLE IF EXISTS table_name
$forge->dropTable('table_name',TRUE);
你能夠加入 true 作為方法的第三個參數，這個選項將產生 「CASCADE」 的效果。某些驅動程式在刪除上，可能需要會這個選項來處理帶有外來鍵的資料表。
// Produces: DROP TABLE `table_name` CASCADE
$forge->dropTable('table_name', false, true);
棄用外來鍵¶
執行 DROP FOREIGN KEY 語句。
// 生成: ALTER TABLE 'tablename' DROP FOREIGN KEY 'users_foreign'
$forge->dropForeignKey('tablename','users_foreign');
Dropping a Key¶
Execute a DROP KEY.
// Produces: DROP INDEX `users_index` ON `tablename`
$forge->dropKey('tablename','users_index');
修改資料表¶
新增一個資料表欄位¶
$forge->addColumn()
addColumn() 方法用於修改一個現有的資料表，它接受與上述相同的欄位陣列，並可以用於不限量的附加欄位。
$fields = [
'preferences' => ['type' => 'TEXT']
];
$forge->addColumn('table_name', $fields);
// 執行: ALTER TABLE table_name ADD preferences TEXT
如果你使用的是 MySQL 或 CUBIRD ，你可以會利用他們的 AFTER 或 FIRST 子句來定位新的資料欄位。
例如：
// 將把新的資料列放在 `another_field` 資料列之後:
$fields = [
'preferences' => ['type' => 'TEXT', 'after' => 'another_field']
];
// 將把新的資料列定義在起始處:
$fields = [
'preferences' => ['type' => 'TEXT', 'first' => TRUE]
];
類別參考¶
-
CodeIgniter\Database\Forge -
addColumn($table[, $field = []])¶ 參數: - $table (string) – 欲新增資料列的資料表名稱
- $field (array) – 資料欄位定義
傳回: TRUE 為成功， FALSE 為失敗
傳回型態: bool
在資料表內新增資料列。 使用方式：請見 新增一個資料表欄位.
-
addField($field)¶ 參數: - $field (array) – 要加入的欄位定義。
傳回: CodeIgniterDatabaseForge 實體（方法鏈）
傳回型態: CodeIgniterDatabaseForge
將欄位添加到用於創建資料表的集合中。 使用方式：請見 新增欄位.
-
addForeignKey($fieldName, $tableName, $tableField[, $onUpdate = '', $onDelete = ''])¶ 參數: - $fieldName (string|string[]) – 欄位名稱或是欄位名稱陣列
- $tableName (string) – 父資料表名稱
- $tableField (string|string[]) – 父資料表欄位名稱或是欄位名稱陣列
- $onUpdate (string) – 希望 on update 時採取的行動
- $onDelete (string) – 希望 on delete 時採取的行動
傳回: CodeIgniterDatabaseForge instance (method chaining)
傳回型態: CodeIgniterDatabaseForge
在新建資料表的過程中加入外來建，使用方法請參閱 新增外來鍵 。
-
addKey($key[, $primary = FALSE[, $unique = FALSE]])¶ 參數: - $key (mixed) – 欄位鍵名或欄位陣列
- $primary (bool) – 為 TRUE 與否判斷是主鍵或普通鍵
- $unique (bool) – 為 TRUE 與否判斷是唯一鍵或普通鍵
傳回: CodeIgniterDatabaseForge 實體（方法鏈）
傳回型態: CodeIgniterDatabaseForge
將資料庫鍵新增到用於創建資料表的集合中。 使用方式：請見 新增資料庫鍵.
-
addPrimaryKey($key)¶ 參數: - $key (mixed) – 欄位鍵名或欄位陣列
傳回: CodeIgniterDatabaseForge 實體（方法鏈）
傳回型態: CodeIgniterDatabaseForge
將主鍵新增到用於創建資料表的集合中。 使用方式：請見 新增資料庫鍵.
-
addUniqueKey($key)¶ 參數: - $key (mixed) – 欄位鍵名或欄位陣列
傳回: CodeIgniterDatabaseForge 實體（方法鏈）
傳回型態: CodeIgniterDatabaseForge
將唯一鍵新增到用於創建資料表的集合中。 使用方式：請見 新增資料庫鍵.
-
createDatabase($dbName[, $ifNotExists = FALSE])¶ 參數: - $db_name (string) – 欲新增的資料庫名稱
- $ifNotExists (string) – 為 true 將可以添加用於檢查資料庫是否存在的 「IF NOT EXISTS」 子句。
傳回: TRUE 為成功， FALSE 為失敗
傳回型態: bool
新增一個新的資料庫。 使用方式：請見 建立與刪除資料庫.
-
createTable($table[, $if_not_exists = FALSE[, array $attributes = []]])¶ 參數: - $table (string) – 欲建立的資料表名稱
- $if_not_exists (string) – 為 true 將添加 『IF NOT EXISTS』 子句
- $attributes (string) – 資料表屬性的鍵值陣列
傳回: 查詢生成器物件為成功， FALSE 為失敗
傳回型態: mixed
新增一個新的資料表。 使用方式：請見 新建資料表.
-
dropColumn($table, $column_name)¶ 參數: - $table (string) – 資料表名稱
- $column_names (mixed) – 逗號分隔的字串或欄位名稱組成的陣列
傳回: TRUE 為成功， FALSE 為失敗
傳回型態: bool
棄用一個或多個資料表欄位。 使用方式：請見 棄用一個資料表欄位.
-
dropDatabase($dbName)¶ 參數: - $dbName (string) – 欲棄用的資料庫名稱
傳回: TRUE 為成功， FALSE 為失敗
傳回型態: bool
棄用資料庫。 使用方式：請見 建立與刪除資料庫.
-
dropTable($table_name[, $if_exists = FALSE])¶ 參數: - $table (string) – 欲器用的資料表名稱
- $if_exists (string) – 為 TRUE 則加入 『IF EXISTS』 子句
傳回: TRUE 為成功， FALSE 為失敗
傳回型態: bool
棄用資料表。 使用方式：請見 棄用資料表.
-