Refactor PostgreSQLExecutor to support Windows compatibility for process management

.github/workflows/oldest-postgres.yml

@@ -52,7 +52,7 @@ jobs:
         run: |
           sudo locale-gen de_DE.UTF-8
       - name: install libpq
-        if: ${{ contains(inputs.python-versions, 'pypy') }}
+        if: ${{ contains(matrix.python-version, 'pypy') && runner.os == 'Linux' }}
         run: sudo apt install libpq5
       - name: Install oldest supported versions
         uses: fizyk/actions-reuse/.github/actions/pipenv-run@v4.2.1

.github/workflows/single-postgres.yml

@@ -43,29 +43,69 @@ jobs:
       - uses: ankane/setup-postgres@v1
         with:
           postgres-version: ${{ inputs.postgresql }}
+      - name: Detect PostgreSQL path on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $pgPath = "C:\Program Files\PostgreSQL\${{ inputs.postgresql }}\bin\pg_ctl.exe"
+          if (Test-Path $pgPath) {
+            echo "POSTGRESQL_EXEC=$pgPath" >> $env:GITHUB_ENV
+          } else {
+            $pgPath = (Get-Command pg_ctl -ErrorAction SilentlyContinue).Source
+            if ($pgPath) {
+              echo "POSTGRESQL_EXEC=$pgPath" >> $env:GITHUB_ENV
+            }
+          }
+
+          # Verify that PostgreSQL was found
+          if (-not $pgPath) {
+            Write-Error "Error: pg_ctl not found in expected locations. Checked hardcoded path and system PATH."
+            exit 1
+          }
+      - name: Set PostgreSQL path for Unix/macOS
+        if: runner.os != 'Windows'
+        run: |
+          # Try to find pg_ctl dynamically for cross-platform compatibility
+          if command -v pg_ctl >/dev/null 2>&1; then
+            PG_CTL_PATH=$(command -v pg_ctl)
+            echo "POSTGRESQL_EXEC=$PG_CTL_PATH" >> $GITHUB_ENV
+          elif [ -f "/opt/homebrew/opt/postgresql@${{ inputs.postgresql }}/bin/pg_ctl" ]; then
+            # macOS Apple Silicon Homebrew path
+            echo "POSTGRESQL_EXEC=/opt/homebrew/opt/postgresql@${{ inputs.postgresql }}/bin/pg_ctl" >> $GITHUB_ENV
+          elif [ -f "/usr/local/opt/postgresql@${{ inputs.postgresql }}/bin/pg_ctl" ]; then
+            # macOS Intel Homebrew path
+            echo "POSTGRESQL_EXEC=/usr/local/opt/postgresql@${{ inputs.postgresql }}/bin/pg_ctl" >> $GITHUB_ENV
+          elif [ -f "/usr/lib/postgresql/${{ inputs.postgresql }}/bin/pg_ctl" ]; then
+            # Debian/Ubuntu path (fallback)
+            echo "POSTGRESQL_EXEC=/usr/lib/postgresql/${{ inputs.postgresql }}/bin/pg_ctl" >> $GITHUB_ENV
+          else
+            echo "Error: pg_ctl not found in expected locations"
+            exit 1
+          fi
       - name: Check installed locales
+        if: runner.os != 'Windows'
         run: |
           locale -a
       - name: update locale for tests
         if: ${{ inputs.os == 'ubuntu-latest' }}
         run: |
           sudo locale-gen de_DE.UTF-8
       - name: install libpq
-        if: ${{ contains(inputs.python-versions, 'pypy') }}
+        if: ${{ contains(matrix.python-version, 'pypy') && runner.os == 'Linux' }}
         run: sudo apt install libpq5
       - name: Run test
         uses: fizyk/actions-reuse/.github/actions/pipenv-run@v4.2.1
         with:
-          command: pytest -svv -p no:xdist --postgresql-exec="/usr/lib/postgresql/${{ inputs.postgresql }}/bin/pg_ctl" -k "not docker" --cov-report=xml
+          command: pytest -svv -p no:xdist --postgresql-exec="${{ env.POSTGRESQL_EXEC }}" -k "not docker" --cov-report=xml --basetemp="${{ runner.temp }}/pytest-basetemp"
       - name: Run xdist test
         uses: fizyk/actions-reuse/.github/actions/pipenv-run@v4.2.1
         with:
