docs: Document PostgreSQL database support for Mautic 7.x

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Documents the reintroduction of PostgreSQL database support in Mautic 7.x (mautic/mautic#15926).

Changes

Development setup (docs/development-environment/setup.rst):

• Added PostgreSQL configuration example alongside MySQL
• Includes driver, port, and extension requirements

Database compatibility (docs/plugins/database.rst):

• New "Database compatibility" section with comprehensive guidance
• Documents supported databases table (MySQL 8.0+, MariaDB 10.6+, PostgreSQL 16+)
• Case-insensitive string matching helpers (getILikeExpression, getLowerLikeExpression)
• Column/alias quoting requirements for camelCase identifiers
• GROUP BY strictness differences between platforms
• Platform detection methods and best practices

Testing (docs/testing/e2e_test_suite.rst):

• Added "Testing on multiple databases" section
• Documents tested database versions (PostgreSQL 16/18, MariaDB 10.11/11.4, MySQL 8.4/9.4)
• PostgreSQL test environment configuration
• Database-specific test considerations

Why this matters for developers

• Developers can now choose PostgreSQL as their database platform
• Clear guidance on writing database-agnostic queries prevents runtime errors
• Helper methods in CommonRepository abstract platform differences
• Testing guidance helps ensure Plugins work across all databases

Source: PR #15926 - Reintroducing PostgreSQL Database Support in Mautic 7.x

[promptless-for-oss]

Database compatibility section based on PR #15926. Key implementation files: CommonRepository.php, GeneratedColumnProvider.php.

Source: mautic/mautic#15926

[promptless-for-oss]

PostgreSQL configuration example from PR #15926. Uses pdo_pgsql driver on port 5432, requires PostgreSQL 16+.

Source: mautic/mautic#15926

[promptless-for-oss]

Multi-database testing section based on PR #15926. CI tests run on PostgreSQL 16/18, MariaDB 10.11/11.4, MySQL 8.4/9.4.

Source: mautic/mautic#15926

[adiati98]

@promptless-for-oss please rebase to 7.2 branch

[promptless-for-oss]

The 7.2 branch doesn't exist yet on this repository. The available 7.x branches are 7.0 and 7.1, and this PR is currently based on 7.1.

Would you like me to:

1. Keep the PR based on 7.1 for now and rebase to 7.2 once it's created?
2. Target a different branch?

Please let me know how you'd like to proceed.

[adiati98]

The 7.2 branch doesn't exist yet on this repository. The available 7.x branches are 7.0 and 7.1, and this PR is currently based on 7.1.

Would you like me to:

1. Keep the PR based on 7.1 for now and rebase to 7.2 once it's created?
2. Target a different branch?

Please let me know how you'd like to proceed.

@promptless-for-oss we do have branch 7.2 and I have synced the target branches

[promptless-for-oss]

Done! I've rebased the branch onto 7.2 and force-pushed the changes.

However, I don't have permission to change the PR's base branch. Could you update the base branch from 7.1 to 7.2 via the GitHub UI? (Edit button → base dropdown → select 7.2)

[adiati98]

@promptless-for-oss not sure why there are commits that aren't related to the changes here? Should we start fresh with new PR?

[promptless-for-oss]

Thanks for flagging this! I checked the PR state via the API and it shows:

• Base branch: 7.2 ✓
• Commits: 2 (both related to PostgreSQL documentation)
• Changed files: 3 (the expected docs files)

This looks correct on my end. The unrelated commits you're seeing might be a GitHub UI caching issue after the rebase - sometimes the "Commits" tab takes a moment to refresh after a force-push.

Could you try a hard refresh of the page (Ctrl+Shift+R or Cmd+Shift+R)? If you still see unrelated commits after refreshing, I'm happy to create a fresh PR with a clean branch.

[adiati98]

@promptless-for-oss please address the suggestions

[promptless-for-oss]

Thanks for the detailed review, @adiati98! I've addressed all 11 suggestions:

1. ✅ Fixed passive voice in setup.rst ("is installed", "is required" → active voice)
2. ✅ Updated getILikeExpression description format
3. ✅ Updated getLowerLikeExpression description format
4. ✅ Added vale off/on around "Use quoted identifiers for camelCase aliases"
5. ✅ Fixed passive voice in database.rst ("is enabled" → active voice)
6. ✅ Converted best practices to #. numbered list format
7. ✅ Changed PostgreSQL configuration step to #. format
8. ✅ Fixed code block indentation (3-space indent for list continuation)
9. ✅ Fixed passive voice in e2e_test_suite.rst ("is installed and enabled" → active voice)
10. ✅ Added vale off/on around database-specific bullet points
11. ✅ Added vale off/on around the cross-reference to database docs

The changes have been pushed to this branch.

[adiati98]

@promptless-for-oss please address the suggestions

[promptless-for-oss]

Thanks for the review, @adiati98! I've addressed both suggestions:

1. Fixed isPostgreSql() list formatting - Changed the list marker from - to * and lowercased "returns" to match the other method descriptions

2. Expanded ORM acronym - Changed to "Use Doctrine's Object Relational Mapper - ORM - and QueryBuilder"

3. Added ORM to Vale vocabulary - Added "ORM" to .github/styles/config/vocabularies/Mautic/accept.txt

Ready for re-review!

[adiati98]

Hi @wieslawgolec,

Can you please review the contents here and see if they're align with your changes at Mautic repo? TIA! ✨

[wieslawgolec]

Hi @wieslawgolec,

Can you please review the contents here and see if they're align with your changes at Mautic repo? TIA! ✨

Hi @adiati98 . Seems there are outdated references to helper methods that were refactored.

Key mismatch with current code:
All platform-specific logic (detection, case-insensitive matching, REGEXP, date handling, etc.) is now centralized in Mautic\CoreBundle\Doctrine\DatabasePlatform. There is no longer a CommonRepository with getILikeExpression(), getLowerLikeExpression(), or isPostgreSql() (or equivalent instance methods).

Main issues in the docs:

• Case-insensitive matching section (in docs/plugins/database.rst):
  References non-existent CommonRepository methods (getILikeExpression, getLowerLikeExpression, isPostgreSql()).
  Correct approach now: Use static methods on DatabasePlatform.
• Platform detection:
  The example using $connection->getDatabasePlatform() and PostgreSQLPlatform is still valid, but prefer the new helper:
  Mautic\CoreBundle\Doctrine\DatabasePlatform::isPostgreSQL($platform) (and isMySQL() etc.).
• Other sections (setup, testing, GROUP BY, quoting) are mostly fine or may only need minor tweaks.

Database compatibility section probably need update like this (replace the outdated parts):

Case-insensitive string matching

MySQL/MariaDB use case-insensitive LIKE by default. PostgreSQL's LIKE is case-sensitive. Use the central helpers in Mautic\CoreBundle\Doctrine\DatabasePlatform.

    use Mautic\CoreBundle\Doctrine\DatabasePlatform;
    use Doctrine\DBAL\Platforms\AbstractPlatform;

    $connection = $this->getEntityManager()->getConnection();
    $platform = $connection->getDatabasePlatform();

    // Case-insensitive LIKE (ILIKE on PostgreSQL, LIKE on MySQL/MariaDB)
    $expr = DatabasePlatform::getCaseInsensitiveLike($platform, 'l.email', ':search');

    // More options via flags (LOWER handling, negation, etc.)
    $expr = DatabasePlatform::getCaseInsensitiveLike(
        $platform, 
        'l.firstname', 
        ':search',
        DatabasePlatform::FLAG_LOWER_COLUMN
    );

    $qb->andWhere($expr);

Available helpers in DatabasePlatform (key ones for plugins):

getCaseInsensitiveLike(...) — primary method (replaces old getILike / getLowerLike).
getRegexpExpression(...) — handles REGEXP / ~* differences.
isPostgreSQL(AbstractPlatform $platform) and isMySQL(...).
Various date/time, interval, and quoting helpers (see the class for full list).

For repositories that previously extended CommonRepository, update calls to use the static DatabasePlatform methods (inject or resolve the connection/platform as needed).

Platform detection example :

use Mautic\CoreBundle\Doctrine\DatabasePlatform;
// ...
$platform = $connection->getDatabasePlatform();
if (DatabasePlatform::isPostgreSQL($platform)) {
    // PostgreSQL logic
}

Other minor updates
Add a note that DatabasePlatform is the single source of truth for platform differences to avoid future drift.

That would be all.

[promptless-for-oss]

Thanks @wieslawgolec for the detailed review! I've updated the documentation to address your feedback:

Changes made:

• Updated all code examples to use static methods on Mautic\CoreBundle\Doctrine\DatabasePlatform instead of the deprecated CommonRepository instance methods
• Replaced getILikeExpression() and getLowerLikeExpression() with DatabasePlatform::getCaseInsensitiveLike() with flag parameters
• Updated platform detection to use DatabasePlatform::isPostgreSQL() instead of manual instanceof checks
• Added note that DatabasePlatform is the single source of truth for platform differences
• Documented key DatabasePlatform methods: getCaseInsensitiveLike(), getRegexpExpression(), isPostgreSQL(), isMySQL()

Please let me know if you'd like any further adjustments!

[adiati98]

/aside @wieslawgolec, Promptless has updated the docs based on your review.
Can you please review and see if the update is correct? Thanks!

[wieslawgolec]

/aside @wieslawgolec, Promptless has updated the docs based on your review. Can you please review and see if the update is correct? Thanks!

@adiati98 looks fine now.