continuo-python-runtime 0.10.0__tar.gz → 0.11.0__tar.gz

continuo_python_runtime-0.11.0/.python-version

@@ -0,0 +1 @@
+3.14.8

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/CHANGELOG.md

@@ -5,6 +5,77 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-11-04
+
+**TL;DR**
+
+- A failed python node's log now says why it failed.
+- Every engine adapter waits up to about 10 s for a warehouse that refuses
+  the first connections, as a new Kubernetes pod sees until the cluster's
+  network policy admits it. That used to fail the attempt at once.
+- The trino adapter now connects when it is created, so a wrong Trino
+  password fails at start-up instead of at the first read.
+- Adapter authors: `StartupConformance` is a new conformance class every
+  adapter's integration suite runs.
+
+**Upgrade**
+
+1. Build your domain image `FROM` the `v0.11.0` engine image (or pin
+   `continuo-python-runtime==0.11.0` and your adapter's new version).
+2. Bring-your-own adapter: subclass `StartupConformance` in your integration
+   suite and provide the `warehouse_address` and `adapter_from_env` fixtures.
+
+Versions: runtime 0.11.0, engine contract 0.9.0, postgres adapter 0.3.2,
+trino adapter 0.4.0, duckdb adapter 0.2.2.
+
+### Fixed
+
+- A failed python node's stored log names its failure. The harness logs every
+  runtime error at ERROR on stderr, with the traceback of the exception it
+  wraps, as well as printing it in the result block. Continuo cuts the result
+  block out of the pod log before storing it, so a failure only printed there,
+  such as `LoadError: adapter construction failed: … Connection refused`, was
+  missing from the stored log.
+- Every adapter's `from_env` waits out a warehouse that refuses connections
+  for the first few seconds. A Job pod's first connection can be refused until
+  the cluster's NetworkPolicy engine (k3s's kube-router rejects) has admitted
+  the pod; that cost a task retry and a failed Job. A connection that no server
+  answered (every address refused, had no route or sat on an unreachable
+  network) is tried up to 5 times, 2 s apart, each retry logged. An
+  authentication failure, a timeout on any address and every other failure are
+  raised at once.
+  - postgres: around `psycopg2.connect`.
+  - duckdb: around the catalog attach.
+  - trino: `from_env` now sends `SELECT 1`, since the trino DBAPI opens no
+    connection until the first request. A refusal is retried only if it failed
+    within 5 s: urllib3 reports only the last address it tried, so a slower
+    one hides an address that timed out. A failed authentication now fails
+    `from_env` (a harness `LoadError`) rather than the first read or write.
+
+### Added
+
+- `StartupConformance` in `continuo_engine_contract.testing.conformance`: every
+  adapter's integration suite runs it. It puts the real engine behind a
+  loopback port that refuses connections for 3 s (`LateOpeningPort`), then
+  checks that `from_env` returns an adapter that answers `SELECT 1`. The new
+  fixtures are `warehouse_address` and `adapter_from_env`.
+
+### Changed
+
+- The python-node env contract in `docs/boundary-contract.md` lists
+  `TASK_ATTEMPT`, the 0-based number of the task's attempt, which the executor
+  sets on every production Job. The harness does not read it; a node script
+  may. Documentation only: no package changes.
+- The engine images build on `python:3.14.8-slim` (was `3.14.2`), and
+  `.python-version` and the `template/` Dockerfile follow.
+- `pyarrow` is pinned at `26.0.0` (was `25.0.1`) in the runtime, the engine
+  contract's `testing` extra and the three adapters, so they keep resolving
+  together.
+- Dependency pins move together across the workspace: `ruff` 0.17.1, `mypy`
+  2.4.0, `boto3` 1.43.114, `sqlglot` 30.23.0 (runtime and engine contract),
+  `trino` 0.340.0 and `psycopg2-binary` 2.9.13. `urllib3` moves to 2.8.0 in
+  `uv.lock` (CVE-2026-97687, CVE-2026-97689).
+
 ## [0.10.0] - 2026-10-22
 
 ### Added

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/CLAUDE.md

