Add cross-driver testsuite for MySQL and Postgres

Refactor DbTest and MapperTest onto a shared DatabaseTestCase so the
existing tests run against SQLite, MySQL, and Postgres. The driver,
DSN, and credentials are selected from environment variables; default
to in-memory SQLite to preserve the current zero-config experience.
A docker-compose.yml provides MySQL and Postgres locally on non-default
ports, and CI fans out into a three-driver matrix using GitHub Actions
services.

Fix Mapper::checkNewIdentity to wrap lastInsertId() in a savepoint on
Postgres. After an INSERT with an explicit id, Postgres errors with
"lastval is not yet defined in this session" and marks the surrounding
transaction as aborted; the catch swallowed the exception but the
subsequent commit then discarded the row. The savepoint contains the
abort. MySQL is excluded because issuing SAVEPOINT between the INSERT
and LAST_INSERT_ID() resets the latter to 0.

Also fix four raw-SQL portability bugs in MapperTest that SQLite and
MySQL had hidden: double-quoted string literals (Postgres reads them
as identifiers) and a VARCHAR/integer comparison.

Author: alganet

.env.example

@@ -0,0 +1,15 @@
+# Driver selection for the integration testsuite.
+# Defaults to sqlite (in-memory) when unset.
+DB_DRIVER=sqlite
+
+# MySQL (matches docker-compose.yml `mysql` service)
+# DB_DRIVER=mysql
+# DB_DSN=mysql:host=127.0.0.1;port=33306;dbname=relational_test
+# DB_USER=root
+# DB_PASSWORD=test
+
+# Postgres (matches docker-compose.yml `postgres` service)
+# DB_DRIVER=pgsql
+# DB_DSN=pgsql:host=127.0.0.1;port=55432;dbname=relational_test
+# DB_USER=postgres
+# DB_PASSWORD=test

.github/workflows/ci.yml

@@ -6,16 +6,79 @@ on:
   pull_request:
 
 jobs:
-  tests:
-    name: Tests
+  tests-sqlite:
+    name: Tests (sqlite)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
       - uses: shivammathur/setup-php@v2
         with:
           php-version: '8.5'
+          extensions: pdo_sqlite
       - uses: ramsey/composer-install@v3
       - run: composer phpunit
+        env:
+          DB_DRIVER: sqlite
+
+  tests-mysql:
+    name: Tests (mysql)
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: test
+          MYSQL_DATABASE: relational_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -ptest"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=20
+    steps:
+      - uses: actions/checkout@v6
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          extensions: pdo_mysql
+      - uses: ramsey/composer-install@v3
+      - run: composer phpunit
+        env:
+          DB_DRIVER: mysql
+          DB_DSN: mysql:host=127.0.0.1;port=3306;dbname=relational_test
+          DB_USER: root
+          DB_PASSWORD: test
+
+  tests-pgsql:
+    name: Tests (pgsql)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: relational_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres -d relational_test"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=20
+    steps:
+      - uses: actions/checkout@v6
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          extensions: pdo_pgsql
+      - uses: ramsey/composer-install@v3
+      - run: composer phpunit
+        env:
+          DB_DRIVER: pgsql
+          DB_DSN: pgsql:host=127.0.0.1;port=5432;dbname=relational_test
+          DB_USER: postgres
+          DB_PASSWORD: test
 
   code-coverage:
     name: Code Coverage

CONTRIBUTING.md

@@ -48,6 +48,30 @@ No test should fail.
 You can tweak the PHPUnit's settings by copying `phpunit.xml.dist` to `phpunit.xml`
 and changing it according to your needs.
 