-          command: pytest -n auto --dist loadgroup --max-worker-restart 0 --postgresql-exec="/usr/lib/postgresql/${{ inputs.postgresql }}/bin/pg_ctl" -k "not docker" --cov-report=xml:coverage-xdist.xml
+          command: pytest -n auto --dist loadgroup --max-worker-restart 0 --postgresql-exec="${{ env.POSTGRESQL_EXEC }}" -k "not docker" --cov-report=xml:coverage-xdist.xml --basetemp="${{ runner.temp }}/pytest-basetemp"
       - uses: actions/upload-artifact@v7
         if: failure()
         with:
           name: postgresql-${{ matrix.python-version }}-${{ inputs.postgresql }}
-          path: /tmp/pytest-of-runner/**
+          path: ${{ runner.temp }}/pytest-basetemp/**
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5.5.2
         with:

.github/workflows/tests.yml

@@ -77,6 +77,33 @@ jobs:
       python-versions: '["3.13", "3.14"]'
     secrets:
       codecov_token: ${{ secrets.CODECOV_TOKEN }}
+  windows_postgres_18:
+    needs: [postgresql_18]
+    uses: ./.github/workflows/single-postgres.yml
+    with:
+      postgresql: 18
+      os: windows-latest
+      python-versions: '["3.12", "3.13", "3.14"]'
+    secrets:
+      codecov_token: ${{ secrets.CODECOV_TOKEN }}
+  windows_postgres_17:
+    needs: [postgresql_17, windows_postgres_18]
+    uses: ./.github/workflows/single-postgres.yml
+    with:
+      postgresql: 17
+      os: windows-latest
+      python-versions: '["3.12", "3.13", "3.14"]'
+    secrets:
+      codecov_token: ${{ secrets.CODECOV_TOKEN }}
+  windows_postgres_16:
+    needs: [postgresql_16, windows_postgres_17]
+    uses: ./.github/workflows/single-postgres.yml
+    with:
+      postgresql: 16
+      os: windows-latest
+      python-versions: '["3.13", "3.14"]'
+    secrets:
+      codecov_token: ${{ secrets.CODECOV_TOKEN }}
   docker_postgresql_18:
     needs: [postgresql_18]
     uses: ./.github/workflows/dockerised-postgres.yml

newsfragments/1182.feature.rst

@@ -0,0 +1 @@
+Add Windows compatibility for ``PostgreSQLExecutor`` with platform-specific command templates (``UNIX_PROC_START_COMMAND`` / ``WINDOWS_PROC_START_COMMAND``) and a dedicated ``_windows_terminate_process`` method for graceful process termination on Windows.

pytest_postgresql/executor.py

@@ -17,6 +17,8 @@
 # along with pytest-postgresql.  If not, see <http://www.gnu.org/licenses/>.
 """PostgreSQL executor crafter around pg_ctl."""
 
+import logging
+import os
 import os.path
 import platform
 import re
@@ -32,10 +34,16 @@
 
 from pytest_postgresql.exceptions import ExecutableMissingException, PostgreSQLUnsupported
 
+logger = logging.getLogger(__name__)
+
 _LOCALE = "C.UTF-8"
 
 if platform.system() == "Darwin":
+    # Darwin does not have C.UTF-8, but en_US.UTF-8 is always available
     _LOCALE = "en_US.UTF-8"
+elif platform.system() == "Windows":
+    # Windows doesn't support C.UTF-8 or en_US.UTF-8, use plain "C" locale
+    _LOCALE = "C"
 
 
 T = TypeVar("T", bound="PostgreSQLExecutor")
@@ -48,11 +56,26 @@ class PostgreSQLExecutor(TCPExecutor):
     <http://www.postgresql.org/docs/current/static/app-pg-ctl.html>`_
     """
 
-    BASE_PROC_START_COMMAND = (
+    # Unix command template - uses single quotes for PostgreSQL config value quoting
+    # which protects paths with spaces in unix_socket_directories.
+    # On Unix, mirakuru uses shlex.split() with shell=False, so single quotes
+    # inside double-quoted strings are preserved and passed to PostgreSQL's config parser.
+    UNIX_PROC_START_COMMAND = (
         '{executable} start -D "{datadir}" '
         "-o \"-F -p {port} -c log_destination='stderr' "
         "-c logging_collector=off "
-        "-c unix_socket_directories='{unixsocketdir}' {postgres_options}\" "
+        "-c unix_socket_directories='{unixsocketdir}'{postgres_options}\" "
+        '-l "{logfile}" {startparams}'
+    )
+
+    # Windows command template - no single quotes (cmd.exe treats them as literals,
+    # not delimiters) and unix_socket_directories is omitted entirely since PostgreSQL
+    # ignores it on Windows. On Windows, mirakuru forces shell=True so the command
+    # goes through cmd.exe.
+    WINDOWS_PROC_START_COMMAND = (
+        '{executable} start -D "{datadir}" '
+        '-o "-F -p {port} -c log_destination=stderr '
+        '-c logging_collector=off{postgres_options}" '
         '-l "{logfile}" {startparams}'
     )
 
@@ -108,14 +131,18 @@ def __init__(
         self.logfile = logfile
         self.startparams = startparams
         self.postgres_options = postgres_options
-        command = self.BASE_PROC_START_COMMAND.format(
+        if platform.system() == "Windows":
+            command_template = self.WINDOWS_PROC_START_COMMAND
+        else:
+            command_template = self.UNIX_PROC_START_COMMAND
+        command = command_template.format(
             executable=self.executable,
             datadir=self.datadir,
             port=port,
             unixsocketdir=self.unixsocketdir,
             logfile=self.logfile,
             startparams=self.startparams,
-            postgres_options=self.postgres_options,
+            postgres_options=f" {self.postgres_options}" if self.postgres_options else "",
         )
         super().__init__(
             command,
@@ -219,17 +246,57 @@ def running(self) -> bool:
         status_code = subprocess.getstatusoutput(f'{self.executable} status -D "{self.datadir}"')[0]
         return status_code == 0
 
+    def _windows_terminate_process(self, _sig: Optional[int] = None) -> None:
+        """Terminate process on Windows.
+
+        :param _sig: Signal parameter (unused on Windows but included for consistency)
+        """
+        if self.process is None:
+            return
+
+        try:
+            # On Windows, try to terminate gracefully first
+            self.process.terminate()
+            # Give it a chance to terminate gracefully
+            try:
+                self.process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                # If it doesn't terminate gracefully, force kill
+                self.process.kill()
+                try:
+                    self.process.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    logger.warning(
+                        "Process %s could not be cleaned up after kill() and may be a zombie process",
+                        self.process.pid if self.process else "unknown",
+                    )
+        except (OSError, AttributeError) as e:
+            # Process might already be dead or other issues
+            logger.debug(
+                "Exception during Windows process termination: %s: %s",
+                type(e).__name__,
+                e,
+            )
+
     def stop(self: T, sig: Optional[int] = None, exp_sig: Optional[int] = None) -> T:
         """Issue a stop request to executable."""
         subprocess.check_output(
-            f'{self.executable} stop -D "{self.datadir}" -m f',
-            shell=True,
+            [self.executable, "stop", "-D", self.datadir, "-m", "f"],
         )
         try:
-            super().stop(sig, exp_sig)
+            if platform.system() == "Windows":
+                self._windows_terminate_process(sig)
+            else:
+                super().stop(sig, exp_sig)
         except ProcessFinishedWithError:
             # Finished, leftovers ought to be cleaned afterwards anyway
             pass
+        except AttributeError:
+            # Fallback for edge cases where os.killpg doesn't exist (e.g., Windows)
+            if not hasattr(os, "killpg"):
+                self._windows_terminate_process(sig)
+            else:
+                raise
         return self
 
     def __del__(self) -> None:

tests/conftest.py

@@ -4,7 +4,6 @@
 from pathlib import Path
 
 from pytest_postgresql import factories
-from pytest_postgresql.plugin import *  # noqa: F403,F401
 
 pytest_plugins = ["pytester"]
 POSTGRESQL_VERSION = os.environ.get("POSTGRES", "13")