[PR #12148] [MERGED] docs: generation strategies: differences between DBAL 3 and 4 #13521

New Issue

admin · 2026-01-22T16:17:22+01:00

admin commented

2026-01-22 16:17:22 +01:00

📋 Pull Request Information

Original PR: https://github.com/doctrine/orm/pull/12148
Author: @lucasmirloup
Created: 8/26/2025
Status: ✅ Merged
Merged: 8/27/2025
Merged by: @greg0ire

Base: 3.5.x ← Head: docs/generation-strategies-dbal-4

📝 Commits (2)

c164ae4 docs: generation strategies differences between DBAL 3 and 4
f7d4e37 docs: consistent PostgreSQL's name case

📊 Changes

2 files changed (+9 additions, -7 deletions)

View changed files

📝 docs/en/reference/basic-mapping.rst (+7 -5)
📝 docs/en/tutorials/getting-started.rst (+2 -2)

📄 Description

Hello,
I'm currently updating Doctrine DBAL from version 3 to 4 on an app that uses Doctrine generated ID columns (with no strategy defined, thus using AUTO if I'm not mistaken) with PostgreSQL 17.

I suspect that the generation strategies' documentation for PostgreSQL is outdated or inaccurate, due to changes introduced in / for Doctrine DBAL 4.

Here's a more detailed report / explanation:

I initially encountered database errors about PostgreSQL's SEQUENCE, and tried tinkering with the strategy, to no avail.
I then stumbled upon the following documentation: https://github.com/doctrine/dbal/blob/4.3.x/docs/en/how-to/postgresql-identity-migration.rst

Still, something about the generation strategies' documentation confused me: the documentation claims that no matter Doctrine DBAL's version, the default (AUTO) strategy on PostgreSQL is SEQUENCE.

When tested on my app, either of these 2 lines produce the same database migrations:

#[ORM\GeneratedValue(strategy: 'IDENTITY')]
#[ORM\GeneratedValue]

ALTER TABLE my_table ALTER id DROP DEFAULT;
ALTER TABLE my_table ALTER id ADD GENERATED BY DEFAULT AS IDENTITY;

but the SEQUENCE strategy just seems to remove the DEFAULT:

#[ORM\GeneratedValue(strategy: 'SEQUENCE')]

ALTER TABLE my_table ALTER id DROP DEFAULT;

This behavior suggested that the default strategy on PostgreSQL would be IDENTITY and not SEQUENCE.

After digging into the code, it seems to be the case:

PostgreSQL isn't listed in NON_IDENTITY_DEFAULT_STRATEGY: 21e9fcbfbb/src/Mapping/ClassMetadataFactory.php (L63-L65)
but it is set only when using DBAL 3: 21e9fcbfbb/src/Mapping/ClassMetadataFactory.php (L631-L634)
when using DBAL 4, the previous code isn't triggered, and falls back to IDENTITY: 21e9fcbfbb/src/Mapping/ClassMetadataFactory.php (L666)
Doctrine DBAL's PostgreSQLPlatform then outputs GENERATED BY DEFAULT AS IDENTITY: 1432ec6851/src/Platforms/PostgreSQLPlatform.php (L276)

Thank you for reviewing my PR, tell me if there is anything wrong / that can be improved in it 👍
Thank you for all the work you did on Doctrine!

PS : Do these documentation changes need to be backported all the way back to ORM 3.0? The initial commit that introduced this difference seems to date back to ORM 3.0 RC 1: bdc039fe31

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/doctrine/orm/pull/12148 **Author:** [@lucasmirloup](https://github.com/lucasmirloup) **Created:** 8/26/2025 **Status:** ✅ Merged **Merged:** 8/27/2025 **Merged by:** [@greg0ire](https://github.com/greg0ire) **Base:** `3.5.x` ← **Head:** `docs/generation-strategies-dbal-4` --- ### 📝 Commits (2) - [`c164ae4`](https://github.com/doctrine/orm/commit/c164ae434febef66681caed86ec148a4adc265c4) docs: generation strategies differences between DBAL 3 and 4 - [`f7d4e37`](https://github.com/doctrine/orm/commit/f7d4e379bc15a8b8d1d0de63174ac13fbc8c6840) docs: consistent PostgreSQL's name case ### 📊 Changes **2 files changed** (+9 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `docs/en/reference/basic-mapping.rst` (+7 -5) 📝 `docs/en/tutorials/getting-started.rst` (+2 -2) </details> ### 📄 Description Hello, I'm currently updating Doctrine DBAL from version 3 to 4 on an app that uses Doctrine generated ID columns (with no strategy defined, thus using `AUTO` if I'm not mistaken) with PostgreSQL 17. I suspect that the generation strategies' documentation for PostgreSQL is outdated or inaccurate, due to changes introduced in / for Doctrine DBAL 4. Here's a more detailed report / explanation: I initially encountered database errors about PostgreSQL's `SEQUENCE`, and tried tinkering with the strategy, to no avail. I then stumbled upon the following documentation: https://github.com/doctrine/dbal/blob/4.3.x/docs/en/how-to/postgresql-identity-migration.rst Still, something about the generation strategies' documentation confused me: the documentation claims that no matter Doctrine DBAL's version, the default (`AUTO`) strategy on PostgreSQL is `SEQUENCE`. When tested on my app, either of these 2 lines produce the same database migrations: ```php #[ORM\GeneratedValue(strategy: 'IDENTITY')] #[ORM\GeneratedValue] ``` ```sql ALTER TABLE my_table ALTER id DROP DEFAULT; ALTER TABLE my_table ALTER id ADD GENERATED BY DEFAULT AS IDENTITY; ``` but the `SEQUENCE` strategy just seems to remove the `DEFAULT`: ```php #[ORM\GeneratedValue(strategy: 'SEQUENCE')] ``` ```sql ALTER TABLE my_table ALTER id DROP DEFAULT; ``` This behavior suggested that the default strategy on PostgreSQL would be `IDENTITY` and not `SEQUENCE`. After digging into the code, it seems to be the case: - PostgreSQL isn't listed in `NON_IDENTITY_DEFAULT_STRATEGY`: https://github.com/doctrine/orm/blob/21e9fcbfbbf9a72abd8bf0d3f3e9d8c397fb80f3/src/Mapping/ClassMetadataFactory.php#L63-L65 - but it is set only when using DBAL 3: https://github.com/doctrine/orm/blob/21e9fcbfbbf9a72abd8bf0d3f3e9d8c397fb80f3/src/Mapping/ClassMetadataFactory.php#L631-L634 - when using DBAL 4, the previous code isn't triggered, and falls back to `IDENTITY`: https://github.com/doctrine/orm/blob/21e9fcbfbbf9a72abd8bf0d3f3e9d8c397fb80f3/src/Mapping/ClassMetadataFactory.php#L666 - Doctrine DBAL's `PostgreSQLPlatform` then outputs `GENERATED BY DEFAULT AS IDENTITY`: https://github.com/doctrine/dbal/blob/1432ec68513bb1788d9ed4e7ace4f12f6595fb9c/src/Platforms/PostgreSQLPlatform.php#L276 Thank you for reviewing my PR, tell me if there is anything wrong / that can be improved in it :+1: Thank you for all the work you did on Doctrine! PS : Do these documentation changes need to be backported all the way back to ORM 3.0? The initial commit that introduced this difference seems to date back to ORM 3.0 RC 1: https://github.com/doctrine/orm/commit/bdc039fe314a85fb6c578e06c1dd7f7d383f06a7 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

admin added the pull-request label 2026-01-22 16:17:22 +01:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: doctrine/archived-orm#13521