+### Running tests against MySQL and PostgreSQL
+
+The default `vendor/bin/phpunit` run uses an in-memory SQLite database. To
+exercise the full testsuite against MySQL and PostgreSQL as well, start the
+bundled containers and use the driver-specific composer scripts:
+
+```shell
+docker compose up -d
+composer phpunit:sqlite
+composer phpunit:mysql
+composer phpunit:pgsql
+# or all three in sequence:
+composer phpunit:all
+```
+
+The `docker-compose.yml` exposes MySQL on host port `33306` and PostgreSQL on
+`55432` (non-default to avoid conflicts with locally installed databases).
+The composer scripts hard-code the credentials defined in `docker-compose.yml`;
+override `DB_DRIVER`, `DB_DSN`, `DB_USER`, and `DB_PASSWORD` to point at a
+different setup — see `.env.example` for the supported variables.
+
+CI runs the same three-driver matrix on every push and pull request via
+GitHub Actions services (no Docker required in CI).
+
 ## Standards
 
 We are trying to follow the [PHP-FIG](http://www.php-fig.org)'s standards, so

composer.json

@@ -45,6 +45,14 @@
         "phpcs": "vendor/bin/phpcs",
         "phpstan": "vendor/bin/phpstan analyze",
         "phpunit": "vendor/bin/phpunit",
+        "phpunit:sqlite": "DB_DRIVER=sqlite vendor/bin/phpunit",
+        "phpunit:mysql": "DB_DRIVER=mysql DB_USER=root DB_PASSWORD=test vendor/bin/phpunit",
+        "phpunit:pgsql": "DB_DRIVER=pgsql DB_USER=postgres DB_PASSWORD=test vendor/bin/phpunit",
+        "phpunit:all": [
+            "@phpunit:sqlite",
+            "@phpunit:mysql",
+            "@phpunit:pgsql"
+        ],
         "coverage": "vendor/bin/phpunit --coverage-text",
         "qa": [
             "@phpcs",

docker-compose.yml

@@ -0,0 +1,29 @@
+# Host ports (33306, 55432) deliberately differ from the MySQL/Postgres
+# defaults so a developer with a local install of either is not blocked.
+# CI runs against the standard ports (3306, 5432) via GitHub Actions services.
+services:
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: test
+      MYSQL_DATABASE: relational_test
+    ports:
+      - "33306:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-ptest"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_PASSWORD: test
+      POSTGRES_DB: relational_test
+    ports:
+      - "55432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d relational_test"]
+      interval: 5s
+      timeout: 5s
+      retries: 20

phpunit.xml.dist

@@ -4,7 +4,11 @@
          bootstrap="vendor/autoload.php">
     <testsuites>
         <testsuite name="unit">
-            <directory suffix="Test.php">tests</directory>
+            <file>tests/SqlTest.php</file>
+        </testsuite>
+        <testsuite name="database">
+            <file>tests/DbTest.php</file>
+            <file>tests/MapperTest.php</file>
         </testsuite>
     </testsuites>
     <source>

src/Mapper.php

@@ -205,12 +205,35 @@ private function rawInsert(
 
     private function checkNewIdentity(object $entity, Scope $scope): bool
     {
+        $conn = $this->db->connection;
+
+        // Postgres aborts the surrounding transaction when lastInsertId() is
+        // called and no sequence has fired in the session (e.g. the row was
+        // inserted with an explicit id). Wrap in a savepoint so the abort is
+        // contained and the insert survives the commit. MySQL is excluded
+        // because issuing SAVEPOINT between the INSERT and LAST_INSERT_ID()
+        // resets the latter to 0.
+        $useSavepoint = $conn->inTransaction()
+            && $conn->getAttribute(PDO::ATTR_DRIVER_NAME) === 'pgsql';
+
+        if ($useSavepoint) {
+            $conn->exec('SAVEPOINT mapper_lastid');
+        }
+
         try {
-            $identity = $this->db->connection->lastInsertId();
+            $identity = $conn->lastInsertId();
         } catch (PDOException) {
+            if ($useSavepoint) {
+                $conn->exec('ROLLBACK TO SAVEPOINT mapper_lastid');
+            }
+
             return false;
         }
 
+        if ($useSavepoint) {
+            $conn->exec('RELEASE SAVEPOINT mapper_lastid');
+        }
+
         if (!$identity) {
             return false;
         }

tests/Database/ConnectionFactory.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Relational\Database;
+
+use InvalidArgumentException;
+use PDO;
+
+use function getenv;
+use function in_array;
+
+final class ConnectionFactory
+{
+    public static function driver(): string
+    {
+        $driver = getenv('DB_DRIVER');
+        if ($driver === false || $driver === '') {
+            return 'sqlite';
+        }
+
+        return $driver;
+    }
+
+    /** @throws DriverUnavailable */
+    public static function create(): PDO
+    {
+        $driver = self::driver();
+        if (!in_array($driver, PDO::getAvailableDrivers(), true)) {
+            throw new DriverUnavailable($driver);
+        }
+
+        $dsn = self::dsn($driver);
+        $user = self::env('DB_USER');
+        $password = self::env('DB_PASSWORD');
+
+        $pdo = new PDO($dsn, $user, $password);
+        $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
+
+        return $pdo;
+    }
+
+    private static function dsn(string $driver): string
+    {
+        $dsn = self::env('DB_DSN');
+        if ($dsn !== null) {
+            return $dsn;
+        }
+
+        return match ($driver) {
+            'sqlite' => 'sqlite::memory:',
+            'mysql' => 'mysql:host=127.0.0.1;port=33306;dbname=relational_test',
+            'pgsql' => 'pgsql:host=127.0.0.1;port=55432;dbname=relational_test',
+            default => throw new InvalidArgumentException('Unsupported driver: ' . $driver),
+        };
+    }
+
+    private static function env(string $name): string|null
+    {
+        $value = getenv($name);
+        if ($value === false || $value === '') {
+            return null;
+        }
+
+        return $value;
+    }
+}

tests/Database/DatabaseTestCase.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Relational\Database;
+
+use PDO;
+use PHPUnit\Framework\TestCase;
+
+abstract class DatabaseTestCase extends TestCase
+{
+    protected PDO $conn;
+
+    protected string $driver;
+
+    protected function setUp(): void
+    {
+        try {
+            $this->conn = ConnectionFactory::create();
+        } catch (DriverUnavailable $e) {
+            $this->markTestSkipped($e->getMessage());
+        }
+
+        $this->driver = ConnectionFactory::driver();
+    }
+
+    protected function resetTables(string ...$names): void
+    {
+        foreach ($names as $name) {
+            $this->conn->exec('DROP TABLE IF EXISTS ' . $name);
+        }
+    }
+
+    /**
+     * Resync Postgres IDENTITY sequences after fixtures with explicit IDs.
+     * No-op for sqlite and mysql (sqlite picks max+1 automatically; mysql
+     * advances AUTO_INCREMENT on explicit insert).
+     *
+     * @param array<string, string> $tables map of table name to id column name
+     */
+    protected function syncSequences(array $tables): void
+    {
+        if ($this->driver !== 'pgsql') {
+            return;
+        }
+
+        foreach ($tables as $table => $idColumn) {
+            $this->conn->exec(
+                "SELECT setval(pg_get_serial_sequence('" . $table . "', '" . $idColumn . "'), "
+                . 'COALESCE((SELECT MAX(' . $idColumn . ') FROM ' . $table . '), 1))',
+            );
+        }
+    }
+}

tests/Database/DriverUnavailable.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Relational\Database;
+
+use RuntimeException;
+
+final class DriverUnavailable extends RuntimeException
+{
+    public function __construct(public readonly string $driver)
+    {
+        parent::__construct('PDO driver "' . $driver . '" is not available');
+    }
+}