feat: Add multi-backend testing infrastructure (Phase 1)

Implement infrastructure for testing DataJoint against both MySQL and
PostgreSQL backends. Tests automatically run against both backends via
parameterized fixtures, with support for testcontainers and docker-compose.

docker-compose.yaml changes:
- Added PostgreSQL 15 service with health checks
- Added PostgreSQL environment variables to app service
- PostgreSQL runs on port 5432 alongside MySQL on 3306

tests/conftest.py changes:
- Added postgres_container fixture (testcontainers integration)
- Added backend parameterization fixtures:
  * backend: Parameterizes tests to run as [mysql, postgresql]
  * db_creds_by_backend: Returns credentials for current backend
  * connection_by_backend: Creates connection for current backend
- Updated pytest_collection_modifyitems to auto-mark backend tests
- Backend-parameterized tests automatically get mysql, postgresql, and
  backend_agnostic markers

pyproject.toml changes:
- Added pytest markers: mysql, postgresql, backend_agnostic
- Updated testcontainers dependency: testcontainers[mysql,minio,postgres]>=4.0

tests/integration/test_multi_backend.py (NEW):
- Example backend-agnostic tests demonstrating infrastructure
- 4 tests × 2 backends = 8 test instances collected
- Tests verify: table declaration, foreign keys, data types, comments

Usage:
  pytest tests/                                  # All tests, both backends
  pytest -m "mysql"                              # MySQL tests only
  pytest -m "postgresql"                         # PostgreSQL tests only
  pytest -m "backend_agnostic"                   # Multi-backend tests only
  DJ_USE_EXTERNAL_CONTAINERS=1 pytest tests/    # Use docker-compose

Benefits:
- Zero-config testing: pytest automatically manages containers
- Flexible: testcontainers (auto) or docker-compose (manual)
- Selective: Run specific backends via pytest markers
- Parallel CI: Different jobs can test different backends
- Easy debugging: Use docker-compose for persistent containers

Phase 1 of multi-backend testing implementation complete.
Next phase: Convert existing tests to use backend fixtures.

Related: #1338

Author: dimitri-yatsenko

docker-compose.yaml

@@ -24,6 +24,19 @@ services:
       timeout: 30s
       retries: 5
       interval: 15s
+  postgres:
+    image: postgres:${POSTGRES_VER:-15}
+    environment:
+      - POSTGRES_PASSWORD=${PG_PASS:-password}
+      - POSTGRES_USER=${PG_USER:-postgres}
+      - POSTGRES_DB=${PG_DB:-test}
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
+      timeout: 30s
+      retries: 5
+      interval: 15s
   minio:
     image: minio/minio:${MINIO_VER:-RELEASE.2025-02-28T09-55-16Z}
     environment:
@@ -52,6 +65,8 @@ services:
     depends_on:
       db:
         condition: service_healthy
+      postgres:
+        condition: service_healthy
       minio:
         condition: service_healthy
     environment:
@@ -61,6 +76,10 @@ services:
       - DJ_TEST_HOST=db
       - DJ_TEST_USER=datajoint
       - DJ_TEST_PASSWORD=datajoint
+      - DJ_PG_HOST=postgres
+      - DJ_PG_USER=postgres
+      - DJ_PG_PASS=password
+      - DJ_PG_PORT=5432
       - S3_ENDPOINT=minio:9000
       - S3_ACCESS_KEY=datajoint
       - S3_SECRET_KEY=datajoint

pyproject.toml

@@ -89,7 +89,7 @@ test = [
   "pytest-cov",
   "requests",
   "graphviz",
-  "testcontainers[mysql,minio]>=4.0",
+  "testcontainers[mysql,minio,postgres]>=4.0",
   "polars>=0.20.0",
   "pyarrow>=14.0.0",
 ]
@@ -228,6 +228,9 @@ ignore-words-list = "rever,numer,astroid"
 markers = [
     "requires_mysql: marks tests as requiring MySQL database (deselect with '-m \"not requires_mysql\"')",
     "requires_minio: marks tests as requiring MinIO object storage (deselect with '-m \"not requires_minio\"')",
+    "mysql: marks tests that run on MySQL backend (select with '-m mysql')",
+    "postgresql: marks tests that run on PostgreSQL backend (select with '-m postgresql')",
+    "backend_agnostic: marks tests that should pass on all backends (auto-marked for parameterized tests)",
 ]
 
 

tests/conftest.py