@@ -28,15 +28,17 @@ merged PRs before adding anything new.
 conformance suite for engine adapter authors. Its dependencies are installed
 with `continuo-engine-contract[testing]`.
 
-- Every adapter MUST satisfy the engine contract and pass the shared
-  conformance classes for every capability it declares: `IntrospectionConformance`
-  for `TableIntrospection`, `AppendConformance` for `AppendCapable`, and
-  `UpsertConformance` for `UpsertCapable`. Append and upsert adapters must also
-  run the introspection class. An adapter need not declare capabilities its
-  engine cannot support.
+- Every adapter MUST satisfy the engine contract and pass `StartupConformance`
+  (`from_env` waits out a warehouse that refuses connections at first) and the
+  shared conformance classes for every capability it declares:
+  `IntrospectionConformance` for `TableIntrospection`, `AppendConformance` for
+  `AppendCapable`, and `UpsertConformance` for `UpsertCapable`. Append and
+  upsert adapters must also run the introspection class. An adapter need not
+  declare capabilities its engine cannot support.
 - Each adapter's integration suite MUST subclass the applicable classes,
-  supply connected `adapter` and temporary `schema` fixtures, and run them
-  against its real warehouse in CI. In-memory reference tests alone do not
+  supply connected `adapter` and temporary `schema` fixtures (and, for
+  `StartupConformance`, `warehouse_address` and `adapter_from_env`), and run
+  them against its real warehouse in CI. In-memory reference tests alone do not
   establish an adapter's conformance. Do not skip or weaken shared checks to
   accommodate an adapter that violates the contract.
 - Every new or changed engine-independent contract requirement, including

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/Dockerfile.duckdb

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-slim
 # One dual-role image per engine: the python-node runtime harness (default
 # command `run`) and the blue/green validation runner (`validation-op`). It
 # installs the PUBLISHED, versioned libraries, never the repo source:

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/Dockerfile.postgres

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-slim
 # One dual-role image per engine — the python-node runtime harness (default
 # command `run`) and the blue/green validation runner (`validation-op`). It
 # installs the PUBLISHED, versioned libraries, never the repo source:

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/Dockerfile.trino

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-slim
 # One dual-role image per engine — the python-node runtime harness (default
 # command `run`) and the blue/green validation runner (`validation-op`). It
 # installs the PUBLISHED, versioned libraries, never the repo source:

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: continuo-python-runtime
-Version: 0.10.0
+Version: 0.11.0
 Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
 Author: Simone Carolini
 Maintainer: Simone Carolini
@@ -11,11 +11,11 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
-Requires-Dist: boto3==1.43.85
-Requires-Dist: continuo-engine-contract==0.8.1
-Requires-Dist: pyarrow==25.0.1
+Requires-Dist: boto3==1.43.114
+Requires-Dist: continuo-engine-contract==0.9.0
+Requires-Dist: pyarrow==26.0.0
 Requires-Dist: pyyaml==6.0.3
-Requires-Dist: sqlglot==30.17.0
+Requires-Dist: sqlglot==30.23.0
 Description-Content-Type: text/markdown
 
 # Continuo Python Runtime
@@ -340,7 +340,10 @@ declared `output_columns` on the table `run()` returned, in this order:
 Every runtime failure is one of five `HarnessError` subclasses
 (`continuo_python_runtime/errors.py`). The sentinel result block's message
 is prefixed `<ErrorClass>: ` so failures can be triaged without parsing free
-text.
+text. The harness also logs the same message at ERROR on stderr, with the
+traceback of the exception it wraps (a driver error, the script's own
+exception), so the stored log of a failed run names its failure: Continuo cuts
+the result block out of the log before storing it.
 
 | Class | Meaning | Typical fix target |
 | --- | --- | --- |
@@ -356,11 +359,11 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.11.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.11.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.11.0
 ```
 
 The engine is part of the image **name**; the tag is the bare version, so

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/README.md

@@ -320,7 +320,10 @@ declared `output_columns` on the table `run()` returned, in this order:
 Every runtime failure is one of five `HarnessError` subclasses
 (`continuo_python_runtime/errors.py`). The sentinel result block's message
 is prefixed `<ErrorClass>: ` so failures can be triaged without parsing free
-text.
+text. The harness also logs the same message at ERROR on stderr, with the
+traceback of the exception it wraps (a driver error, the script's own
+exception), so the stored log of a failed run names its failure: Continuo cuts
+the result block out of the log before storing it.
 
 | Class | Meaning | Typical fix target |
 | --- | --- | --- |
@@ -336,11 +339,11 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.11.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.11.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.10.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.11.0
 ```
 
 The engine is part of the image **name**; the tag is the bare version, so

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/duckdb/README.md

