資料庫建構類別

資料庫建構類別將包含幫助你管理資料庫的方法。

初始化資料庫建構類別

重要

為了初始化 資料庫建構類別,你的資料庫驅動必須是正常運作的狀態,因為 資料庫建構類別將倚賴於它。

依照以下方法載入資料庫建構類別:

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

你可將另外的資料庫群組名稱傳給資料庫建構載入器,預防你要管理的資料庫並不是你的預設資料庫:

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

在上述範例,我們傳入了一個不同的資料庫群組名稱作為參數來連接資料庫。

Creating and Dropping Databases

$forge->createDatabase(『db_name』)

Permits you to create the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:

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

An optional second parameter set to TRUE will add IF EXISTS statement or will check if a database exists before create it (depending on 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』)

Permits you to drop the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:

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

Creating Databases in the Command Line

CodeIgniter supports creating databases straight from your favorite terminal using the dedicated db:create command. By using this command it is assumed that the database is not yet existing. Otherwise, CodeIgniter will complain that the database creation has failed.

To start, just type the command and the name of the database (e.g., foo):

php spark db:create foo

If everything went fine, you should expect the Database "foo" successfully created. message displayed.

If you are on a testing environment or you are using the SQLite3 driver, you may pass in the file extension for the file where the database will be created using the --ext option. Valid values are db and sqlite and defaults to db. Remember that these should not be preceded by a period.

php spark db:create foo --ext sqlite
// will create the db file in WRITEPATH/foo.sqlite

備註

When using the special SQLite3 database name :memory:, expect that the command will still produce a success message but no database file is created. This is because SQLite3 will just use an in-memory database.

新建與棄用資料庫

$forge->createDatabase(『db_name』)

允許你傳入資料庫名稱來新建資料庫,根據成功與否回傳 TRUE 或 FALSE :

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

第二個可選參數若設定為 TRUE ,將會在查詢中加入 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』)

允許你傳入資料庫名稱並棄用這個資料庫,根據成功與否回傳 TRUE 或 FALSE :

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

Creating Databases in the Command Line

CodeIgniter supports creating databases straight from your favorite terminal using the dedicated db:create command. By using this command it is assumed that the database is not yet existing. Otherwise, CodeIgniter will complain that the database creation has failed.

To start, just type the command and the name of the database (e.g., foo):

php spark db:create foo

If everything went fine, you should expect the Database "foo" successfully created. message displayed.

If you are on a testing environment or you are using the SQLite3 driver, you may pass in the file extension for the file where the database will be created using the --ext option. Valid values are db and sqlite and defaults to db. Remember that these should not be preceded by a period.

php spark db:create foo --ext sqlite
// will create the db file in WRITEPATH/foo.sqlite

備註

When using the special SQLite3 database name :memory:, expect that the command will still produce a success message but no database file is created. This is because SQLite3 will just use an in-memory database.

新建與棄用資料表

在建立資料表時,你可能有幾件需要做到的事。加入欄位、宣告主鍵、改變資料列。對於這個需求,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`)

你可以額外約束 「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->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);

棄用外來鍵

執行 DROP FOREIGN KEY 語句。

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

重新命名資料表

執行 TABLE 重新命名語句。

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

修改資料表

新增一個資料表欄位

$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]
];

棄用一個資料表欄位

$forge->dropColumn()

用來刪除資料表中的資料列。

$forge->dropColumn('table_name', 'column_to_drop'); // 刪除單一資料列

用來刪除資料表中的多個資料列。

$forge->dropColumn('table_name', 'column_1,column_2'); // 透過逗號分割名稱
$forge->dropColumn('table_name', ['column_1', 'column_2']); // 透過陣列傳遞名稱

修改資料表欄位

$forge->modifyColumn()

這個方法的使用方式與 addColumn() 相同,它只是改變了一個現有的資料欄位,而不是增價一個新的資料欄位。為了改變名稱,可以在欄位定義的陣列中新增一個 「name」 鍵。

$fields = [
        'old_name' => [
                'name' => 'new_name',
                'type' => 'TEXT',
        ],
];
$forge->modifyColumn('table_name', $fields);
// 給予 ALTER TABLE table_name CHANGE old_name new_name TEXT

類別參考

CodeIgniter\Database\Forge
addColumn($table[, $field = []])
參數:
  • $table (string) – 欲新增資料列的資料表名稱
  • $field (array) – 資料欄位定義
傳回:

TRUE 為成功, FALSE 為失敗

傳回型態:

bool

在資料表內新增資料列。 使用方式:請見 新增一個資料表欄位.

addField($field)
參數:
  • $field (array) – 要加入的欄位定義。
傳回:

CodeIgniterDatabaseForge 實體(方法鏈)

傳回型態:

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

棄用資料表。 使用方式:請見 棄用資料表.

modifyColumn($table, $field)
參數:
  • $table (string) – 資料表名稱
  • $field (array) – 自訂資料欄位
傳回:

TRUE 為成功, FALSE 為失敗

傳回型態:

bool

修改資料庫欄位。 使用方式:請見 修改資料表欄位.

renameTable($table_name, $new_table_name)
參數:
  • $table (string) – 目前的資料表名稱
  • $new_table_name (string) – 新的資料表名稱
傳回:

查詢生成器物件為成功, FALSE 為失敗

傳回型態:

mixed

重新命名資料表。 使用方式:請見 重新命名資料表.