@@ -66,6 +66,12 @@ def pytest_collection_modifyitems(config, items):
         "stores_config",
         "mock_stores",
     }
+    # Tests that use these fixtures are backend-parameterized
+    backend_fixtures = {
+        "backend",
+        "db_creds_by_backend",
+        "connection_by_backend",
+    }
 
     for item in items:
         # Get all fixtures this test uses (directly or indirectly)
@@ -80,6 +86,13 @@ def pytest_collection_modifyitems(config, items):
         if fixturenames & minio_fixtures:
             item.add_marker(pytest.mark.requires_minio)
 
+        # Auto-mark backend-parameterized tests
+        if fixturenames & backend_fixtures:
+            # Test will run for both backends - add all backend markers
+            item.add_marker(pytest.mark.mysql)
+            item.add_marker(pytest.mark.postgresql)
+            item.add_marker(pytest.mark.backend_agnostic)
+
 
 # =============================================================================
 # Container Fixtures - Auto-start MySQL and MinIO via testcontainers
@@ -118,6 +131,35 @@ def mysql_container():
     logger.info("MySQL container stopped")
 
 
+@pytest.fixture(scope="session")
+def postgres_container():
+    """Start PostgreSQL container for the test session (or use external)."""
+    if USE_EXTERNAL_CONTAINERS:
+        # Use external container - return None, credentials come from env
+        logger.info("Using external PostgreSQL container")
+        yield None
+        return
+
+    from testcontainers.postgres import PostgresContainer
+
+    container = PostgresContainer(
+        image="postgres:15",
+        username="postgres",
+        password="password",
+        dbname="test",
+    )
+    container.start()
+
+    host = container.get_container_host_ip()
+    port = container.get_exposed_port(5432)
+    logger.info(f"PostgreSQL container started at {host}:{port}")
+
+    yield container
+
+    container.stop()
+    logger.info("PostgreSQL container stopped")
+
+
 @pytest.fixture(scope="session")
 def minio_container():
     """Start MinIO container for the test session (or use external)."""
@@ -225,6 +267,91 @@ def s3_creds(minio_container) -> Dict:
         )
 
 
+# =============================================================================
+# Backend-Parameterized Fixtures
+# =============================================================================
+
+
+@pytest.fixture(scope="session", params=["mysql", "postgresql"])
+def backend(request):
+    """Parameterize tests to run against both backends."""
+    return request.param
+
+
+@pytest.fixture(scope="session")
+def db_creds_by_backend(backend, mysql_container, postgres_container):
+    """Get root database credentials for the specified backend."""
+    if backend == "mysql":
+        if mysql_container is not None:
+            host = mysql_container.get_container_host_ip()
+            port = mysql_container.get_exposed_port(3306)
+            return {
+                "backend": "mysql",
+                "host": f"{host}:{port}",
+                "user": "root",
+                "password": "password",
+            }
+        else:
+            # External MySQL container
+            host = os.environ.get("DJ_HOST", "localhost")
+            port = os.environ.get("DJ_PORT", "3306")
+            return {
+                "backend": "mysql",
+                "host": f"{host}:{port}" if port else host,
+                "user": os.environ.get("DJ_USER", "root"),
+                "password": os.environ.get("DJ_PASS", "password"),
+            }
+
+    elif backend == "postgresql":
+        if postgres_container is not None:
+            host = postgres_container.get_container_host_ip()
+            port = postgres_container.get_exposed_port(5432)
+            return {
+                "backend": "postgresql",
+                "host": f"{host}:{port}",
+                "user": "postgres",
+                "password": "password",
+            }
+        else:
+            # External PostgreSQL container
+            host = os.environ.get("DJ_PG_HOST", "localhost")
+            port = os.environ.get("DJ_PG_PORT", "5432")
+            return {
+                "backend": "postgresql",
+                "host": f"{host}:{port}" if port else host,
+                "user": os.environ.get("DJ_PG_USER", "postgres"),
+                "password": os.environ.get("DJ_PG_PASS", "password"),
+            }
+
+
+@pytest.fixture(scope="session")
+def connection_by_backend(db_creds_by_backend):
+    """Create connection for the specified backend."""
+    # Configure backend
+    dj.config["database.backend"] = db_creds_by_backend["backend"]
+
+    # Parse host:port
+    host_port = db_creds_by_backend["host"]
+    if ":" in host_port:
+        host, port = host_port.rsplit(":", 1)
+    else:
+        host = host_port
+        port = "3306" if db_creds_by_backend["backend"] == "mysql" else "5432"
+
+    dj.config["database.host"] = host
+    dj.config["database.port"] = int(port)
+    dj.config["safemode"] = False
+
+    connection = dj.Connection(
+        host=host_port,
+        user=db_creds_by_backend["user"],
+        password=db_creds_by_backend["password"],
+    )
+
+    yield connection
+    connection.close()
+
+
 # =============================================================================
 # DataJoint Configuration
 # =============================================================================