@@ -47,9 +47,18 @@ contains a line break, when `PGPASSWORD` is set in the environment (libpq would
 prefer it to any passfile), or when no temp file can be created. The `aws`
 extension is only loaded for the AWS credential-chain S3 path.
 
-A first attach to a brand-new catalog from several Jobs at once can race on
-DuckLake's metadata creation; the adapter retries exactly that failure a few
-times, and surfaces every other connection error immediately.
+The attach is retried, up to 5 attempts in all, for two failures only:
+
+- a first attach to a brand-new catalog from several Jobs at once can race on
+  DuckLake's metadata creation;
+- a catalog connection that no server answered (every address of the host
+  refused, had no route or sat on an unreachable network) is tried again 2 s
+  later, each retry logged: a Job pod's first connection can be refused for a
+  few seconds after the pod starts, until the cluster's NetworkPolicy engine
+  has admitted the pod.
+
+Every other connection error, an authentication failure or a connect timeout
+on any address among them, surfaces immediately.
 
 ## Physical layout (`config`)
 

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/duckdb/continuo_duckdb_adapter/infrastructure/session.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import contextlib
 import logging
+import re
 import time
 import uuid
 from collections.abc import Callable, Iterator, Sequence
@@ -52,13 +53,30 @@ logger = logging.getLogger("continuo_duckdb_adapter")
 
 CATALOG_ALIAS = "lake"
 
+# An ATTACH is retried on a fresh connection, up to _ATTACH_ATTEMPTS in all, for
+# two failures only; every other failure is raised at once.
+#
 # DuckLake creates its metadata tables on the first ATTACH of a fresh catalog
 # and does not guard that against a concurrent first ATTACH (several Jobs of one
 # run starting together): all but one fail on the duplicate CREATE. The loser
-# retries on a fresh connection and then finds the catalog initialised. Bounded,
-# and only this failure class is retried.
+# retries and then finds the catalog initialised.
+#
+# A Job pod's first connection to the catalog can be refused for a few seconds
+# after the pod starts, until the cluster's NetworkPolicy engine has admitted
+# the pod: an engine that rejects (k3s's kube-router) refuses at once instead
+# of dropping the packets. So a connection no server answered, refused or
+# unroutable, is retried. A connect timeout is not: an engine that drops
+# packets only delays the first connection, which TCP's own retransmissions
+# carry through, so a timeout means the catalog stayed silent for the whole
+# timeout and every retry would wait that long again.
 _ATTACH_ATTEMPTS = 5
 _ATTACH_BACKOFF_SECONDS = 0.2
+_UNREACHABLE_RETRY_SECONDS = 2.0
+# The ATTACH error carries libpq's text for the catalog connection: one line per
+# address it tried, the reason after "failed: " (libpq 14 and later) or after
+# "could not connect to server: " (libpq 13 and earlier).
+_ADDRESS_FAILURE = re.compile(r"(?:failed|could not connect to server): ([^\n]*)")
+_UNREACHABLE_REASONS = frozenset({"Connection refused", "No route to host", "Network is unreachable"})
 
 
 def _is_first_attach_race(exc: duckdb.Error) -> bool:
@@ -68,6 +86,25 @@ def _is_first_attach_race(exc: duckdb.Error) -> bool:
     )
 
 
