README

此插件允许使用 MySQL/MariaDB/PostgreSQL 数据库，而不是默认的 MongoDB/SQLite。

要求

• Cockpit CMS (next, 测试到 v0.11.0 或旧版)
• MySQL 5.7.9/MariaDB 10.2.6/PostgreSQL 9.4
• PHP 7.1
• 启用的 PHP 扩展：pdo，pdo_mysql/pdo_pgsql

兼容性

要运行 Cockpit 0.9.2+，至少需要版本 1.0.0-beta.2+。

安装

注意

如果您在启动 Cockpit 之前安装了插件，一旦启动它，可能会出现一些错误。

要解决这个问题，请使用它支持的数据库配置启动 Cockpit 默认配置 以触发 Cockpit warmup，然后设置针对此插件的特定配置。

手册

下载 最新版本 并解压缩到 COCKPIT_PATH/addons/SqlDriver 目录

使用 Cockpit CLI （开发版本）

./cp install/addon --name SqlDriver --url https://github.com/piotr-cz/cockpit-sql-driver/archive/master.zip

使用 Composer

1. 确保在项目的 composer.json 文件中定义了 cockpit 插件的路径

   {
       "name": "MY_PROJECT",
       "extra": {
           "installer-paths": {
               "public/cockpit/addons/{$name}": ["type:cockpit-module"]
           }
       }
   }

2. 在项目根目录下运行命令

   composer require piotr-cz/cockpit-sql-driver

配置

为 COCKPIT_PATH/config/config.php 文件提供的示例配置

<?php
return [
    # Cockpit configuration
    # …

    # Use SQL Driver as main data storage
    'database' => [
        'server' => 'sqldriver',
        # Connection options
        'options' => [
            'connection' => 'mysql',         # One of 'mysql'|'pgsql'
            'host'       => 'localhost',     # Optional, defaults to 'localhost'
            'port'       => 3306,            # Optional, defaults to 3306 (MySQL) or 5432 (PostgreSQL)
            'dbname'     => 'DATABASE_NAME',
            'username'   => 'USER',
            'password'   => 'PASSWORD',
            'charset'    => 'UTF8',          # Optional, defaults to 'UTF8'
            'tablePrefix' => '',             # Optional, database tables prefix (ie. 'cockpit_')
            'bootstrapPriority' => 999,      # Optional, defaults to 999
        ],
        # Connection specific options
        # General: https://php.ac.cn/manual/en/pdo.setattribute.php
        # MySQL specific: https://php.ac.cn/manual/en/ref.pdo-mysql.php#pdo-mysql.constants
        'driverOptions' => [],
    ],
];

参考：Cockpit 文档 > 配置

数据库内容迁移（Cockpit v0.6.0+）

1. 将数据导出到 COCKPIT_PATH/migration 子目录

   mkdir migration
   ./cp export --target migration

2. 将数据库切换到 sqldriver（见 配置）

3. 从 COCKPIT_PATH/migration 子目录导入数据

   ./cp import --src migration
   rm -rf migration

参考：Cockpit 文档 > CLI

测试

该软件包中包含集成测试。这些测试需要 Cockpit CMS 作为开发依赖项，并使用其 MongoHybrid\Client API 在数据库上运行操作。

要运行测试

1. 安装依赖项

   cd COCKPIT_PATH/addons/SqlDriver
   composer install

2. 配置测试数据库

   将 /phpunit.xml.dist 复制到 /phpunit.xml 并根据配置设置变量

3. 使用 PHPUnit 运行测试

   ./vendor/bin/phpunit

缺点

Cockpit 不提供公共 API 来注册自定义数据库驱动程序，因此此插件会对 Cockpit 驱动程序选择器客户端（MongoHybrid Client）进行 monkey-patch。这意味着无法保证此插件将在 Cockpit 的未来版本中工作。

集合过滤器

未实现

• $func/ $fn/ $f

• $fuzzy

工作方式不同

• 可调用

  与 SQLite 不同，PDO MySQL 和 PostgreSQL 驱动程序不支持 PHP 语言中的用户定义函数 - 因此可调用在每个结果检索时都会被评估。如果您在集合中有大量文档并且关心性能，请使用其他过滤器。

• $in，$nin

  当数据库值是数组时，评估为 false。

• $regexp

  • MySQL 通过 REGEXP + 不区分大小写实现
  • PostgreSQL通过POSIX正则表达式 + 不区分大小写实现。

  将表达式包裹在//中或添加如/foobar/i的标志不起作用，因为MySQL和PostgreSQL的正则表达式函数不支持标志。

• $text

  • MySQL通过LIKE实现。
  • PostgreSQL通过LIKE实现。

  不支持过滤选项（$minScore，$distance，$search）。

手动数据库优化

默认情况下，包为每个创建的集合创建具有唯一索引的虚拟列_id。

如果您想加快其他集合字段的过滤速度，请添加具有合适索引和类型的虚拟列。

例如，要为TABLE_NAME集合中的FIELD_NAME字段添加整数类型的虚拟列，使用以下命令：

• MySQL

  ALTER TABLE
      `{TABLE_NAME}` ADD COLUMN `{FIELD_NAME}_virtual` INT AS (`document` ->> '$.{FIELD_NAME}') NOT NULL,
      ADD UNIQUE | KEY `idx_{TABLE_NAME}_{FIELD_NAME}` (`{FIELD_NAME}_virtual`);

  参考：MySQL 5.7 > CREATE INDEX

• PostgreSQL

  CREATE [UNIQUE] INDEX "idx_{TABLE_NAME}_{FIELD_NAME}" ON "{FIELD_NAME}" ((("document" ->> '{FIELD_NAME}')::int));

  参考：PostgreSQL 9.4 > CREATE INDEX

已知问题

错误：Call to a member function toArray() on null

这发生在第一次启动cockpit并安装此插件时。原因是原生Cockpit模块尝试访问稍后初始化的存储（在自定义模块引导过程中）。

Cockpit必须在没有配置为使用SQL驱动程序的情况下首次启动。

解决方案1 使用Cockpit支持的自带数据库配置启动，然后按以下说明此处切换到sqldriver

解决方案2 手动创建文件COCKPIT_STORAGE_FOLDER/tmp/webhooks.cache.php，并包含以下内容：

<?php return [];

版权和许可

版权自2019年Piotr Konieczny起，根据MIT许可证。