tests/integration/test_multi_backend.py

@@ -0,0 +1,143 @@
+"""
+Integration tests that verify backend-agnostic behavior.
+
+These tests run against both MySQL and PostgreSQL to ensure:
+1. DDL generation is correct
+2. SQL queries work identically
+3. Data types map correctly
+
+To run these tests:
+    pytest tests/integration/test_multi_backend.py  # Run against both backends
+    pytest -m "mysql" tests/integration/test_multi_backend.py  # MySQL only
+    pytest -m "postgresql" tests/integration/test_multi_backend.py  # PostgreSQL only
+"""
+
+import pytest
+import datajoint as dj
+
+
+@pytest.mark.backend_agnostic
+def test_simple_table_declaration(connection_by_backend, backend, prefix):
+    """Test that simple tables can be declared on both backends."""
+    schema = dj.Schema(
+        f"{prefix}_multi_backend_{backend}_simple",
+        connection=connection_by_backend,
+    )
+
+    @schema
+    class User(dj.Manual):
+        definition = """
+        user_id : int
+        ---
+        username : varchar(255)
+        created_at : datetime
+        """
+
+    # Verify table exists
+    assert User.is_declared
+
+    # Insert and fetch data
+    from datetime import datetime
+
+    User.insert1((1, "alice", datetime(2025, 1, 1)))
+    data = User.fetch1()
+
+    assert data["user_id"] == 1
+    assert data["username"] == "alice"
+
+    # Cleanup
+    schema.drop()
+
+
+@pytest.mark.backend_agnostic
+def test_foreign_keys(connection_by_backend, backend, prefix):
+    """Test foreign key declarations work on both backends."""
+    schema = dj.Schema(
+        f"{prefix}_multi_backend_{backend}_fk",
+        connection=connection_by_backend,
+    )
+
+    @schema
+    class Animal(dj.Manual):
+        definition = """
+        animal_id : int
+        ---
+        name : varchar(255)
+        """
+
+    @schema
+    class Observation(dj.Manual):
+        definition = """
+        -> Animal
+        obs_id : int
+        ---
+        notes : varchar(1000)
+        """
+
+    # Insert data
+    Animal.insert1((1, "Mouse"))
+    Observation.insert1((1, 1, "Active"))
+
+    # Verify data was inserted
+    assert len(Animal) == 1
+    assert len(Observation) == 1
+
+    # Cleanup
+    schema.drop()
+
+
+@pytest.mark.backend_agnostic
+def test_data_types(connection_by_backend, backend, prefix):
+    """Test that core data types work on both backends."""
+    schema = dj.Schema(
+        f"{prefix}_multi_backend_{backend}_types",
+        connection=connection_by_backend,
+    )
+
+    @schema
+    class TypeTest(dj.Manual):
+        definition = """
+        id : int
+        ---
+        int_value : int
+        str_value : varchar(255)
+        float_value : float
+        bool_value : bool
+        """
+
+    # Insert data
+    TypeTest.insert1((1, 42, "test", 3.14, True))
+
+    # Fetch and verify
+    data = (TypeTest & {"id": 1}).fetch1()
+    assert data["int_value"] == 42
+    assert data["str_value"] == "test"
+    assert abs(data["float_value"] - 3.14) < 0.001
+    assert data["bool_value"] == 1  # MySQL stores as tinyint(1)
+
+    # Cleanup
+    schema.drop()
+
+
+@pytest.mark.backend_agnostic
+def test_table_comments(connection_by_backend, backend, prefix):
+    """Test that table comments are preserved on both backends."""
+    schema = dj.Schema(
+        f"{prefix}_multi_backend_{backend}_comments",
+        connection=connection_by_backend,
+    )
+
+    @schema
+    class Commented(dj.Manual):
+        definition = """
+        # This is a test table for backend testing
+        id : int  # primary key
+        ---
+        value : varchar(255)  # some value
+        """
+
+    # Verify table was created
+    assert Commented.is_declared
+
+    # Cleanup
+    schema.drop()