bitrix-postgresql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostgreSQL in Bitrix

Bitrix中的PostgreSQL

Baseline: main 23.0+. Supported in Enterprise for PostgreSQL licenses (B24 and CMS). Connection class:

\Bitrix\Main\DB\PgsqlConnection

基准版本：main 23.0+。仅在PostgreSQL企业版许可证（B24和CMS）中支持。连接类：

\Bitrix\Main\DB\PgsqlConnection

。

Configuration

配置

php

'connections' => [
    'value' => [
        'default' => [
            'className' => \Bitrix\Main\DB\PgsqlConnection::class,
            'host' => 'localhost',
            'database' => 'bx',
            'login' => 'bx',
            'password' => '***',
            'options' => \Bitrix\Main\DB\Connection::DEFERRED,
        ],
    ],
    'readonly' => true,
],

php

'connections' => [
    'value' => [
        'default' => [
            'className' => \Bitrix\Main\DB\PgsqlConnection::class,
            'host' => 'localhost',
            'database' => 'bx',
            'login' => 'bx',
            'password' => '***',
            'options' => \Bitrix\Main\DB\Connection::DEFERRED,
        ],
    ],
    'readonly' => true,
],

Before Migration

迁移前准备

Check that the current license stays valid through the whole test period (up to 6 months) and the final switch — renew it first if it expires earlier.
Obtain Enterprise for PostgreSQL license. It provides a coupon (activate it only after migration testing) and a test key for a separate test install; testing window is max 6 months from purchase. During testing the production site keeps running on MySQL under the current license — the test key is for the test environment only.
Update Performance Monitor module to 24.0.0+.
Project must use UTF-8 encoding.
Close site to visitors during migration.
Test on staging first — return to MySQL after production PostgreSQL launch requires manual work.

确保当前许可证在整个测试周期（最长6个月）及最终切换期间保持有效——若许可证到期时间更早，请先续费。
获取PostgreSQL企业版许可证。该许可证包含一张优惠券（仅在迁移测试完成后激活）和用于独立测试环境的测试密钥；测试窗口期为购买后最长6个月。测试期间，生产站点可在当前许可证下继续运行MySQL，测试密钥仅用于测试环境。
将性能监控模块更新至24.0.0+版本。
项目必须使用UTF-8编码。
迁移期间关闭站点对访客的访问权限。
先在预发布环境测试——生产环境切换至PostgreSQL后再换回MySQL需要手动操作。

Module Compatibility

模块兼容性

Not all kernel and marketplace modules support PostgreSQL. Incompatible modules are disabled during conversion wizard.

Check custom code:

MySQL-specific SQL (
```
LIMIT
```
syntax differences handled by SqlHelper, but raw SQL may break).
MySQL install scripts under
```
install/mysql/
```
or
```
install/db/mysql/
```
need matching PostgreSQL scripts under
```
install/pgsql/
```
or
```
install/db/pgsql/
```
.

Find modules missing pgsql install:

bash

for mysql in bitrix/modules/*/install/mysql/install.sql bitrix/modules/*/install/db/mysql/install.sql; do
  pgsql=$(echo $mysql | sed 's#/mysql/#/pgsql/#')
  test -e $pgsql || echo "missing: $pgsql"
done

Check kernel module install folders: each supporting module should have matching

install/pgsql/

install/db/pgsql/

scripts. Inspect

bitrix/modules/<module>/install/

in the project.

并非所有内核模块和市场模块都支持PostgreSQL。不兼容的模块会在转换向导中被禁用。

检查自定义代码：

避免MySQL专属SQL语法（
```
LIMIT
```
的语法差异可由SqlHelper处理，但原生SQL可能失效）。
若存在
```
install/mysql/
```
或
```
install/db/mysql/
```
下的MySQL安装脚本，需在
```
install/pgsql/
```
或
```
install/db/pgsql/
```
下添加对应的PostgreSQL脚本。

查找缺少pgsql安装脚本的模块：

bash

for mysql in bitrix/modules/*/install/mysql/install.sql bitrix/modules/*/install/db/mysql/install.sql; do
  pgsql=$(echo $mysql | sed 's#/mysql/#/pgsql/#')
  test -e $pgsql || echo "missing: $pgsql"
done

检查内核模块安装目录：每个支持PostgreSQL的模块都应配有

install/pgsql/

或

install/db/pgsql/

脚本。请查看项目中的

bitrix/modules/<module>/install/

目录。

Migration Methods

迁移方法

Wizard — Admin conversion tool (lists disabled modules on step 1).
CLI — manual server-side migration via Performance Monitor module tools.

向导——后台转换工具（第一步会列出被禁用的模块）。
CLI——通过性能监控模块工具手动在服务器端执行迁移。

Writing Compatible Code

编写兼容代码

Use ORM and
```
SqlHelper
```
— avoid MySQL-specific functions in raw SQL.
Use
```
SqlExpression
```
placeholders instead of string concatenation.
Test DDL in both MySQL (
```
install/mysql/
```
or
```
install/db/mysql/
```
) and PostgreSQL (
```
install/pgsql/
```
or
```
install/db/pgsql/
```
) if the module supports both.
Avoid
```
ENGINE=InnoDB
```
, backticks-specific syntax,
```
UNSIGNED
```
.

使用ORM和
```
SqlHelper
```
——避免在原生SQL中使用MySQL专属函数。
使用
```
SqlExpression
```
占位符替代字符串拼接。
若模块同时支持两种数据库，需在MySQL（
```
install/mysql/
```
或
```
install/db/mysql/
```
）和PostgreSQL（
```
install/pgsql/
```
或
```
install/db/pgsql/
```
）环境中测试DDL语句。
避免使用
```
ENGINE=InnoDB
```
、反引号专属语法、
```
UNSIGNED
```
。