Yii 2.0 ORM 连接 OceanBase 数据库示例程序

Yii 2.0 是一个高性能的 PHP 框架，提供了强大的 ORM 功能。Yii 2.0 的 ActiveRecord 类为数据库操作提供了优雅的解决方案，支持多种数据库系统，包括与 OceanBase 数据库的兼容。

Yii 2.0 ORM 的主要特点：

• 完整的 ORM 支持，包括模型定义、CRUD 操作和关联关系
• 支持多种数据库系统，包括 MySQL、PostgreSQL、SQLite 等
• 提供查询构建器、事务处理、数据验证等高级功能
• 高性能的缓存机制和延迟加载
• 与 Yii 2.0 框架深度集成

本文将介绍如何使用 Yii 2.0 ORM 连接 OceanBase 数据库，实现基本的数据库操作，包括创建表、插入数据、更新数据和查询数据等。

前提条件

• 您已安装 PHP 7.4 或更高版本。
• 您已安装 Composer 包管理工具。
• 您已安装 OceanBase 数据库并且创建了 MySQL 模式租户。
• 您已获取 OceanBase 数据库连接串。

操作步骤

1. 获取 OceanBase 数据库连接串。
2. 创建 Yii 2.0 项目并安装依赖。
3. 配置数据库连接。
4. 创建模型和数据库迁移。
5. 编写数据库操作代码。
6. 运行程序并验证结果。

步骤一：获取 OceanBase 数据库连接串

联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串。

obclient -h$host -P$port -u$user_name -p$password -D$database_name

参数说明：

• $host：提供 OceanBase 数据库连接 IP。OceanBase 数据库代理（OceanBase Database Proxy，ODP）连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。

• $port：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 2883，在部署 ODP 时可自定义；直连方式默认是 2881，在部署 OceanBase 数据库时可自定义。

• $database_name：需要访问的数据库名称。

  注意

  连接租户的用户需要拥有该数据库的 CREATE、INSERT、UPDATE 和 SELECT 权限。更多有关用户权限的信息，请参见 MySQL 模式下的权限分类。

• $user_name：提供租户的连接账户。ODP 连接的常用格式：用户名@租户名#集群名 或者 集群名:租户名:用户名；直连方式格式：用户名@租户名。

• $password：提供账户密码。

更多连接串的信息，请参见 通过 OBClient 连接 OceanBase 租户。

示例如下：

obclient -hxxx.xxx.xxx.xxx -P2881 -utest_user001@mysql001 -p****** -Dtest

步骤二：创建 Yii 2.0 项目并安装依赖

1. 使用 Composer 创建新的 Yii 2.0 项目：

   # 安装 Yii 2.0 基础应用模板
   composer create-project --prefer-dist yiisoft/yii2-app-basic yii2-oceanbase
   cd yii2-oceanbase
   

2. 安装数据库依赖：

   composer require --prefer-dist yiisoft/yii2-debug
   composer require --prefer-dist yiisoft/yii2-gii
   

3. 验证安装：

   php yii help
   

   如果安装成功，将显示 Yii 的版本信息。

步骤三：配置数据库连接

编辑 config/db.php 文件，配置 OceanBase 数据库连接：

<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=your_oceanbase_host;port=2881;dbname=your_database',
    'username' => 'your_username',
    'password' => 'your_password',
    'charset' => 'utf8mb4',
    'tablePrefix' => 'tbl_',
    'enableSchemaCache' => true,
    'schemaCacheDuration' => 3600,
    'schemaCache' => 'cache',
    'enableQueryCache' => true,
    'queryCacheDuration' => 3600,
    'attributes' => [
        PDO::ATTR_TIMEOUT => 30, // 设置超时时间为30秒
    ],
];

步骤四：创建模型和表结构

