Download the PHP package darkspock/just-query without Composer

JustQuery

A high-performance PHP Query Builder built for production SaaS applications where query control, observability, and deploy safety matter.

Full MySQL and PostgreSQL support. Zero framework coupling. Drop into any PHP 8.3+ project.

Benchmarks

Compared against Eloquent 12.x and Doctrine DBAL 4.x (PHP 8.5, MySQL 8.0, 50k+ rows). Ties Doctrine on reads, 26x faster on batch inserts, and matches Eloquent's code brevity — without the ORM overhead. Full comparison.

Requirements

• PHP >= 8.3
• PDO + pdo_mysql and/or pdo_pgsql

Installation

Connection

MySQL

PostgreSQL

Shared PDO (existing connection)

Advanced Configuration

Connection Lifecycle

Table Prefix

Framework Integration

Laravel

Register JustQuery as a singleton in a Service Provider. This reuses Laravel's existing PDO connection:

Usage anywhere via dependency injection or the container:

Symfony

Register JustQuery as a service in services.yaml:

Or reuse Doctrine's existing PDO connection:

Usage via autowiring:

Quick Start

Factory Methods

Query Builder

WHERE Conditions

Every standard SQL comparison, plus array/JSON operators:

Full list of condition operators: =, !=, <>, >, >=, <, <=, BETWEEN, NOT BETWEEN, IN, NOT IN, LIKE, NOT LIKE, OR LIKE, OR NOT LIKE, EXISTS, NOT EXISTS, ARRAY OVERLAPS, JSON OVERLAPS, JSON CONTAINS, JSON LENGTH, AND, OR, NOT.

Raw Integer IN (High Performance)

For large IN lists with integer IDs, whereIntegerInRaw() skips PDO parameter binding entirely. A normal ['in', 'id', $ids] with 10,000 IDs creates 10,000 :qp0, :qp1, ... placeholders and 10,000 PDOStatement::bindValue() calls. The raw version inlines the integers directly, sanitized with intval():

Safety: all values are cast through intval(), so non-integer values become 0. Empty arrays produce WHERE 0=1 (IN) or are a no-op (NOT IN).

When to use: large lists of IDs from subqueries, caches, or external systems where binding overhead is measurable. For small lists (under ~100 values), normal ['in', 'id', $values] is fine.

Conditional Clauses (when)

Apply query clauses only when a condition is truthy. Eliminates verbose if/else blocks:

The second closure (optional) is the default, called when the condition is falsy.

Incremental WHERE Building

where() sets the initial condition (throws LogicException if called twice). Use andWhere() / orWhere() to add conditions incrementally:

Smart Filter Comparison

andFilterCompare() detects the operator from the value string:

Recognized prefixes: >=, <=, <>, >, <, =. Default operator is =.

SELECT Options

JOINs

GROUP BY and HAVING

ORDER BY

Aggregates

Result Methods

Index Results By Column

Result Callback

Transform result rows before they are returned:

FOR UPDATE / FOR SHARE

Lock rows for update within a transaction:

Emulate Execution

Skip actual DB execution (useful for conditional query building):

Subqueries

Any Query object is embeddable as a subquery anywhere:

Common Table Expressions (CTE)

UNION

Batch Processing

Chunk By ID (Safe Iteration)

Unlike batch() which uses OFFSET/LIMIT, chunkById() uses cursor-based pagination (WHERE id > last_id). This is safe when modifying records during iteration and faster on large tables:

Upsert

Increment / Decrement

Atomic counter operations without writing Expression objects manually:

Batch Insert

Parameter Binding

Raw SQL and Direct Command Queries

Transactions

Retry Handler

Handle transient database errors (deadlocks, connection drops) with automatic retry:

Index Hints (MySQL)

Control which indexes MySQL uses for query execution. Essential for large tables where the optimizer makes suboptimal choices.

Generated SQL:

Expression System

Build complex SQL safely using the Expression/Builder pattern. Every expression class has a corresponding Builder that generates the SQL.

Raw Expression

CASE Expression

Function Expressions

Value Expressions

Composite Expressions

Schema Provider

Configure how the query builder understands your database schema:

Why JSON Schema?

In rolling deployments:

1. Database migration runs (adds column score FLOAT GENERATED ALWAYS AS (...))
2. Old code is still running — it doesn't know about score
3. New code deploys — it reads score from JSON schema, knows it's computed, skips it in writes

With DB introspection (upstream approach), step 2 can fail if the cache is stale or cold. With JSON schema, the schema definition travels with the code.

JSON Schema Format

The type defines the PHP type you want, not the MySQL column type. A TEXT column storing "42" with "type": "integer" returns 42 in PHP.

Supported types: string, integer, float, boolean, json.

Automatic Type Casting

PDO returns everything as strings. JustQuery casts automatically based on schema:

Granular Type Casting Control

Computed Column Protection

Columns marked as computed or autoIncrement are automatically excluded from INSERT and UPDATE:

Query Profiler

Zero-overhead when disabled. Nanosecond-precision timing when active.

Each query record contains:

When no profiler is set, there is zero overhead — all profiler calls are nullsafe no-ops.

PostgreSQL Support

Full PostgreSQL support with native types:

RETURNING Clause

Array Types

Structured/Composite Types

Range Types

Full support for all PostgreSQL range types:

Supported: int4range, int8range, numrange, daterange, tsrange, tstzrange, and all corresponding multirange types.

Array Merge

Index Methods

DDL Operations

Full DDL support for both MySQL and PostgreSQL. All DDL methods are available on both the QueryBuilder and Command interfaces:

Tables

Columns

Indexes

Foreign Keys

Constraints

Comments

Views

Sequences and Integrity

Testing

Project Status

Roadmap

• Query plan analysis — EXPLAIN integration with automatic slow-query detection
• Connection-level metrics — connection pool stats, reconnection tracking
• Read/write splitting — automatic routing to read replicas
• Query result caching — PSR-16 cache layer with tag-based invalidation
• MySQL 8.0+ optimizer hints — /*+ ... */ comment-style hints beyond index hints
• Prepared statement caching — reuse server-side prepared statements across queries

Why a Fork?

JustQuery is a fork of yiisoft/db v2.0.1 and yiisoft/db-mysql. We forked because we needed features that don't fit upstream's scope: MySQL index hints (FORCE INDEX, USE INDEX, IGNORE INDEX), JSON-based schema for rolling deployments, a built-in query profiler, computed column protection, and shared PDO connections. See the full comparison for details.

License

BSD-3-Clause. See LICENSE.md.

We are deeply grateful to the Yii framework team and community for building and open-sourcing an exceptionally well-designed database abstraction layer. The query builder architecture, the Expression/Builder pattern, the condition system, and the overall code quality of yiisoft/db are outstanding work that made this project possible.

Special thanks to:

• Qiang Xue (@qiangxue) — creator of Yii Framework
• Alexander Makarov (@samdark) — long-time Yii core maintainer
• Sergei Tigrov (@Tigrov) and Sergei Predvoditelev (@vjik) — primary maintainers of yiisoft/db who wrote the vast majority of the v2.0 codebase

The Yii project has been a cornerstone of the PHP ecosystem since 2008. If you are looking for a full-featured PHP framework, check out yiiframework.com.

Original licenses preserved in LICENSE-mysql.md.