+def _is_catalog_unreachable(exc: duckdb.Error) -> bool:
+    """Whether *exc* says that every address of the catalog host refused or could not be routed to.
+
+    A host name can have several addresses, and libpq reports each one it
+    tried. One that timed out means a retry would wait out its timeout again;
+    a FATAL line came from a server that answered (a failed authentication, an
+    unknown database). libpq 13 and earlier print a timeout as a bare
+    "timeout expired" line, with no prefix.
+    """
+    message = str(exc)
+    reasons = [reason.strip() for reason in _ADDRESS_FAILURE.findall(message)]
+    return (
+        bool(reasons)
+        and all(reason in _UNREACHABLE_REASONS for reason in reasons)
+        and "FATAL:" not in message
+        and "timeout expired" not in message
+    )
+
+
 def _load_extension(con: "duckdb.DuckDBPyConnection", name: str) -> None:
     try:
         con.execute(load_extension(name))
@@ -135,6 +172,14 @@ class DuckLakeSession(LakeGateway):
                         logger.info("first attach of a fresh catalog raced (attempt %d); retrying", attempt)
                         sleep(_ATTACH_BACKOFF_SECONDS * attempt)
                         continue
+                    if attempt < _ATTACH_ATTEMPTS and _is_catalog_unreachable(exc):
+                        logger.warning(
+                            "catalog not reachable yet (attempt %d of %d), retrying in %.0f s: %s",
+                            attempt, _ATTACH_ATTEMPTS, _UNREACHABLE_RETRY_SECONDS,
+                            _redact(exc, secrets).strip(),
+                        )
+                        sleep(_UNREACHABLE_RETRY_SECONDS)
+                        continue
                     raise _translate(exc, secrets) from None
                 return cls(con, DdlRenderer(CATALOG_ALIAS), secrets=secrets, passfile=passfile)
         except BaseException:

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/duckdb/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-version = "0.2.1"
+version = "0.2.2"
 name = "continuo-duckdb-adapter"
 description = "DuckDB (DuckLake) warehouse adapter for Continuo: validation and python-node runtime."
 authors = [{ name = "Simone Carolini" }]
