feat: Add ExecWaitStrategy and migrate Postgres from deprecated decorator (#935)

## Problem

The `PostgresContainer` currently uses the deprecated
`@wait_container_is_ready()` decorator, which is slated for removal. The
container was previously migrated away from log-based waiting due to
locale-dependent issues (#703, #695), but still relies on the deprecated
decorator pattern.

  ## Solution

This PR introduces a new `ExecWaitStrategy` wait strategy and migrates
`PostgresContainer` to use it.

  ### Changes

1. **New `ExecWaitStrategy` in
`core/testcontainers/core/wait_strategies.py`**
- Executes commands inside containers and waits for expected exit codes
     - Follows the modern structured wait strategy pattern
     - Reusable for any `DockerContainer` with CLI-based health checks
     - Composable with other wait strategies via `CompositeWaitStrategy`
     - Includes runtime check to ensure container supports `exec()`

  2. **Updated `modules/postgres/testcontainers/postgres/__init__.py`**
- Migrated `_connect()` method from `@wait_container_is_ready` decorator
to `ExecWaitStrategy`
     - Uses `psql` command execution to verify database readiness
     - Maintains existing behavior and password escaping logic

  ### Design Consideration: Protocol Limitations 

**Issue**: The `WaitStrategyTarget` protocol is designed to support both
`DockerContainer` and `ComposeContainer`, but `ExecWaitStrategy` only
works with `DockerContainer` (which has an `exec()`
  method). 

**Current Solution**: Runtime check with `hasattr(container, "exec")`
that raises a clear error if used with incompatible containers.

  **Discussion Points**:
- Should we have separate protocol types for different container
capabilities?
- Should `ExecWaitStrategy` accept a more specific type (e.g.,
`DockerContainer` directly)?
- Is the runtime check acceptable, or should this be enforced at the
type level?

I've opted for the runtime check to maintain consistency with the
existing `WaitStrategyTarget` protocol pattern, but I'm open to
alternatives if the maintainers prefer a different approach.


# PR Checklist

- [x] Your PR title follows the [Conventional
Commits](https://www.conventionalcommits.org/en/v1.0.0/) syntax
  as we make use of this for detecting Semantic Versioning changes.
- Additions to the community modules do not contribute to SemVer scheme:
all community features will be tagged
[community-feat](https://github.com/testcontainers/testcontainers-python/issues?q=label%3Acommunity-feat+),
but we do not want to release minor or major versions due to features or
breaking changes outside of core.
So please use `fix(postgres):` or `fix(my_new_vector_db):` if you want
to add or modify community modules.
This may change in the future if we have a separate package released
with community modules.
- [x] Your PR allows maintainers to edit your branch, this will speed up
resolving minor issues!
- [x] The new container is implemented under `modules/*`
- Your module follows [PEP 420](https://peps.python.org/pep-0420/) with
implicit namespace packages
    (if unsure, look at other existing community modules)
  - Your package namespacing follows `testcontainers.<modulename>.*`
    and you DO NOT have an `__init__.py` above your module's level.
  - Your module has its own tests under `modules/*/tests`
- Your module has a `README.rst` and hooks in the `.. auto-class` and
`.. title` of your container
- Implement the new feature (typically in `__init__.py`) and
corresponding tests.
- [x] Your module is added in `pyproject.toml`
- it is declared under `tool.poetry.packages` - see other community
modules
- it is declared under `tool.poetry.extras` with the same name as your
module name,
we still prefer adding _NO EXTRA DEPENDENCIES_, meaning `mymodule = []`
is the preferred addition
    (see the notes at the bottom)
- [x] Your branch is up-to-date (or your branch will be rebased with
`git rebase`)

Author: tylernisonoff

core/testcontainers/core/wait_strategies.py

@@ -6,6 +6,7 @@
 - HealthcheckWaitStrategy: Wait for Docker health checks to pass
 - PortWaitStrategy: Wait for TCP ports to be available
 - FileExistsWaitStrategy: Wait for files to exist on the filesystem
+- ExecWaitStrategy: Wait for command execution inside container to succeed
 - CompositeWaitStrategy: Combine multiple wait strategies
 
 Example:
@@ -19,6 +20,9 @@
     # Wait for log message
     container.waiting_for(LogMessageWaitStrategy("Server started"))
 
+    # Wait for command execution
+    container.waiting_for(ExecWaitStrategy(["pg_isready", "-U", "postgres"]))
+
     # Combine multiple strategies
     container.waiting_for(CompositeWaitStrategy(
         LogMessageWaitStrategy("Database ready"),
@@ -779,9 +783,103 @@ def wait_until_ready(self, container: WaitStrategyTarget) -> None:
         logger.debug("CompositeWaitStrategy: All strategies completed successfully")
 
 
+class ExecWaitStrategy(WaitStrategy):
+    """
+    Wait for a command execution inside the container to succeed.
+
+    This strategy executes a command inside the container and waits for it to
+    return a successful exit code. It's useful for databases and services
+    that provide CLI tools to check readiness.
+
+    Args:
+        command: Command to execute (list of strings or single string)
+        expected_exit_code: Expected exit code for success (default: 0)
+
+    Example:
+        # Wait for Postgres readiness
+        strategy = ExecWaitStrategy(
+            ["sh", "-c",
+             "PGPASSWORD='password' psql -U user -d db -h 127.0.0.1 -c 'select 1;'"]
+        )
+
+        # Wait for Redis readiness
+        strategy = ExecWaitStrategy(["redis-cli", "ping"])
+
+        # Check for specific exit code
+        strategy = ExecWaitStrategy(["custom-healthcheck.sh"], expected_exit_code=0)
+    """
+
+    def __init__(
+        self,
+        command: Union[str, list[str]],
+        expected_exit_code: int = 0,
+    ) -> None:
+        super().__init__()
+        self._command = command if isinstance(command, list) else [command]
+        self._expected_exit_code = expected_exit_code
+
+    def wait_until_ready(self, container: WaitStrategyTarget) -> None:
+        """
+        Wait until command execution succeeds with the expected exit code.
+
+        Args:
+            container: The container to execute commands in
+
+        Raises:
+            TimeoutError: If the command doesn't succeed within the timeout period
+            RuntimeError: If the container doesn't support exec
+        """
+        # Check if container supports exec (DockerContainer does, ComposeContainer doesn't)
+        if not hasattr(container, "exec"):
+            raise RuntimeError(
+                f"ExecWaitStrategy requires a container with exec support. "
+                f"Container type {type(container).__name__} does not support exec."
+            )
+
+        start_time = time.time()
+        last_exit_code = None
+        last_output = None
+
+        while True:
+            duration = time.time() - start_time
+            if duration > self._startup_timeout:
+                command_str = " ".join(self._command)
+                raise TimeoutError(
+                    f"Command execution did not succeed within {self._startup_timeout:.3f} seconds. "
+                    f"Command: {command_str}. "
+                    f"Expected exit code: {self._expected_exit_code}, "
+                    f"last exit code: {last_exit_code}. "
+                    f"Last output: {last_output}. "
+                    f"Hint: Check if the service is starting correctly, the command is valid, "
+                    f"and all required environment variables or credentials are properly configured."
+                )
+
+            try:
+                result = container.exec(self._command)
+                last_exit_code = result.exit_code
+                last_output = result.output.decode() if hasattr(result.output, "decode") else str(result.output)
+
+                if result.exit_code == self._expected_exit_code:
+                    logger.debug(
+                        f"ExecWaitStrategy: Command succeeded with exit code {result.exit_code} after {duration:.2f}s"
+                    )
+                    return
+
+                logger.debug(
+                    f"ExecWaitStrategy: Command failed with exit code {result.exit_code}, "
+                    f"expected {self._expected_exit_code}. Retrying..."
+                )
+            except Exception as e:
+                logger.debug(f"ExecWaitStrategy: Command execution failed with exception: {e}. Retrying...")
+                last_output = str(e)
+
+            time.sleep(self._poll_interval)
+
+
 __all__ = [
     "CompositeWaitStrategy",
     "ContainerStatusWaitStrategy",
+    "ExecWaitStrategy",
     "FileExistsWaitStrategy",
     "HealthcheckWaitStrategy",
     "HttpWaitStrategy",

modules/postgres/testcontainers/postgres/__init__.py

@@ -15,7 +15,7 @@
 
 from testcontainers.core.generic import DbContainer
 from testcontainers.core.utils import raise_for_deprecated_parameter
-from testcontainers.core.waiting_utils import wait_container_is_ready
+from testcontainers.core.wait_strategies import ExecWaitStrategy
 
 _UNSET = object()
 
@@ -87,15 +87,14 @@ def get_connection_url(self, host: Optional[str] = None, driver: Optional[str] =
             port=self.port,
         )
 
-    @wait_container_is_ready()
     def _connect(self) -> None:
+        """Wait for Postgres to be ready by executing a query via psql."""
         escaped_single_password = self.password.replace("'", "'\"'\"'")
-        result = self.exec(
+        strategy = ExecWaitStrategy(
             [
                 "sh",
                 "-c",
                 f"PGPASSWORD='{escaped_single_password}' psql --username {self.username} --dbname {self.dbname} --host 127.0.0.1 -c 'select version();'",
             ]
         )
-        if result.exit_code:
-            raise ConnectionError("pg_isready is not ready yet")
+        strategy.wait_until_ready(self)