RUEN
Package · cdo

CDO API

CDO extends PDO, adding the DML methods below. Everything else — query, prepare, fetch*, transactions, attributes — is inherited from PDO unchanged. Every method here throws CDOException on failure, wrapping the original PDOException.

Identifiers are quoted; values are bound

Values are bound as prepared-statement parameters. Table and column names — which cannot be bound — are quoted with the driver’s quoting characters ("…" for PostgreSQL/Oracle, `…` for MySQL/MariaDB), so these DML methods are safe even with dynamically built names. Because quoted identifiers are case-sensitive in PostgreSQL, pass names exactly as they exist in the schema (users, not Users). Note this quoting applies to the CDO methods only — column names passed to Qb are not quoted.

Construction

You rarely construct CDO directly — ConnectionPool does it for you. The constructor is:

php
public function __construct(
  DbConfigInterface $config,
  int $timeout = 5,
  bool $debug = false
)
Parameter Type Default Description
config DbConfigInterface — Connection config (credentials, driver, logger)
timeout int 5 Connection timeout in seconds (PDO::ATTR_TIMEOUT)
debug bool false When true, sets PDO::ERRMODE_EXCEPTION

getDriverName

php
public function getDriverName(): string

Returns the normalised driver: 'pgsql', 'mysql', 'mariadb', or 'oci'. Unlike PDO::ATTR_DRIVER_NAME, this distinguishes MariaDB from MySQL — see Driver detection.

insert

php
final public function insert(string $table, object|array $entity): mixed

Inserts one row and returns the generated primary key.

Parameter Type Description
table string Table name
entity `object\ array`
  • Returns the primary key — the value of the entity’s first key, read via RETURNING (PostgreSQL/MariaDB) or lastInsertId() (MySQL). Returns null when there is no generated id to report.
  • null values in entity are excluded from the INSERT.
  • Throws CDOException on query failure.

insertGroup

php
final public function insertGroup(
  string $table,
  array $entities,
  int $chunkSize = 1000
): void

Batch-inserts many rows as chunked multi-row INSERTs.

Parameter Type Default Description
table string — Table name
entities array — Array of arrays/objects
chunkSize int 1000 Rows per INSERT statement
  • Returns nothing. An empty entities array is a no-op.
  • Per-row null values are excluded. Throws CDOException on failure.

upsert

php
final public function upsert(
  string $table,
  object|array $entity,
  array $conflictColumns,
  ?array $updateColumns = null
): mixed

Inserts a row, or updates/ignores it on unique conflict.

Parameter Type Default Description
table string — Table name
entity `object\ array` —
conflictColumns array — Column(s) defining uniqueness
updateColumns `array\ null` null
  • Returns the primary key on PostgreSQL (via RETURNING); on MySQL/MariaDB returns lastInsertId() (null if no new row was inserted).
  • Throws CDOException if conflictColumns is empty, or on query failure.
  • Expression tokens :new / :current — see Upsert placeholders.

upsertGroup

php
final public function upsertGroup(
  string $table,
  array $entities,
  array $conflictColumns,
  ?array $updateColumns = null,
  int $chunkSize = 500
): void

Batch upsert with chunking.

Parameter Type Default Description
table string — Table name
entities array — Array of arrays/objects
conflictColumns array — Column(s) defining uniqueness
updateColumns `array\ null` null
chunkSize int 500 Rows per statement
  • Returns nothing. Empty entities ⇒ no-op; empty conflictColumns ⇒ throws.

update

php
final public function update(string $table, object|array $entity, Qb $qb): int

Updates rows matching a Qb condition.

Parameter Type Description
table string Table name
entity `object\ array`
qb Qb Condition for the WHERE clause
  • Returns the number of affected rows (rowCount()).
  • Throws CDOException on failure.

delete

php
final public function delete(string $table, Qb $qb): int

Deletes rows matching a Qb condition.

Parameter Type Description
table string Table name
qb Qb Condition for the WHERE clause
  • Returns the number of deleted rows. Throws CDOException on failure.

applyDatabaseTimezone

php
public function applyDatabaseTimezone(mixed $driver, string $tz): void

Sets the session timezone to match PHP’s. Called automatically at connect time; exposed as public so you can re-apply it after a driver-level reset. Behaviour per driver is documented in Driver detection.

Writes only; reads stay PDO

There is intentionally no select / find here. Read with the inherited PDO methods and a Qb fragment for the WHERE.