@@ -10,9 +10,9 @@ dependencies = [
     # Pinned exactly for the same reason as the postgres adapter: the
     # [tool.uv.sources] redirect below is uv-only and never reaches built
     # metadata, and this adapter subclasses the contract's port directly.
-    "continuo-engine-contract==0.8.1",
+    "continuo-engine-contract==0.9.0",
     "duckdb==1.5.6",
-    "pyarrow==25.0.1",
+    "pyarrow==26.0.0",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -25,16 +25,16 @@ duckdb = "continuo_duckdb_adapter.adapter:DuckDBAdapter"
 
 [dependency-groups]
 dev = [
-    "ruff==0.16.5",
-    "mypy==2.3.1",
+    "ruff==0.17.1",
+    "mypy==2.4.0",
 ]
 test = [
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
     # Integration tests read the DuckLake catalog (postgres) and the data
     # files (MinIO) directly to prove layout was really applied.
-    "psycopg2-binary==2.9.12",
-    "boto3==1.43.85",
+    "psycopg2-binary==2.9.13",
+    "boto3==1.43.114",
 ]
 
 [build-system]

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/duckdb/tests/test_infra_duckdb_session.py

@@ -298,12 +298,75 @@ def test_a_persistent_init_race_surfaces_after_bounded_attempts(connect_with):
     assert all(c.closed for c in script.connections)
 
 
+# --- a catalog the pod cannot reach yet --------------------------------------
+#
+# A Job pod's first connection can be refused for a few seconds after the pod
+# starts, while the cluster's NetworkPolicy engine has not yet admitted it. The
+# ATTACH reports libpq's text for the catalog connection; these are DuckDB's
+# messages as it prints them.
+
+
+def _catalog_unreachable(reason: str) -> duckdb.IOException:
+    conninfo = "host=catalog port=5432 dbname=catalog user=continuo"
+    return duckdb.IOException(
+        f'IO Error: Failed to attach DuckLake MetaData "__ducklake_metadata_lake" at path + '
+        f'"postgres:{conninfo}"Unable to connect to Postgres at "{conninfo}": connection to '
+        f'server at "catalog" (10.43.0.7), port 5432 failed: {reason}\n'
+    )
+
+
+REFUSED = "Connection refused\n\tIs the server running on that host and accepting TCP/IP connections?"
+
+
+@pytest.mark.parametrize("reason", [
+    REFUSED, "No route to host", "Network is unreachable",
+    f'{REFUSED}\nconnection to server at "catalog" (10.43.0.8), port 5432 failed: {REFUSED}',
+], ids=["refused", "no-route", "net-unreachable", "refused-twice"])
+def test_an_unreachable_catalog_is_retried_on_a_fresh_connection(connect_with, reason):
+    script, sleeps, connect = connect_with([_catalog_unreachable(reason)] * 2 + [None])
+    session = connect()
+    assert len(script.connections) == 3
+    assert [c.closed for c in script.connections] == [True, True, False]
+    assert sleeps == [2.0, 2.0]
+    session.close()
+
+
+def test_a_catalog_that_stays_unreachable_fails_after_bounded_attempts(connect_with):
+    from continuo_duckdb_adapter.infrastructure import session as session_module
+
+    script, sleeps, connect = connect_with([_catalog_unreachable(REFUSED)] * 50)
+    with pytest.raises(duckdb.IOException, match="Connection refused"):
+        connect()
+    assert len(script.connections) == session_module._ATTACH_ATTEMPTS == 5
+    assert sleeps == [2.0, 2.0, 2.0, 2.0]
+    assert all(c.closed for c in script.connections)
+
+
+def test_each_catalog_retry_is_logged_redacted(connect_with, caplog):
+    leaking = duckdb.IOException(f"{_catalog_unreachable(REFUSED)} password={PASSWORD}")
+    _, _, connect = connect_with([leaking, leaking, None])
+    caplog.set_level(logging.INFO, logger="continuo_duckdb_adapter")
+    connect().close()
+    warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+    assert len(warnings) == 2
+    assert all("port 5432 failed: Connection refused" in r.getMessage() for r in warnings)
+    assert PASSWORD not in caplog.text
+
+
+# A catalog host with two addresses, one refused and one silent: the ATTACH
+# error carries both of libpq's lines.
+REFUSED_THEN_TIMED_OUT = (
+    f'{REFUSED}\nconnection to server at "catalog" (10.43.0.8), port 5432 failed: timeout expired'
+)
+
+
 @pytest.mark.parametrize("error", [
-    duckdb.IOException('Unable to connect to Postgres at "host=h": Connection refused'),
-    duckdb.IOException('Failed to attach DuckLake: FATAL:  password authentication failed'),
+    _catalog_unreachable('FATAL:  password authentication failed for user "continuo"'),
+    _catalog_unreachable("timeout expired"),
+    _catalog_unreachable(REFUSED_THEN_TIMED_OUT),
     duckdb.Error("Failed to initialize DuckLake: disk full"),
     duckdb.CatalogException("something else"),
-])
+], ids=["auth-failed", "timed-out", "refused-then-timed-out", "init-failed", "catalog-error"])
 def test_every_other_attach_error_is_not_retried(connect_with, error):
     script, sleeps, connect = connect_with([error])
     with pytest.raises(type(error)):

continuo_python_runtime-0.11.0/adapters/duckdb/tests/test_integration_duckdb_conformance.py

@@ -0,0 +1,51 @@
+"""The engine-contract conformance suite against a real DuckLake (tests/smoke/duckdb-stack).
+
+The `adapter`, `schema` and `lake_env` fixtures come from this directory's
+conftest.py. The first connection ``from_env`` opens is the catalog's, so the
+startup case puts the catalog behind the refusing port.
+Run the stack first:
+    docker compose -f tests/smoke/duckdb-stack/docker-compose.yml up -d --wait
+"""
+import pytest
+
+from continuo_engine_contract.testing.conformance import (
+    AppendConformance,
+    IntrospectionConformance,
+    StartupConformance,
+    UpsertConformance,
+)
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+def warehouse_address(lake_env):
+    return "127.0.0.1", int(lake_env["DUCKDB_CATALOG_PORT"])
+
+
+@pytest.fixture
+def adapter_from_env(lake_env, monkeypatch):
+    from continuo_duckdb_adapter.adapter import DuckDBAdapter
+
+    def build(host, port):
+        for key, value in {**lake_env, "DUCKDB_CATALOG_HOST": host, "DUCKDB_CATALOG_PORT": str(port)}.items():
+            monkeypatch.setenv(key, value)
+        return DuckDBAdapter.from_env()
+
+    return build
+
+
+class TestDuckDBStartup(StartupConformance):
+    pass
+
+
+class TestDuckDBIntrospection(IntrospectionConformance):
+    pass
+
+
+class TestDuckDBAppend(AppendConformance):
+    pass
+
+
+class TestDuckDBUpsert(UpsertConformance):
+    pass

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/duckdb/tests/test_integration_duckdb_stack.py

