dbos 0.20.0a8__tar.gz → 0.21.0__tar.gz

{dbos-0.20.0a8 → dbos-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dbos
-Version: 0.20.0a8
+Version: 0.21.0
 Summary: Ultra-lightweight durable execution in Python
 Author-Email: "DBOS, Inc." <contact@dbos.dev>
 License: MIT

{dbos-0.20.0a8 → dbos-0.21.0}/dbos/_context.py

@@ -63,7 +63,6 @@ class DBOSContext:
         self.parent_workflow_fid: int = -1
         self.workflow_id: str = ""
         self.function_id: int = -1
-        self.in_recovery: bool = False
 
         self.curr_step_function_id: int = -1
         self.curr_tx_function_id: int = -1
@@ -82,7 +81,6 @@ class DBOSContext:
         rv.is_within_set_workflow_id_block = self.is_within_set_workflow_id_block
         rv.parent_workflow_id = self.workflow_id
         rv.parent_workflow_fid = self.function_id
-        rv.in_recovery = self.in_recovery
         rv.authenticated_user = self.authenticated_user
         rv.authenticated_roles = (
             self.authenticated_roles[:]
@@ -335,34 +333,6 @@ class SetWorkflowID:
         return False  # Did not handle
 
 
-class SetWorkflowRecovery:
-    def __init__(self) -> None:
-        self.created_ctx = False
-
-    def __enter__(self) -> SetWorkflowRecovery:
-        # Code to create a basic context
-        ctx = get_local_dbos_context()
-        if ctx is None:
-            self.created_ctx = True
-            _set_local_dbos_context(DBOSContext())
-        assert_current_dbos_context().in_recovery = True
-
-        return self
-
-    def __exit__(
-        self,
-        exc_type: Optional[Type[BaseException]],
-        exc_value: Optional[BaseException],
-        traceback: Optional[TracebackType],
-    ) -> Literal[False]:
-        assert assert_current_dbos_context().in_recovery == True
-        assert_current_dbos_context().in_recovery = False
-        # Code to clean up the basic context if we created it
-        if self.created_ctx:
-            _clear_local_dbos_context()
-        return False  # Did not handle
-
-
 class EnterDBOSWorkflow(AbstractContextManager[DBOSContext, Literal[False]]):
     def __init__(self, attributes: TracedAttributes) -> None:
         self.created_ctx = False

{dbos-0.20.0a8 → dbos-0.21.0}/dbos/_core.py

@@ -185,8 +185,8 @@ def _init_workflow(
         # Synchronously record the status and inputs for workflows and single-step workflows
         # We also have to do this for single-step workflows because of the foreign key constraint on the operation outputs table
         # TODO: Make this transactional (and with the queue step below)
-        wf_status = dbos._sys_db.update_workflow_status(
-            status, False, ctx.in_recovery, max_recovery_attempts=max_recovery_attempts
+        wf_status = dbos._sys_db.insert_workflow_status(
+            status, max_recovery_attempts=max_recovery_attempts
         )
         # TODO: Modify the inputs if they were changed by `update_workflow_inputs`
         dbos._sys_db.update_workflow_inputs(wfid, _serialization.serialize_args(inputs))

{dbos-0.20.0a8 → dbos-0.21.0}/dbos/_dbos.py

@@ -56,7 +56,7 @@ from ._registrations import (
 )
 from ._roles import default_required_roles, required_roles
 from ._scheduler import ScheduledWorkflow, scheduled
-from ._sys_db import WorkflowStatusString, reset_system_database
+from ._sys_db import reset_system_database
 from ._tracer import dbos_tracer
 
 if TYPE_CHECKING:
@@ -613,6 +613,7 @@ class DBOS:
             workflow_id=workflow_id,
             status=stat["status"],
             name=stat["name"],
+            executor_id=stat["executor_id"],
             recovery_attempts=stat["recovery_attempts"],
             class_name=stat["class_name"],
             config_name=stat["config_name"],
@@ -800,14 +801,13 @@ class DBOS:
     @classmethod
     def cancel_workflow(cls, workflow_id: str) -> None:
         """Cancel a workflow by ID."""
-        _get_dbos_instance()._sys_db.set_workflow_status(
-            workflow_id, WorkflowStatusString.CANCELLED, False
-        )
+        _get_dbos_instance()._sys_db.cancel_workflow(workflow_id)
 
     @classmethod
-    def resume_workflow(cls, workflow_id: str) -> None:
+    def resume_workflow(cls, workflow_id: str) -> WorkflowHandle[Any]:
         """Resume a workflow by ID."""
-        execute_workflow_by_id(_get_dbos_instance(), workflow_id, False)
+        _get_dbos_instance()._sys_db.resume_workflow(workflow_id)
+        return execute_workflow_by_id(_get_dbos_instance(), workflow_id, False)
 
     @classproperty
     def logger(cls) -> Logger:
@@ -910,6 +910,7 @@ class WorkflowStatus:
         workflow_id(str):  The ID of the workflow execution
         status(str):  The status of the execution, from `WorkflowStatusString`
         name(str): The workflow function name
+        executor_id(str): The ID of the executor running the workflow
         class_name(str): For member functions, the name of the class containing the workflow function
         config_name(str): For instance member functions, the name of the class instance for the execution
         queue_name(str): For workflows that are or were queued, the queue name
@@ -923,6 +924,7 @@ class WorkflowStatus:
     workflow_id: str
     status: str
     name: str
+    executor_id: Optional[str]
     class_name: Optional[str]
     config_name: Optional[str]
     queue_name: Optional[str]

{dbos-0.20.0a8 → dbos-0.21.0}/dbos/_dbos_config.py

@@ -123,7 +123,10 @@ def get_dbos_database_url(config_file_path: str = DBOS_CONFIG_PATH) -> str:
 
 
 def load_config(
-    config_file_path: str = DBOS_CONFIG_PATH, *, use_db_wizard: bool = True
+    config_file_path: str = DBOS_CONFIG_PATH,
+    *,
+    use_db_wizard: bool = True,
+    silent: bool = False,
 ) -> ConfigFile:
     """
     Load the DBOS `ConfigFile` from the specified path (typically `dbos-config.yaml`).
@@ -188,18 +191,19 @@ def load_config(
     # Load the DB connection file. Use its values for missing fields from dbos-config.yaml. Use defaults otherwise.
     data = cast(ConfigFile, data)
     db_connection = load_db_connection()
-    if data["database"].get("hostname"):
-        print(
-            "[bold blue]Loading database connection parameters from dbos-config.yaml[/bold blue]"
-        )
-    elif db_connection.get("hostname"):
-        print(
-            "[bold blue]Loading database connection parameters from .dbos/db_connection[/bold blue]"
-        )
-    else:
-        print(
-            "[bold blue]Using default database connection parameters (localhost)[/bold blue]"
-        )
+    if not silent:
+        if data["database"].get("hostname"):
+            print(
+                "[bold blue]Loading database connection parameters from dbos-config.yaml[/bold blue]"
+            )
+        elif db_connection.get("hostname"):
+            print(
+                "[bold blue]Loading database connection parameters from .dbos/db_connection[/bold blue]"
+            )
+        else:
+            print(
+                "[bold blue]Using default database connection parameters (localhost)[/bold blue]"
+            )
 
     data["database"]["hostname"] = (
         data["database"].get("hostname") or db_connection.get("hostname") or "localhost"

dbos-0.21.0/dbos/_recovery.py

@@ -0,0 +1,70 @@
+import os
+import threading
+import time
+import traceback
+from typing import TYPE_CHECKING, Any, List
+
+from ._core import execute_workflow_by_id
+from ._error import DBOSWorkflowFunctionNotFoundError
+from ._sys_db import GetPendingWorkflowsOutput
+
+if TYPE_CHECKING:
+    from ._dbos import DBOS, WorkflowHandle
+
+
+def startup_recovery_thread(
+    dbos: "DBOS", pending_workflows: List[GetPendingWorkflowsOutput]
+) -> None:
+    """Attempt to recover local pending workflows on startup using a background thread."""
+    stop_event = threading.Event()
+    dbos.stop_events.append(stop_event)
+    while not stop_event.is_set() and len(pending_workflows) > 0:
+        try:
+            for pending_workflow in list(pending_workflows):
+                if (
+                    pending_workflow.queue_name
+                    and pending_workflow.queue_name != "_dbos_internal_queue"
+                ):
+                    dbos._sys_db.clear_queue_assignment(pending_workflow.workflow_uuid)
+                    continue
+                execute_workflow_by_id(dbos, pending_workflow.workflow_uuid)
+                pending_workflows.remove(pending_workflow)
+        except DBOSWorkflowFunctionNotFoundError:
+            time.sleep(1)
+        except Exception as e:
+            dbos.logger.error(
+                f"Exception encountered when recovering workflows: {traceback.format_exc()}"
+            )
+            raise e
+
+
+def recover_pending_workflows(
+    dbos: "DBOS", executor_ids: List[str] = ["local"]
+) -> List["WorkflowHandle[Any]"]:
+    workflow_handles: List["WorkflowHandle[Any]"] = []
+    for executor_id in executor_ids:
+        if executor_id == "local" and os.environ.get("DBOS__VMID"):
+            dbos.logger.debug(
+                f"Skip local recovery because it's running in a VM: {os.environ.get('DBOS__VMID')}"
+            )
+        dbos.logger.debug(f"Recovering pending workflows for executor: {executor_id}")
+        pending_workflows = dbos._sys_db.get_pending_workflows(executor_id)
+        for pending_workflow in pending_workflows:
+            if (
+                pending_workflow.queue_name
+                and pending_workflow.queue_name != "_dbos_internal_queue"
+            ):
+                try:
+                    dbos._sys_db.clear_queue_assignment(pending_workflow.workflow_uuid)
+                    workflow_handles.append(
+                        dbos.retrieve_workflow(pending_workflow.workflow_uuid)
+                    )
+                except Exception as e:
+                    dbos.logger.error(e)
+            else:
+                workflow_handles.append(
+                    execute_workflow_by_id(dbos, pending_workflow.workflow_uuid)
+                )
+
+    dbos.logger.info("Recovered pending workflows")
+    return workflow_handles

{dbos-0.20.0a8 → dbos-0.21.0}/dbos/_sys_db.py

@@ -126,11 +126,26 @@ class GetWorkflowsInput:
         )
 
 
+class GetQueuedWorkflowsInput(TypedDict):
+    queue_name: Optional[str]
+    status: Optional[str]
+    start_time: Optional[str]  # Timestamp in ISO 8601 format
+    end_time: Optional[str]  # Timestamp in ISO 8601 format
+    limit: Optional[int]  # Return up to this many workflows IDs.
+    name: Optional[str]  # The name of the workflow function
+
+
 class GetWorkflowsOutput:
     def __init__(self, workflow_uuids: List[str]):
         self.workflow_uuids = workflow_uuids
 
 
+class GetPendingWorkflowsOutput:
+    def __init__(self, *, workflow_uuid: str, queue_name: Optional[str] = None):
+        self.workflow_uuid: str = workflow_uuid
+        self.queue_name: Optional[str] = queue_name
+
+
 class WorkflowInformation(TypedDict, total=False):
     workflow_uuid: str
     status: WorkflowStatuses  # The status of the workflow.
@@ -243,66 +258,50 @@ class SystemDatabase:
             dbos_logger.debug("Waiting for system buffers to be exported")
             time.sleep(1)
 
-    def update_workflow_status(
+    def insert_workflow_status(
         self,
         status: WorkflowStatusInternal,
-        replace: bool = True,
-        in_recovery: bool = False,
         *,
-        conn: Optional[sa.Connection] = None,
         max_recovery_attempts: int = DEFAULT_MAX_RECOVERY_ATTEMPTS,
     ) -> WorkflowStatuses:
         wf_status: WorkflowStatuses = status["status"]
 
-        cmd = pg.insert(SystemSchema.workflow_status).values(
-            workflow_uuid=status["workflow_uuid"],
-            status=status["status"],
-            name=status["name"],
-            class_name=status["class_name"],
-            config_name=status["config_name"],
-            output=status["output"],
-            error=status["error"],
-            executor_id=status["executor_id"],
-            application_version=status["app_version"],
-            application_id=status["app_id"],
-            request=status["request"],
-            authenticated_user=status["authenticated_user"],
-            authenticated_roles=status["authenticated_roles"],
-            assumed_role=status["assumed_role"],
-            queue_name=status["queue_name"],
-        )
-        if replace:
-            cmd = cmd.on_conflict_do_update(
-                index_elements=["workflow_uuid"],
-                set_=dict(
-                    status=status["status"],
-                    output=status["output"],
-                    error=status["error"],
-                ),
-            )
-        elif in_recovery:
-            cmd = cmd.on_conflict_do_update(
-                index_elements=["workflow_uuid"],
-                set_=dict(
-                    recovery_attempts=SystemSchema.workflow_status.c.recovery_attempts
-                    + 1,
+        cmd = (
+            pg.insert(SystemSchema.workflow_status)
+            .values(
+                workflow_uuid=status["workflow_uuid"],
+                status=status["status"],
+                name=status["name"],
+                class_name=status["class_name"],
+                config_name=status["config_name"],
+                output=status["output"],
+                error=status["error"],
+                executor_id=status["executor_id"],
+                application_version=status["app_version"],
+                application_id=status["app_id"],
+                request=status["request"],
+                authenticated_user=status["authenticated_user"],
+                authenticated_roles=status["authenticated_roles"],
+                assumed_role=status["assumed_role"],
+                queue_name=status["queue_name"],
+                recovery_attempts=(
+                    1 if wf_status != WorkflowStatusString.ENQUEUED.value else 0
                 ),
             )
-        else:
-            # A blank update so that we can return the existing status
-            cmd = cmd.on_conflict_do_update(
+            .on_conflict_do_update(
                 index_elements=["workflow_uuid"],
                 set_=dict(
-                    recovery_attempts=SystemSchema.workflow_status.c.recovery_attempts
+                    recovery_attempts=(
+                        SystemSchema.workflow_status.c.recovery_attempts + 1
+                    ),
                 ),
             )
+        )
+
         cmd = cmd.returning(SystemSchema.workflow_status.c.recovery_attempts, SystemSchema.workflow_status.c.status, SystemSchema.workflow_status.c.name, SystemSchema.workflow_status.c.class_name, SystemSchema.workflow_status.c.config_name, SystemSchema.workflow_status.c.queue_name)  # type: ignore
 
-        if conn is not None:
-            results = conn.execute(cmd)
-        else:
-            with self.engine.begin() as c:
-                results = c.execute(cmd)
+        with self.engine.begin() as c:
+            results = c.execute(cmd)
 
         row = results.fetchone()
         if row is not None:
@@ -325,7 +324,9 @@ class SystemDatabase:
             if err_msg is not None:
                 raise DBOSConflictingWorkflowError(status["workflow_uuid"], err_msg)
 
-            if in_recovery and recovery_attempts > max_recovery_attempts:
+            # Every time we start executing a workflow (and thus attempt to insert its status), we increment `recovery_attempts` by 1.
+            # When this number becomes equal to `maxRetries + 1`, we mark the workflow as `RETRIES_EXCEEDED`.
+            if recovery_attempts > max_recovery_attempts + 1:
                 with self.engine.begin() as c:
                     c.execute(
                         sa.delete(SystemSchema.workflow_queue).where(
@@ -352,38 +353,107 @@ class SystemDatabase:
                     status["workflow_uuid"], max_recovery_attempts
                 )
 
-        # Record we have exported status for this single-transaction workflow
+        return wf_status
+
+    def update_workflow_status(
+        self,
+        status: WorkflowStatusInternal,
+        *,
+        conn: Optional[sa.Connection] = None,
+    ) -> None:
+        wf_status: WorkflowStatuses = status["status"]
+
+        cmd = (
+            pg.insert(SystemSchema.workflow_status)
+            .values(
+                workflow_uuid=status["workflow_uuid"],
+                status=status["status"],
+                name=status["name"],
+                class_name=status["class_name"],
+                config_name=status["config_name"],
+                output=status["output"],
+                error=status["error"],
+                executor_id=status["executor_id"],
+                application_version=status["app_version"],
+                application_id=status["app_id"],
+                request=status["request"],
+                authenticated_user=status["authenticated_user"],
+                authenticated_roles=status["authenticated_roles"],
+                assumed_role=status["assumed_role"],
+                queue_name=status["queue_name"],
+                recovery_attempts=(
+                    1 if wf_status != WorkflowStatusString.ENQUEUED.value else 0
+                ),
+            )
+            .on_conflict_do_update(
+                index_elements=["workflow_uuid"],
+                set_=dict(
+                    status=status["status"],
+                    output=status["output"],
+                    error=status["error"],
+                ),
+            )
+        )
+
+        if conn is not None:
+            conn.execute(cmd)
+        else:
+            with self.engine.begin() as c:
+                c.execute(cmd)
+
+        # If this is a single-transaction workflow, record that its status has been exported
         if status["workflow_uuid"] in self._temp_txn_wf_ids:
             self._exported_temp_txn_wf_status.add(status["workflow_uuid"])
 
-        return wf_status
-
-    def set_workflow_status(
+    def cancel_workflow(
         self,
-        workflow_uuid: str,
-        status: WorkflowStatusString,
-        reset_recovery_attempts: bool,
+        workflow_id: str,
     ) -> None:
         with self.engine.begin() as c:
-            stmt = (
+            # Remove the workflow from the queues table so it does not block the table
+            c.execute(
+                sa.delete(SystemSchema.workflow_queue).where(
+                    SystemSchema.workflow_queue.c.workflow_uuid == workflow_id
+                )
+            )
+            # Set the workflow's status to CANCELLED
+            c.execute(
                 sa.update(SystemSchema.workflow_status)
-                .where(SystemSchema.workflow_status.c.workflow_uuid == workflow_uuid)
+                .where(SystemSchema.workflow_status.c.workflow_uuid == workflow_id)
                 .values(
-                    status=status,
+                    status=WorkflowStatusString.CANCELLED.value,
                 )
             )
-            c.execute(stmt)
 
-        if reset_recovery_attempts:
-            with self.engine.begin() as c:
-                stmt = (
-                    sa.update(SystemSchema.workflow_status)
-                    .where(
-                        SystemSchema.workflow_status.c.workflow_uuid == workflow_uuid
-                    )
-                    .values(recovery_attempts=reset_recovery_attempts)
+    def resume_workflow(
+        self,
+        workflow_id: str,
+    ) -> None:
+        with self.engine.begin() as c:
+            # Check the status of the workflow. If it is complete, do nothing.
+            row = c.execute(
+                sa.select(
+                    SystemSchema.workflow_status.c.status,
+                ).where(SystemSchema.workflow_status.c.workflow_uuid == workflow_id)
+            ).fetchone()
+            if (
+                row is None
+                or row[0] == WorkflowStatusString.SUCCESS.value
+                or row[0] == WorkflowStatusString.ERROR.value
+            ):
+                return
+            # Remove the workflow from the queues table so resume can safely be called on an ENQUEUED workflow
+            c.execute(
+                sa.delete(SystemSchema.workflow_queue).where(
+                    SystemSchema.workflow_queue.c.workflow_uuid == workflow_id
                 )
-                c.execute(stmt)
+            )
+            # Set the workflow's status to PENDING and clear its recovery attempts.
+            c.execute(
+                sa.update(SystemSchema.workflow_status)
+                .where(SystemSchema.workflow_status.c.workflow_uuid == workflow_id)
+                .values(status=WorkflowStatusString.PENDING.value, recovery_attempts=0)
+            )
 
     def get_workflow_status(
         self, workflow_uuid: str
@@ -401,6 +471,7 @@ class SystemDatabase:
                     SystemSchema.workflow_status.c.authenticated_roles,
                     SystemSchema.workflow_status.c.assumed_role,
                     SystemSchema.workflow_status.c.queue_name,
+                    SystemSchema.workflow_status.c.executor_id,
                 ).where(SystemSchema.workflow_status.c.workflow_uuid == workflow_uuid)
             ).fetchone()
             if row is None:
@@ -415,7 +486,7 @@ class SystemDatabase:
                 "error": None,
                 "app_id": None,
                 "app_version": None,
-                "executor_id": None,
+                "executor_id": row[10],
                 "request": row[2],
                 "recovery_attempts": row[3],
                 "authenticated_user": row[6],
@@ -601,9 +672,8 @@ class SystemDatabase:
 
     def get_workflows(self, input: GetWorkflowsInput) -> GetWorkflowsOutput:
         query = sa.select(SystemSchema.workflow_status.c.workflow_uuid).order_by(
-            SystemSchema.workflow_status.c.created_at.desc()
+            SystemSchema.workflow_status.c.created_at.asc()
         )
-
         if input.name:
             query = query.where(SystemSchema.workflow_status.c.name == input.name)
         if input.authenticated_user:
@@ -637,16 +707,73 @@ class SystemDatabase:
 
         return GetWorkflowsOutput(workflow_uuids)
 
-    def get_pending_workflows(self, executor_id: str) -> list[str]:
+    def get_queued_workflows(
+        self, input: GetQueuedWorkflowsInput
+    ) -> GetWorkflowsOutput:
+
+        query = (
+            sa.select(SystemSchema.workflow_queue.c.workflow_uuid)
+            .join(
+                SystemSchema.workflow_status,
+                SystemSchema.workflow_queue.c.workflow_uuid
+                == SystemSchema.workflow_status.c.workflow_uuid,
+            )
+            .order_by(SystemSchema.workflow_status.c.created_at.asc())
+        )
+
+        if input.get("name"):
+            query = query.where(SystemSchema.workflow_status.c.name == input["name"])
+
+        if input.get("queue_name"):
+            query = query.where(
+                SystemSchema.workflow_queue.c.queue_name == input["queue_name"]
+            )
+
+        if input.get("status"):
+            query = query.where(
+                SystemSchema.workflow_status.c.status == input["status"]
+            )
+        if "start_time" in input and input["start_time"] is not None:
+            query = query.where(
+                SystemSchema.workflow_status.c.created_at
+                >= datetime.datetime.fromisoformat(input["start_time"]).timestamp()
+                * 1000
+            )
+        if "end_time" in input and input["end_time"] is not None:
+            query = query.where(
+                SystemSchema.workflow_status.c.created_at
+                <= datetime.datetime.fromisoformat(input["end_time"]).timestamp() * 1000
+            )
+        if input.get("limit"):
+            query = query.limit(input["limit"])
+
+        with self.engine.begin() as c:
+            rows = c.execute(query)
+        workflow_uuids = [row[0] for row in rows]
+
+        return GetWorkflowsOutput(workflow_uuids)
+
+    def get_pending_workflows(
+        self, executor_id: str
+    ) -> list[GetPendingWorkflowsOutput]:
         with self.engine.begin() as c:
             rows = c.execute(
-                sa.select(SystemSchema.workflow_status.c.workflow_uuid).where(
+                sa.select(
+                    SystemSchema.workflow_status.c.workflow_uuid,
+                    SystemSchema.workflow_status.c.queue_name,
+                ).where(
                     SystemSchema.workflow_status.c.status
                     == WorkflowStatusString.PENDING.value,
                     SystemSchema.workflow_status.c.executor_id == executor_id,
                 )
             ).fetchall()
-            return [row[0] for row in rows]
+            return [
+                GetPendingWorkflowsOutput(
+                    workflow_uuid=row.workflow_uuid,
+                    queue_name=row.queue_name,
+                )
+                for row in rows
+            ]
 
     def record_operation_result(
         self, result: OperationResultInternal, conn: Optional[sa.Connection] = None
@@ -1266,6 +1393,19 @@ class SystemDatabase:
                     .values(completed_at_epoch_ms=int(time.time() * 1000))
                 )
 
+    def clear_queue_assignment(self, workflow_id: str) -> None:
+        with self.engine.begin() as c:
+            c.execute(
+                sa.update(SystemSchema.workflow_queue)
+                .where(SystemSchema.workflow_queue.c.workflow_uuid == workflow_id)
+                .values(executor_id=None, started_at_epoch_ms=None)
+            )
+            c.execute(
+                sa.update(SystemSchema.workflow_status)
+                .where(SystemSchema.workflow_status.c.workflow_uuid == workflow_id)
+                .values(executor_id=None, status=WorkflowStatusString.ENQUEUED.value)
+            )
+
 
 def reset_system_database(config: ConfigFile) -> None:
     sysdb_name = (