數據庫抽象層（Database Abstraction Layer） · Phalcon中文文檔2.0.6

# 數據庫抽象層（Database Abstraction Layer） # 數據庫抽象層（Database Abstraction Layer） [*Phalcon\\Db*](#) 是 [*Phalcon\\Mvc\\Model*](#) 背后的一個組件，它為框架提供了強大的model層。它是一個完全由C語言寫的獨立的高級抽象層的數據庫系統。這個組件提供了比傳統模式的更容易上手的數據庫操作。 > 這個指引不是一個完整的包含所有方法和它們的參數的文檔。查看完整的文檔參考，請訪問 [*API*](#) ### 數據庫適配器（Database Adapters）這個組件利用了這些適配器去封裝特定的數據庫的詳細操作。Phalcon使用 [PDO](http://www.php.net/manual/en/book.pdo.php) 去連接這些數據庫。下面這些是我們支持的數據庫引擎：名稱描述APIMySQLMySQL是這個世界上最多人使用的關系數據庫，它作為服務器運行為多用戶提供了訪問多個數據庫的功能。[*Phalcon\\Db\\Adapter\\Pdo\\Mysql*](#)PostgreSQLPostgreSQL是一個強大，開源的關系數據庫。它擁有超過15年的積極發展和經過驗證的架構，這些已經為它贏得了可靠性、數據完整性、正確性的良好的聲譽[*Phalcon\\Db\\Adapter\\Pdo\\Postgresql*](#)SQLiteSQLite是一個實現一個自包含的，無服務器，零配置，支持事務的SQL數據庫引擎的軟件庫[*Phalcon\\Db\\Adapter\\Pdo\\Sqlite*](#)OracleOracle是一個對象-關系數據庫，由甲骨文公司生產和銷售。[*Phalcon\\Db\\Adapter\\Pdo\\Oracle*](#)### 自定義適配器（Implementing your own adapters）如果你想創建自己的適配器或者擴展現有的適配器，這個 [*Phalcon\\Db\\AdapterInterface*](#) 接口必須被實現。 ### 數據庫“方言” Phalcon把每個數據庫引擎的具體操作封裝成“方言”，這些“方言”提供了提供通用的功能和SQL生成的適配器。(譯者注：這里的“方言”是指Phalcon把一些常用的數據庫操作封裝成類的方法，例如檢查數據庫中表是否存在，不再需要麻煩的手動寫SQL，可以把調用tableExists方法去查詢) 名稱描述APIMySQLMySQL的具體“方言”[*Phalcon\\Db\\Dialect\\Mysql*](#)PostgreSQLPostgreSQL的具體“方言”[*Phalcon\\Db\\Dialect\\Postgresql*](#)SQLiteSQLite的具體“方言”[*Phalcon\\Db\\Dialect\\Sqlite*](#)OracleOracle的具體“方言”[*Phalcon\\Db\\Dialect\\Oracle*](#)### 自定義“方言”（Implementing your own dialects）如果你想創建自己的“方言”或者擴展現有的“方言”，你需要實現這個接口： [*Phalcon\\Db\\DialectInterface*](#) ### 連接數據庫（Connecting to Databases）為了建立連接，實例化適配器類是必須的。它只接收一個包含連接參數的數組。下面的例子展示了，傳遞必要參數和可選項的參數去連接數據庫： ``` <pre class="calibre14">``` <?php // 必要參數 $config = array( "host" => "127.0.0.1", "username" => "mike", "password" => "sigma", "dbname" => "test_db" ); // 可選參數 $config["persistent"] = false; // 創建連接 $connection = new \Phalcon\Db\Adapter\Pdo\Mysql($config); ``` ``` ``` <pre class="calibre14">``` <?php // 必要參數 $config = array( "host" => "localhost", "username" => "postgres", "password" => "secret1", "dbname" => "template" ); // 可選參數 $config["schema"] = "public"; // 創建連接 $connection = new \Phalcon\Db\Adapter\Pdo\Postgresql($config); ``` ``` ``` <pre class="calibre14">``` <?php // 必要參數 $config = array( "dbname" => "/path/to/database.db" ); // 創建連接 $connection = new \Phalcon\Db\Adapter\Pdo\Sqlite($config); ``` ``` ``` <pre class="calibre14">``` <?php // 基本配置信息 $config = array( 'username' => 'scott', 'password' => 'tiger', 'dbname' => '192.168.10.145/orcl' ); // 高級配置信息 $config = array( 'dbname' => '(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=xe)(FAILOVER_MODE=(TYPE=SELECT)(METHOD=BASIC)(RETRIES=20)(DELAY=5))))', 'username' => 'scott', 'password' => 'tiger', 'charset' => 'AL32UTF8' ); // 創建連接 $connection = new \Phalcon\Db\Adapter\Pdo\Oracle($config); ``` ``` ### 設置額外的 PDO 選項（Setting up additional PDO options）你可以在連接的時候，通過傳遞'options'參數，設置PDO選項： ``` <pre class="calibre14">``` <?php // 帶PDO options參數的創建連接 $connection = new \Phalcon\Db\Adapter\Pdo\Mysql( array( "host" => "localhost", "username" => "root", "password" => "sigma", "dbname" => "test_db", "options" => array( PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES \'UTF8\'", PDO::ATTR_CASE => PDO::CASE_LOWER ) ) ); ``` ``` ### 查找行（Finding Rows）文檔 [*Phalcon\\Db*](#) 提供了幾種方法去查詢行。在這個例子中，SQL語句是必須符合數據庫的SQL語法的： ``` <pre class="calibre14">``` <?php $sql = "SELECT id, name FROM robots ORDER BY name"; // 發送SQL語句到數據庫 $result = $connection->query($sql); // 打印每個robot名稱 while ($robot = $result->fetch()) { echo $robot["name"]; } // 返回一個包含返回結果的數組 $robots = $connection->fetchAll($sql); foreach ($robots as $robot) { echo $robot["name"]; } // 只返回查詢結果的第一條數據 $robot = $connection->fetchOne($sql); ``` ``` 默認情況下，這些調用會建立一個數組，數組中包含以字段名和以數字下標為key的值。你可以改變這種行為通過使用 Phalcon\\Db\\Result::setFetchMode() 。這個方法接受一個常量值，確定哪些類型的指標是被要求的。常量描述Phalcon\\Db::FETCH\_NUM返回一個包含數字下標的數組Phalcon\\Db::FETCH\_ASSOC返回一個包含字段名的數組Phalcon\\Db::FETCH\_BOTH返回一個包含字段名和數字下標的數組Phalcon\\Db::FETCH\_OBJ返回一個對象而不是一個數組``` <pre class="calibre14">``` <?php $sql = "SELECT id, name FROM robots ORDER BY name"; $result = $connection->query($sql); $result->setFetchMode(Phalcon\Db::FETCH_NUM); while ($robot = $result->fetch()) { echo $robot[0]; } ``` ``` 這個 Phalcon\\Db::query() 方法返回一個 [*Phalcon\\Db\\Result\\Pdo*](#) 實例。這些對象封裝了凡是涉及到返回的結果集的功能，例如遍歷，尋找特定行，計算總行數等等 ``` <pre class="calibre14">``` <?php $sql = "SELECT id, name FROM robots"; $result = $connection->query($sql); // 遍歷結果集 while ($robot = $result->fetch()) { echo $robot["name"]; } // 獲取第三條記錄 $result->seek(2); $robot = $result->fetch(); // 計算結果集的記錄數 echo $result->numRows(); ``` ``` ### 綁定參數（Binding Parameters）在 [*Phalcon\\Db*](#) 中支持綁定參數。雖然使用綁定參數會有很少性能的損失，但是我們鼓勵你使用這個方法去消除(譯者注：是消除，不是減少，因為使用參數綁定可以徹底解決SQL注入問題)SQL注入攻擊的可能性。字符串和占位符都支持，就像下面展示的那樣，綁定參數可以簡單地實現： ``` <pre class="calibre14">``` <?php // 用數字占位符綁定參數 $sql = "SELECT * FROM robots WHERE name = ? ORDER BY name"; $result = $connection->query($sql, array("Wall-E")); // 用指定的占位符綁定參數 $sql = "INSERT INTO `robots`(name`, year) VALUES (:name, :year)"; $success = $connection->query($sql, array("name" => "Astro Boy", "year" => 1952)); ``` ``` When using numeric placeholders, you will need to define them as integers i.e. 1 or 2. In this case “1” or “2”are considered strings and not numbers, so the placeholder could not be successfully replaced. With any adapterdata are automatically escaped using [PDO Quote](http://www.php.net/manual/en/pdo.quote.php). This function takes into account the connection charset, so its recommended to define the correct charsetin the connection parameters or in your database server configuration, as a wrongcharset will produce undesired effects when storing or retrieving data. Also, you can pass your parameterers directly to the execute/query methods. In this casebound parameters are directly passed to PDO: ``` <pre class="calibre14">``` <?php // Binding with PDO placeholders $sql = "SELECT * FROM robots WHERE name = ? ORDER BY name"; $result = $connection->query($sql, array(1 => "Wall-E")); ``` ``` ### 插入、更新、刪除行（Inserting/Updating/Deleting Rows）去插入，更新或者刪除行，你可以使用原生SQL操作，或者使用類中預設的方法 ``` <pre class="calibre14">``` <?php // 使用原生SQL插入行 $sql = "INSERT INTO `robots`(`name`, `year`) VALUES ('Astro Boy', 1952)"; $success = $connection->execute($sql); // 使用帶占位符的SQL插入行 $sql = "INSERT INTO `robots`(`name`, `year`) VALUES (?, ?)"; $success = $connection->execute($sql, array('Astro Boy', 1952)); // 使用類中預設的方法插入行 $success = $connection->insert( "robots", array("Astro Boy", 1952), array("name", "year") ); // 插入數據的另外一種方法 $success = $connection->insertAsDict( "robots", array( "name" => "Astro Boy", "year" => 1952 ) ); // 使用原生SQL更新行 $sql = "UPDATE `robots` SET `name` = 'Astro boy' WHERE `id` = 101"; $success = $connection->execute($sql); // 使用帶占位符的SQL更新行 $sql = "UPDATE `robots` SET `name` = ? WHERE `id` = ?"; $success = $connection->execute($sql, array('Astro Boy', 101)); // 使用類中預設的方法更新行 $success = $connection->update( "robots", array("name"), array("New Astro Boy"), "id = 101" // Warning! In this case values are not escaped ); // 更新數據的另外一種方法 $success = $connection->updateAsDict( "robots", array( "name" => "New Astro Boy" ), "id = 101" // Warning! In this case values are not escaped ); // With escaping conditions $success = $connection->update( "robots", array("name"), array("New Astro Boy"), array( 'conditions' => 'id = ?', 'bind' => array(101), 'bindTypes' => array(PDO::PARAM_INT) // Optional parameter ) ); $success = $connection->updateAsDict( "robots", array( "name" => "New Astro Boy" ), array( 'conditions' => 'id = ?', 'bind' => array(101), 'bindTypes' => array(PDO::PARAM_INT) // Optional parameter ) ); // 使用原生SQL刪除數據 $sql = "DELETE `robots` WHERE `id` = 101"; $success = $connection->execute($sql); // 使用帶占位符的SQL刪除行 $sql = "DELETE `robots` WHERE `id` = ?"; $success = $connection->execute($sql, array(101)); // 使用類中預設的方法刪除行 $success = $connection->delete("robots", "id = ?", array(101)); ``` ``` ### 事務與嵌套事務（Transactions and Nested Transactions） PDO支持事務工作。在事務里面執行數據操作, 在大多數數據庫系統上, 往往可以提高數據庫的性能： ``` <pre class="calibre14">``` <?php try { // 開始一個事務 $connection->begin(); // 執行一些操作 $connection->execute("DELETE `robots` WHERE `id` = 101"); $connection->execute("DELETE `robots` WHERE `id` = 102"); $connection->execute("DELETE `robots` WHERE `id` = 103"); // 提交操作，如果一切正常 $connection->commit(); } catch (Exception $e) { // 如果發現異常，回滾操作 $connection->rollback(); } ``` ``` 除了標準的事務，Phalcon\\Db提供了內置支持`嵌套事務`\_(如果數據庫系統支持的話)。當你第二次調用begin()方法，一個嵌套的事務就被創建了： ``` <pre class="calibre14">``` <?php try { // 開始一個事務 $connection->begin(); // 執行某些SQL操作 $connection->execute("DELETE `robots` WHERE `id` = 101"); try { // 開始一個嵌套事務 $connection->begin(); // 在嵌套事務中執行這些SQL $connection->execute("DELETE `robots` WHERE `id` = 102"); $connection->execute("DELETE `robots` WHERE `id` = 103"); // 創建一個保存的點 $connection->commit(); } catch (Exception $e) { // 發生錯誤，釋放嵌套的事務 $connection->rollback(); } // 繼續，執行更多SQL操作 $connection->execute("DELETE `robots` WHERE `id` = 104"); // 如果一切正常，提交 $connection->commit(); } catch (Exception $e) { // 發生錯誤，回滾操作 $connection->rollback(); } ``` ``` ### 數據庫事件（Database Events） [*Phalcon\\Db*](#) 可以發送事件到一個 [*EventsManager*](#) 中，如果它存在的話。一些事件當返回布爾值false可以停止操作。我們支持下面這些事件：事件名何時觸發可以停止操作嗎?afterConnect當成功連接數據庫之后觸發NobeforeQuery在發送SQL到數據庫前觸發YesafterQuery在發送SQL到數據庫執行后觸發NobeforeDisconnect在關閉一個暫存的數據庫連接前觸發NobeginTransaction事務啟動前觸發NorollbackTransaction事務回滾前觸發NocommitTransaction事務提交前觸發No綁定一個EventsManager給一個連接是很簡單的，Phalcon\\Db將觸發這些類型為“db”的事件： ``` <pre class="calibre14">``` <?php use Phalcon\Events\Manager as EventsManager; use Phalcon\Db\Adapter\Pdo\Mysql as Connection; $eventsManager = new EventsManager(); // 監聽所有數據庫事件 $eventsManager->attach('db', $dbListener); $connection = new Connection( array( "host" => "localhost", "username" => "root", "password" => "secret", "dbname" => "invo" ) ); // 把eventsManager分配給適配器實例 $connection->setEventsManager($eventsManager); ``` ``` 數據庫事件中，停止操作是非常有用的，例如：如果你想要實現一個注入檢查器，在發送SQL到數據庫前觸發： ``` <pre class="calibre14">``` <?php $eventsManager->attach('db:beforeQuery', function ($event, $connection) { // 檢查是否有惡意關鍵詞 if (preg_match('/DROP|ALTER/i', $connection->getSQLStatement())) { // DROP/ALTER 操作是不允許的, 這肯定是一個注入! // 返回false中斷此操作 return false; } // 一切正常 return true; }); ``` ``` ### 分析 SQL 語句（Profiling SQL Statements） [*Phalcon\\Db*](#) 包含了一個性能分析組件，叫 [*Phalcon\\Db\\Profiler*](#) ，它被用于分析數據庫的操作性能以便診斷性能問題，并發現瓶頸。使用 [*Phalcon\\Db\\Profiler*](#) 來分析數據庫真的很簡單: ``` <pre class="calibre14">``` <?php use Phalcon\Events\Manager as EventsManager; use Phalcon\Db\Profiler as DbProfiler; $eventsManager = new EventsManager(); $profiler = new DbProfiler(); // 監聽所有數據庫的事件 $eventsManager->attach('db', function ($event, $connection) use ($profiler) { if ($event->getType() == 'beforeQuery') { // 操作前啟動分析 $profiler->startProfile($connection->getSQLStatement()); } if ($event->getType() == 'afterQuery') { // 操作后停止分析 $profiler->stopProfile(); } }); // 設置事件管理器 $connection->setEventsManager($eventsManager); $sql = "SELECT buyer_name, quantity, product_name " . "FROM buyers " . "LEFT JOIN products ON buyers.pid = products.id"; // 執行SQL $connection->query($sql); // 獲取最后一個分析結果 $profile = $profiler->getLastProfile(); echo "SQL Statement: ", $profile->getSQLStatement(), "\n"; echo "Start Time: ", $profile->getInitialTime(), "\n"; echo "Final Time: ", $profile->getFinalTime(), "\n"; echo "Total Elapsed Time: ", $profile->getTotalElapsedSeconds(), "\n"; ``` ``` 你也可以基于 [*Phalcon\\Db\\Profiler*](#) 建立你自己的分析器類，以記錄SQL語句發送到數據庫的實時統計： ``` <pre class="calibre14">``` <?php use Phalcon\Events\Manager as EventsManager; use Phalcon\Db\Profiler as Profiler; use Phalcon\Db\Profiler\Item as Item; class DbProfiler extends Profiler { /** * 在SQL語句將要發送給數據庫前執行 */ public function beforeStartProfile(Item $profile) { echo $profile->getSQLStatement(); } /** * 在SQL語句已經被發送到數據庫后執行 */ public function afterEndProfile(Item $profile) { echo $profile->getTotalElapsedSeconds(); } } // 創建一個事件管理器 $eventsManager = new EventsManager(); // 創建一個監聽器 $dbProfiler = new DbProfiler(); // 設置監聽器監聽所有的數據庫事件 $eventsManager->attach('db', $dbProfiler); ``` ``` ### 記錄 SQL 語句（Logging SQL Statements）使用例如 [*Phalcon\\Db*](#) 的高級抽象組件操作數據庫，被發送到數據庫中執行的原生SQL語句是難以獲知的。使用 [*Phalcon\\Logger*](#) 和 [*Phalcon\\Db*](#) 來配合使用，可以在數據庫抽象層上提供記錄的功能。 ``` <pre class="calibre14">``` <?php use Phalcon\Logger; use Phalcon\Events\Manager as EventsManager; use Phalcon\Logger\Adapter\File as FileLogger; $eventsManager = new EventsManager(); $logger = new FileLogger("app/logs/db.log"); // 監聽所有數據庫事件 $eventsManager->attach('db', function ($event, $connection) use ($logger) { if ($event->getType() == 'beforeQuery') { $logger->log($connection->getSQLStatement(), Logger::INFO); } }); // 設置事件管理器 $connection->setEventsManager($eventsManager); // 執行一些SQL $connection->insert( "products", array("Hot pepper", 3.50), array("name", "price") ); ``` ``` 如上操作，文件 *app/logs/db.log* 將包含像下面這樣的信息： ``` <pre class="calibre14">``` [Sun, 29 Apr 12 22:35:26 -0500][DEBUG][Resource Id #77] INSERT INTO products (name, price) VALUES ('Hot pepper', 3.50) ``` ``` ### 自定義日志記錄器（Implementing your own Logger）你可以實現你自己的日志類來記錄數據庫的所有操作，通過創建一個實現了”log”方法的類。這個方法需要接受一個字符串作為第一個參數。你可以把日志類的對象傳遞給Phalcon\\Db::setLogger()，這樣執行SQL時將調用這個對象的log方法去記錄。 ### 獲取數據庫表與視圖信息（Describing Tables/Views） [*Phalcon\\Db*](#) 也提供了方法去檢索詳細的表和視圖信息： ``` <pre class="calibre14">``` <?php // 獲取test_db數據庫的所有表 $tables = $connection->listTables("test_db"); // 在數據庫中是否存在'robots'這個表 $exists = $connection->tableExists("robots"); // 獲取'robots'字段名稱，數據類型，特殊特征 $fields = $connection->describeColumns("robots"); foreach ($fields as $field) { echo "Column Type: ", $field["Type"]; } // 獲取'robots'表的所有索引 $indexes = $connection->describeIndexes("robots"); foreach ($indexes as $index) { print_r($index->getColumns()); } // 獲取'robots'表的所有外鍵 $references = $connection->describeReferences("robots"); foreach ($references as $reference) { // 打印引用的列 print_r($reference->getReferencedColumns()); } ``` ``` 一個表的詳細描述信息和MYSQL的describe命令返回的信息非常相似，它包含以下信息：下標描述Field字段名稱Type字段類型Key是否是主鍵或者索引Null是否允許為空對于被支持的數據庫系統，獲取視圖的信息的方法也被實現了： ``` <pre class="calibre14">``` <?php // 獲取test_db數據庫的視圖 $tables = $connection->listViews("test_db"); // 'robots'視圖是否存在數據庫中 $exists = $connection->viewExists("robots"); ``` ``` ### 創建/修改/刪除表不同的數據庫系統（MySQL,Postgresql等）通過了CREATE, ALTER 或 DROP命令提供了用于創建，修改或刪除表的功能。但是不同的數據庫語法不同。[*Phalcon\\Db*](#) 提供了統一的接口來改變表，而不需要區分基于目標存儲系統上的SQL語法。 ### 創建數據庫表（Creating Tables）下面這個例子展示了怎么建立一個表： ``` <pre class="calibre14">``` <?php use \Phalcon\Db\Column as Column; $connection->createTable( "robots", null, array( "columns" => array( new Column( "id", array( "type" => Column::TYPE_INTEGER, "size" => 10, "notNull" => true, "autoIncrement" => true, ) ), new Column( "name", array( "type" => Column::TYPE_VARCHAR, "size" => 70, "notNull" => true, ) ), new Column( "year", array( "type" => Column::TYPE_INTEGER, "size" => 11, "notNull" => true, ) ) ) ) ); ``` ``` Phalcon\\Db::createTable()接受一個描述數據庫表相關的數組。字段被定義成class [*Phalcon\\Db\\Column*](#) 。下表列出了可用于定義字段的選項： Phalcon\\Db 支持下面的數據庫字段類型: - Phalcon\\Db\\Column::TYPE\_INTEGER - Phalcon\\Db\\Column::TYPE\_DATE - Phalcon\\Db\\Column::TYPE\_VARCHAR - Phalcon\\Db\\Column::TYPE\_DECIMAL - Phalcon\\Db\\Column::TYPE\_DATETIME - Phalcon\\Db\\Column::TYPE\_CHAR - Phalcon\\Db\\Column::TYPE\_TEXT 傳入Phalcon\\Db::createTable() 的相關數組可能含有的下標：下標描述是否可選“columns”一個數組包含表的所有字段，字段要定義成 [*Phalcon\\Db\\Column*](#)不“indexes”一個數組包含表的所有索引，索引要定義成 [*Phalcon\\Db\\Index*](#)是“references”一個數組包含表的所有外鍵，外鍵要定義成 [*Phalcon\\Db\\Reference*](#)是“options”一個表包含所有創建的選項. 這些選項常常和數據庫遷移有關.是### 修改數據庫表（Altering Tables）隨著你的應用的增長，作為一個重構的一部分，或者增加新功能，你也許需要修改你的數據庫。因為不是所有的數據庫允許你修改已存在的字段或者添加字段在2個已存在的字段之間。所以 [*Phalcon\\Db*](#)會受到數據庫系統的這些限制。 ``` <pre class="calibre14">``` <?php use Phalcon\Db\Column as Column; // 添加一個新的字段 $connection->addColumn( "robots", null, new Column( "robot_type", array( "type" => Column::TYPE_VARCHAR, "size" => 32, "notNull" => true, "after" => "name" ) ) ); // 修改一個已存在的字段 $connection->modifyColumn( "robots", null, new Column( "name", array( "type" => Column::TYPE_VARCHAR, "size" => 40, "notNull" => true ) ) ); // 刪除名為"name"的字段 $connection->dropColumn( "robots", null, "name" ); ``` ``` ### 刪除數據庫表（Dropping Tables）刪除數據庫表的例子: ``` <pre class="calibre14">``` <?php // 刪除'robots'表 $connection->dropTable("robots"); // 刪除數據庫'machines'中的'robots'表 $connection->dropTable("robots", "machines"); ``` ``` | - [索引](# "總目錄") - [下一頁](# "國際化（Internationalization）") | - [上一頁](# "隊列（Queueing）") |