@@ -20,14 +20,26 @@ def test_ensure_schema_creates_a_schema_visible_to_another_connection(adapter, a
     assert other.fetch(f'SELECT count(*) AS n FROM "{schema}"."t"').to_pylist() == [{"n": 0}]
 
 
-def test_unreachable_catalog_raises_a_clear_error(adapter_factory):
-    with pytest.raises(duckdb.Error):
-        adapter_factory(DUCKDB_CATALOG_PORT="1")
+def _connect(lake_env, sleeps, **overrides):
+    """DuckDBAdapter.from_env's session, with its retry waits recorded instead of slept."""
+    from continuo_duckdb_adapter.infrastructure.session import DuckLakeSession
+    from continuo_duckdb_adapter.infrastructure.settings import DuckLakeSettings
+
+    return DuckLakeSession.connect(DuckLakeSettings.from_env({**lake_env, **overrides}), sleep=sleeps.append)
+
+
+def test_unreachable_catalog_is_retried_then_raises_a_clear_error(lake_env):
+    sleeps: list[float] = []
+    with pytest.raises(duckdb.Error, match="Connection refused"):
+        _connect(lake_env, sleeps, DUCKDB_CATALOG_PORT="1")
+    assert sleeps == [2.0, 2.0, 2.0, 2.0]
 
 
-def test_wrong_catalog_password_raises_a_clear_error(adapter_factory):
-    with pytest.raises(duckdb.Error):
-        adapter_factory(DUCKDB_CATALOG_PASSWORD="definitely-wrong")
+def test_wrong_catalog_password_raises_a_clear_error_at_once(lake_env):
+    sleeps: list[float] = []
+    with pytest.raises(duckdb.Error, match="password authentication failed"):
+        _connect(lake_env, sleeps, DUCKDB_CATALOG_PASSWORD="definitely-wrong")
+    assert sleeps == []
 
 
 def test_failed_attach_does_not_echo_the_password(adapter_factory):

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/postgres/README.md

@@ -12,6 +12,13 @@ registers itself under entry-point group `continuo_engine.adapters` as
 Connection env: `POSTGRES_HOST`, `POSTGRES_DB`, `POSTGRES_USER` (required);
 `POSTGRES_PORT` (default 5432), `POSTGRES_PASSWORD` (default empty).
 
+`from_env` tries a connection that no server answered (every address of the
+host refused, had no route or sat on an unreachable network) up to 5 times,
+2 s apart, logging each retry: a Job pod's first connection can be refused
+for a few seconds after the pod starts, until the cluster's NetworkPolicy
+engine has admitted the pod. Every other failure, an authentication failure or
+a connect timeout on any address among them, is raised at once.
+
 The connection runs with `autocommit = True`; every method owns its
 transaction explicitly. `load()` and `ensure_table()` open an explicit
 `BEGIN` around their statements and `COMMIT`/`ROLLBACK` themselves, so a

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.11.0}/adapters/postgres/continuo_postgres_adapter/adapter.py

@@ -28,8 +28,10 @@ import contextlib
 import hashlib
 import logging
 import os
+import re
+import time
 
-from collections.abc import Iterator, Sequence
+from collections.abc import Callable, Iterator, Sequence
 from typing import Any
 
 import psycopg2  # type: ignore[import-untyped]
@@ -79,6 +81,42 @@ _DEFAULT_INDEX_TYPE = "btree"
 # postgres actually stores.
 _MAX_IDENTIFIER_BYTES = 63
 
