README

这是一个具有高级SQL语言功能的驱动无关SQL查询构建器。

默认情况下，它生成（几乎）符合SQL标准的查询，几乎是因为我们支持的所有SQL方言中都没有实现某些SQL功能，在这种情况下，我们实现了自定义变体。

它基于流畅的API，这使得基本的SELECT、DELETE、INSERT、UPDATE和MERGE查询易于编写，即使你并不真正了解SQL。

在任何地方，用户都可以注入原始SQL以避免查询构建器本身的限制。

这个API本身只是一个SQL字符串生成器，为了透明地使用它，提供了一些桥梁

• doctrine/dbal:^3桥接器和查询构建器，
• 很快就会有doctrine/dbal:^4桥接器和查询构建器，
• PDO桥接器和查询构建器，
• Symfony扩展集成了doctrine/doctrine-bundle，可在makinacorpus/query-builder-bundle包中获取。

入门指南

阅读read the docs上的文档。

概览 支持的SQL功能列表。

查看官方支持的供应商方言。

非详尽的特性列表

• 公共表表达式:
  • WITH "foo" AS (SELECT ...)
• VALUES / 常量表表达式:
  • WITH "foo" ("col1", "col2") AS (SELECT VALUES ...)
  • SELECT VALUES ... AS ("col1", "col2")
  • JOIN (VALUES ...) AS "foo", ...
• 聚合函数过滤器:
  • 标准SQL: SELECT SUM(foo) FILTER (WHERE <condition>)
  • 不支持RDBMS的模拟: SELECT SUM(CASE WHEN <condition> THEN foo END)
• 窗口函数:
  • SELECT SUM(foo) OVER (PARTITION BY... ORDER BY...)
  • SELECT SUM(foo) OVER (bar) FROM baz WINDOW bar AS (PARTITION BY... ORDER BY...)
• RETURNING/OUTPUT:
  • PostgreSQL: UPDATE foo SET ... RETURNING foo, bar, baz
  • SQL Server: UPDATE foo SET ... OUTPUT DELETED.col1, INSERTED.col1
• 复杂的WHERE条件构建器
• CASE WHEN ... THEN ... END
• IF THEN 使用CASE ... WHEN模拟
• 数组表达式:
  • ARRAY[? ,? ?]
• 行表达式:
  • 标准SQL: ROW('foo', 2, ...)
  • PostgreSQL复合类型: ROW('foo', 2, ...)::some_composite_type
• 混合复杂的数据结构:
  • CAST(ROW('foo', CAST(ARRAY[1,2,3] AS bigint[])) AS some_composite_type)
• CAST表达式:
  • 标准SQL: CAST(expression AS type)
  • PostgreSQL: expression::type
• LIKE / SIMILAR TO
  • foo LIKE '%somevalue%'
  • foo SIMILAR TO '%somevalue%'
• 更新FROM JOIN
• INSERT INTO ... VALUES ...
• INSERT INTO ... SELECT ...
• 用户在所有地方都可以使用任意原始SQL
  • 构建器不支持某些X或Y高级功能或特定方言，那么就编写自己的SQL。
• 在每个地方标识符的转义
• 用户值转换为SQL

构建文档

文档使用VitePress编写。

为读者

cd ./docs/
nvm use
npm ci
npm run docs:build
<your browser> ./.vitepress/dist/index.html

为开发者

cd ./docs/
nvm use
npm ci
npm run docs:dev

运行测试

大多数单元测试可以通过直接运行PHPUnit顺利运行

composer install
vendor/bin/phpunit

为了运行桥梁集成测试，需要一个包含一些正在运行的数据库的完整环境，为此提供了一个使用 docker compose 的脚本，但在所有环境中可能无法优雅地工作。

composer install
./run-tests.sh

请理解，测试环境目前处于原型阶段，并且将保持原样，直到配置好github actions CI。

历史

此API几乎是一个全新的重写，保留了基本设计，使用了现代PHP >= 8.2功能，并对来自 makinacorpus/goat-query 包的查询构建器进行了更多单元测试。

其原因是我们在过去几年中深度使用 makinacorpus/goat-query 作为我们主要的数据库访问层，但现在我们正转向使用更常用的工具来支持未来的项目。

Doctrine DBAL查询构建器可以做你想要做的任何事情，但它的API不直观，使用它的代码难以阅读。此外，它没有实现现代SQL语言功能，因为它的目标主要是为大量RDBMS提供最低的共同基数。