Skip to content
Quiote

UUID and binary columns

Propulsion has a first-class UUID column type — declare a column with type="UUID" and get validated, normalized UUID storage with no further setup. What Propulsion does not have is Propel 2’s UUID_BINARY type, which stores a UUID as 16 raw bytes (BINARY(16) on MySQL/MSSQL, RAW(16) on Oracle, BYTEA on PostgreSQL, BLOB on SQLite) instead of as text. If you only need a UUID column, skip to The UUID type below; if you specifically need binary storage, see Binary storage instead.

The UUID type

Section titled “The UUID type”
<table name="my_table">
  <column name="uuid" type="UUID" required="true" />
</table>
<?php
$myTableObject->setUuid('8DDB2EC4-F996-4777-B4F4-D59399530734');
echo $myTableObject->getUuid(); // '8ddb2ec4-f996-4777-b4f4-d59399530734'


// Malformed input throws rather than storing garbage
$myTableObject->setUuid('not-a-uuid'); // throws PropulsionException

The generated setter validates the canonical 8-4-4-4-12 hyphenated hexadecimal format and normalizes it to lowercase. On PostgreSQL, UUID maps to the native uuid column type; everywhere else (MySQL, SQLite, Oracle, MSSQL) it falls back to CHAR(36). Filtering (filterByXXX()), hydration, and TableMap metadata all work with no further schema configuration, since a UUID column is a text type as far as that machinery is concerned (Column::isTextType()). See Column types and Active Record reference.

This covers the same ground as Propel 2’s UUID type (native-where-possible storage with a string-shaped PHP API), just without Propel 2’s automatic fallback to binary storage on databases lacking a native uuid type — Propulsion always falls back to text (CHAR(36)), never binary, for portability and simplicity. If you need binary storage specifically, see below.

Binary storage instead of UUID_BINARY

Section titled “Binary storage instead of UUID_BINARY”

UUID_BINARY does not exist in Propulsion. This isn’t an oversight this page is working around — it’s a straightforward fact you can verify yourself: Propulsion\Generator\Model\PropulsionTypes (generator/Lib/Model/PropulsionTypes.php) has no UUID_BINARY constant, and neither does the schema XSD’s column-type enumeration (generator/resources/xsd/database.xsd). There is also no UuidConverter class, no uuidColumnType adapter setting, and no UuidSwapFlag vendor parameter anywhere in the codebase. If your Propel 2 schema declares a UUID_BINARY column, bin/propulsion model:build will reject it as an invalid column type — this isn’t a “still works, just undocumented” situation.

If you specifically need 16-byte binary storage (matching what Propel 2’s UUID_BINARY produced), declare a BINARY/VARBINARY column and do the string↔binary conversion in your own code, e.g. with ramsey/uuid:

<table name="my_table">
  <column name="uuid_bin" type="BINARY" size="16" required="true" />
</table>
use Ramsey\Uuid\Uuid;


$myTableObject->setUuidBin(Uuid::fromString('8ddb2ec4-f996-4777-b4f4-d59399530734')->getBytes());
echo Uuid::fromBytes($myTableObject->getUuidBin())->toString();

There’s no Propulsion-provided UuidConverter::uuidToBin()/binToUuid() equivalent, no built-in swap-flag handling for the byte-reordering trick MySQL/MariaDB’s UUID_TO_BIN(..., 1) performs (see the original Propel 2 rationale if you’re porting logic that relied on it), and no automatic conversion in filterByXXX() filter methods — you convert both directions by hand, everywhere a value crosses the PHP/database boundary. This is materially more work than Propel 2’s UUID_BINARY type, but it’s the closest equivalent for binary-format UUID storage.

If PostgreSQL-only native storage efficiency is all you’re after (and you don’t need raw 16-byte binary specifically), prefer the built-in UUID type above — it already maps to PostgreSQL’s native uuid column type without any of this by-hand conversion.

Migrating an existing Propel 2 schema

Section titled “Migrating an existing Propel 2 schema”

If you’re porting a Propel 2 schema to Propulsion:

  1. Plain UUID columns: change the column’s type to Propulsion’s UUID and drop any Propel-2-specific adapter configuration — no other changes needed.
  2. UUID_BINARY columns: decide whether you need the 16-byte binary format specifically, or whether a UUID column (falling back to text where there’s no native type) is an acceptable substitute. Binary format needs the manual BINARY/VARBINARY approach above.
  3. If existing data is already stored as MySQL/MariaDB binary UUIDs (via UUID_TO_BIN()) and you’re moving it to the UUID type, write your own one-off migration to convert it to the canonical hyphenated text form — Propulsion generates no automatic UUID_BINARY→UUID migration path.
  4. Regenerate your models (bin/propulsion model:build) and update any code that called Propel 2’s UuidConverter or relied on filterByXXX() accepting a UUID string on what’s now a plain binary column.
Section titled “Related”