+# A Job pod's first connection can be refused for a few seconds after the pod
+# starts, until the cluster's NetworkPolicy engine has admitted the pod: an
+# engine that rejects (k3s's kube-router) refuses at once instead of dropping
+# the packets. So a connection the server never answered, refused or
+# unroutable, is tried again. A connect timeout is not: an engine that drops
+# packets only delays the first connection, which TCP's own retransmissions
+# carry through, so a timeout means the server stayed silent for the whole
+# timeout and every retry would wait that long again.
+_CONNECT_ATTEMPTS = 5
+_CONNECT_RETRY_SECONDS = 2.0
+# libpq writes one line per address it tried, the reason after "failed: "
+# (libpq 14 and later) or after "could not connect to server: " (libpq 13 and
+# earlier); pgcode is None for every connection failure, so the text is all
+# there is.
+_ADDRESS_FAILURE = re.compile(r"(?:failed|could not connect to server): ([^\n]*)")
+_UNREACHABLE_REASONS = frozenset({"Connection refused", "No route to host", "Network is unreachable"})
+
+
+def _is_unreachable(exc: "psycopg2.OperationalError") -> bool:
+    """Whether *exc* says that every address of the host refused or could not be routed to.
+
+    A host name can have several addresses, and libpq reports each one it
+    tried. One that timed out means a retry would wait out its timeout again;
+    a FATAL line came from a server that answered (a failed authentication, an
+    unknown database). libpq 13 and earlier print a timeout as a bare
+    "timeout expired" line, with no prefix.
+    """
+    message = str(exc)
+    reasons = [reason.strip() for reason in _ADDRESS_FAILURE.findall(message)]
+    return (
+        bool(reasons)
+        and all(reason in _UNREACHABLE_REASONS for reason in reasons)
+        and "FATAL:" not in message
+        and "timeout expired" not in message
+    )
+
 
 def _truncate_explicit_identifier(name: str) -> str:
     """Truncate an explicit, author-given identifier to at most 63 bytes.
@@ -418,16 +456,35 @@ class PostgresAdapter(WarehouseAdapter, AppendCapable, UpsertCapable):
         return ["POSTGRES_HOST", "POSTGRES_DB", "POSTGRES_USER"]
 
     @classmethod
-    def from_env(cls) -> "PostgresAdapter":
-        """Connect from POSTGRES_* env (port defaults 5432, password empty)."""
-        conn = psycopg2.connect(
-            host=os.environ["POSTGRES_HOST"],
-            port=os.environ.get("POSTGRES_PORT", "5432"),
-            dbname=os.environ["POSTGRES_DB"],
-            user=os.environ["POSTGRES_USER"],
-            password=os.environ.get("POSTGRES_PASSWORD", ""),
-        )
-        return cls(conn)
+    def from_env(cls, *, sleep: Callable[[float], None] = time.sleep) -> "PostgresAdapter":
+        """Connect from POSTGRES_* env (port defaults 5432, password empty).
+
+        A connection no server answered (refused, no route, network
+        unreachable) is tried again, up to ``_CONNECT_ATTEMPTS`` times in all,
+        ``_CONNECT_RETRY_SECONDS`` apart, each retry logged; the last failure
+        is raised. Every other failure is raised at once.
+        """
+        params = {
+            "host": os.environ["POSTGRES_HOST"],
+            "port": os.environ.get("POSTGRES_PORT", "5432"),
+            "dbname": os.environ["POSTGRES_DB"],
+            "user": os.environ["POSTGRES_USER"],
+            "password": os.environ.get("POSTGRES_PASSWORD", ""),
+        }
+        for attempt in range(1, _CONNECT_ATTEMPTS + 1):
+            try:
+                conn = psycopg2.connect(**params)
+            except psycopg2.OperationalError as exc:
+                if attempt == _CONNECT_ATTEMPTS or not _is_unreachable(exc):
+                    raise
+                logger.warning(
+                    "postgres not reachable yet (attempt %d of %d), retrying in %.0f s: %s",
+                    attempt, _CONNECT_ATTEMPTS, _CONNECT_RETRY_SECONDS, str(exc).strip(),
+                )
+                sleep(_CONNECT_RETRY_SECONDS)
+                continue
+            return cls(conn)
+        raise AssertionError("unreachable")  # pragma: no cover
 
     # --- Schema lifecycle ---------------------------------------------------