1. 创建 User 模型 models/User.php：

   <?php
   
   namespace app\models;
   
   use Yii;
   use yii\db\ActiveRecord;
   use yii\db\Connection;
   use yii\db\Schema;
   
   class User extends ActiveRecord
   {
       public static function tableName()
       {
           return '{{%user}}';
       }
   
       public function rules()
       {
           return [
               [['username', 'email'], 'required'],
               ['email', 'email'],
               ['age', 'integer', 'min' => 0],
               ['username', 'string', 'max' => 100],
               ['email', 'string', 'max' => 100],
               [['created_at'], 'safe'],
           ];
       }
   
       public function beforeSave($insert)
       {
           if (parent::beforeSave($insert)) {
               if ($this->isNewRecord) {
                   $this->created_at = time();
               }
               return true;
           }
           return false;
       }
   

2. 创建用户表：

   CREATE TABLE user (
   id int(11) NOT NULL AUTO_INCREMENT,
   username varchar(100) COLLATE utf8mb4_unicode_ci NOT NULL,
   email varchar(100) COLLATE utf8mb4_unicode_ci NOT NULL,
   age int(11) DEFAULT NULL,
   created_at int(11) NOT NULL,
   PRIMARY KEY (id),
   UNIQUE KEY idx-email (email),
   KEY idx-username (username)
   );
   

步骤五：编写数据库操作代码

1. 创建控制器 controllers/UserController.php：

   <?php
   
   namespace app\controllers;
   
   use Yii;
   use yii\web\Controller;
   use yii\web\Response;
   use app\models\User;
   
   class UserController extends Controller
   {
       public function actionIndex()
       {
   
           // 开始事务
           $transaction = Yii::$app->db->beginTransaction();
   
           try {
               // 1. 插入数据
               $user = new User();
               $user->username = 'oceanbase_user' . time();
               $user->email = 'user' . time() . '******@oceanbase.com';
               $user->age = rand(20, 60);
   
               if (!$user->save()) {
                   throw new \Exception('保存用户失败: ' . json_encode($user->getErrors(), JSON_UNESCAPED_UNICODE));
               }
   
               Yii::info('插入数据成功, ID: ' . $user->id);
   
               // 2. 查询数据
               $foundUser = User::findOne($user->id);
               if (!$foundUser) {
                   throw new \Exception('查询用户失败: 用户不存在');
               }
               Yii::info('查询数据: ' . json_encode($foundUser->attributes, JSON_UNESCAPED_UNICODE));
   
               // 3. 更新数据
               $foundUser->age += 1;
               if (!$foundUser->save()) {
                   throw new \Exception('更新用户失败: ' . json_encode($foundUser->getErrors(), JSON_UNESCAPED_UNICODE));
               }
               Yii::info('更新数据成功');
   
               // 4. 批量插入示例
               $rows = [];
               $columns = ['username', 'email', 'age', 'created_at'];
               $time = time();
   
               for ($i = 0; $i < 5; $i++) {
                   $rows[] = [
                       'user' . $i . '_' . $time,
                       'user' . $i . '_' . $time . '@example.com',
                       rand(20, 60),
                       $time
                   ];
               }
   
               Yii::$app->db->createCommand()->batchInsert(
                   User::tableName(),
                   $columns,
                   $rows
               )->execute();
   
               Yii::info('批量插入5条数据成功');
   
               // 5. 查询所有数据
               $count = User::find()->count();
               Yii::info("当前用户数: $count");
   
               // 6. 分页查询
               $pageSize = 3;
               $users = User::find()
                   ->orderBy(['id' => SORT_DESC])
                   ->limit($pageSize)
                   ->all();
   
               Yii::info('分页查询结果: ' . count($users) . '条');
   
               // 7. 删除数据
               if ($foundUser->delete() === false) {
                   throw new \Exception('删除用户失败');
               }
               Yii::info('删除数据成功');
   
               $transaction->commit();
   
               return $this->asJson([
                   'success' => true,
                   'message' => '操作成功',
                   'data' => [
                       'userCount' => $count,
                       'sampleUser' => $foundUser->attributes
                   ]
               ]);
   
           } catch (\Exception $e) {
               $transaction->rollBack();
               Yii::error($e->getMessage());
               return $this->asJson([
                   'success' => false,
                   'message' => '操作失败: ' . $e->getMessage(),
               ]);
           }
       }
   }
   

步骤六：运行程序并验证结果

1. 启动 Yii 内置开发服务器：

   php yii serve
   

2. 在浏览器中访问 curl http://localhost:8080/index.php?r=user/index 或使用 curl 测试：

   curl http://localhost:8080/index.php?r=user/index
   

3. 查看 runtime/logs/app.log 文件，您应该能看到类似以下的日志输出：

   2025-06-10 11:30:15 [info][application] 开始处理用户数据...
   2025-06-10 11:30:16 [info][application] 创建用户表 user 成功
   2025-06-10 11:30:16 [info][application] 插入数据成功, ID: 1
   2025-06-10 11:30:16 [info][application] 查询数据: {"id":1,"username":"oceanbase_user1654857016","email":"******@oceanbase.com","age":35,"created_at":1654857016}
   2025-06-10 11:30:16 [info][application] 更新数据成功
   2025-06-10 11:30:16 [info][application] 批量插入5条数据成功
   2025-06-10 11:30:16 [info][application] 当前用户数: 6
   2025-06-10 11:30:16 [info][application] 分页查询结果: 3条
   2025-06-10 11:30:16 [info][application] 删除数据成功
   

4. 响应结果示例：

   {
       "success":true,"message":"操作成功","data":{"userCount":6,"sampleUser":{"id":1,"username":"oceanbase_user1749628918","email":"******@oceanbase.com","age":31,"created_at":1749628919}}
   }
   

相关文档

• Yii 2.0 官方文档
• Yii 2.0 数据库访问对象
• OceanBase 数据库文档
• PHP 官方文档