dbos 0.23.0a8__tar.gz → 0.23.0a9__tar.gz

{dbos-0.23.0a8 → dbos-0.23.0a9}/PKG-INFO

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

dbos-0.23.0a9/dbos/__main__.py

@@ -0,0 +1,26 @@
+import re
+import sys
+from typing import NoReturn, Optional, Union
+
+from dbos.cli.cli import app
+
+
+def main() -> NoReturn:
+    # Modify sys.argv[0] to remove script or executable extensions
+    sys.argv[0] = re.sub(r"(-script\.pyw|\.exe)?$", "", sys.argv[0])
+
+    retval: Optional[Union[str, int]] = 1
+    try:
+        app()
+        retval = None
+    except SystemExit as e:
+        retval = e.code
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        retval = 1
+    finally:
+        sys.exit(retval)
+
+
+if __name__ == "__main__":
+    main()

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/_app_db.py

@@ -27,29 +27,30 @@ class RecordedResult(TypedDict):
 
 class ApplicationDatabase:
 
-    def __init__(self, config: ConfigFile):
+    def __init__(self, config: ConfigFile, *, debug_mode: bool = False):
         self.config = config
 
         app_db_name = config["database"]["app_db_name"]
 
         # If the application database does not already exist, create it
-        postgres_db_url = sa.URL.create(
-            "postgresql+psycopg",
-            username=config["database"]["username"],
-            password=config["database"]["password"],
-            host=config["database"]["hostname"],
-            port=config["database"]["port"],
-            database="postgres",
-        )
-        postgres_db_engine = sa.create_engine(postgres_db_url)
-        with postgres_db_engine.connect() as conn:
-            conn.execution_options(isolation_level="AUTOCOMMIT")
-            if not conn.execute(
-                sa.text("SELECT 1 FROM pg_database WHERE datname=:db_name"),
-                parameters={"db_name": app_db_name},
-            ).scalar():
-                conn.execute(sa.text(f"CREATE DATABASE {app_db_name}"))
-        postgres_db_engine.dispose()
+        if not debug_mode:
+            postgres_db_url = sa.URL.create(
+                "postgresql+psycopg",
+                username=config["database"]["username"],
+                password=config["database"]["password"],
+                host=config["database"]["hostname"],
+                port=config["database"]["port"],
+                database="postgres",
+            )
+            postgres_db_engine = sa.create_engine(postgres_db_url)
+            with postgres_db_engine.connect() as conn:
+                conn.execution_options(isolation_level="AUTOCOMMIT")
+                if not conn.execute(
+                    sa.text("SELECT 1 FROM pg_database WHERE datname=:db_name"),
+                    parameters={"db_name": app_db_name},
+                ).scalar():
+                    conn.execute(sa.text(f"CREATE DATABASE {app_db_name}"))
+            postgres_db_engine.dispose()
 
         # Create a connection pool for the application database
         app_db_url = sa.URL.create(
@@ -64,14 +65,16 @@ class ApplicationDatabase:
             app_db_url, pool_size=20, max_overflow=5, pool_timeout=30
         )
         self.sessionmaker = sessionmaker(bind=self.engine)
+        self.debug_mode = debug_mode
 
         # Create the dbos schema and transaction_outputs table in the application database
-        with self.engine.begin() as conn:
-            schema_creation_query = sa.text(
-                f"CREATE SCHEMA IF NOT EXISTS {ApplicationSchema.schema}"
-            )
-            conn.execute(schema_creation_query)
-        ApplicationSchema.metadata_obj.create_all(self.engine)
+        if not debug_mode:
+            with self.engine.begin() as conn:
+                schema_creation_query = sa.text(
+                    f"CREATE SCHEMA IF NOT EXISTS {ApplicationSchema.schema}"
+                )
+                conn.execute(schema_creation_query)
+            ApplicationSchema.metadata_obj.create_all(self.engine)
 
     def destroy(self) -> None:
         self.engine.dispose()
@@ -100,6 +103,8 @@ class ApplicationDatabase:
             raise
 
     def record_transaction_error(self, output: TransactionResultInternal) -> None:
+        if self.debug_mode:
+            raise Exception("called record_transaction_error in debug mode")
         try:
             with self.engine.begin() as conn:
                 conn.execute(

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/_core.py

@@ -186,21 +186,31 @@ def _init_workflow(
         inputs = {"args": inputs["args"][1:], "kwargs": inputs["kwargs"]}
 
     wf_status = status["status"]
-    if temp_wf_type != "transaction" or queue is not None:
-        # 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.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))
+    if dbos.debug_mode:
+        get_status_result = dbos._sys_db.get_workflow_status(wfid)
+        if get_status_result is None:
+            raise DBOSNonExistentWorkflowError(wfid)
+        wf_status = get_status_result["status"]
     else:
-        # Buffer the inputs for single-transaction workflows, but don't buffer the status
-        dbos._sys_db.buffer_workflow_inputs(wfid, _serialization.serialize_args(inputs))
+        if temp_wf_type != "transaction" or queue is not None:
+            # 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.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)
+            )
+        else:
+            # Buffer the inputs for single-transaction workflows, but don't buffer the status
+            dbos._sys_db.buffer_workflow_inputs(
+                wfid, _serialization.serialize_args(inputs)
+            )
 
-    if queue is not None and wf_status == WorkflowStatusString.ENQUEUED.value:
-        dbos._sys_db.enqueue(wfid, queue)
+        if queue is not None and wf_status == WorkflowStatusString.ENQUEUED.value:
+            dbos._sys_db.enqueue(wfid, queue)
 
     status["status"] = wf_status
     return status
@@ -215,10 +225,11 @@ def _get_wf_invoke_func(
             output = func()
             status["status"] = "SUCCESS"
             status["output"] = _serialization.serialize(output)
-            if status["queue_name"] is not None:
-                queue = dbos._registry.queue_info_map[status["queue_name"]]
-                dbos._sys_db.remove_from_queue(status["workflow_uuid"], queue)
-            dbos._sys_db.buffer_workflow_status(status)
+            if not dbos.debug_mode:
+                if status["queue_name"] is not None:
+                    queue = dbos._registry.queue_info_map[status["queue_name"]]
+                    dbos._sys_db.remove_from_queue(status["workflow_uuid"], queue)
+                dbos._sys_db.buffer_workflow_status(status)
             return output
         except DBOSWorkflowConflictIDError:
             # Retrieve the workflow handle and wait for the result.
@@ -233,10 +244,11 @@ def _get_wf_invoke_func(
         except Exception as error:
             status["status"] = "ERROR"
             status["error"] = _serialization.serialize_exception(error)
-            if status["queue_name"] is not None:
-                queue = dbos._registry.queue_info_map[status["queue_name"]]
-                dbos._sys_db.remove_from_queue(status["workflow_uuid"], queue)
-            dbos._sys_db.update_workflow_status(status)
+            if not dbos.debug_mode:
+                if status["queue_name"] is not None:
+                    queue = dbos._registry.queue_info_map[status["queue_name"]]
+                    dbos._sys_db.remove_from_queue(status["workflow_uuid"], queue)
+                dbos._sys_db.update_workflow_status(status)
             raise
 
     return persist
@@ -422,10 +434,12 @@ def start_workflow(
 
     wf_status = status["status"]
 
-    if (
-        not execute_workflow
-        or wf_status == WorkflowStatusString.ERROR.value
-        or wf_status == WorkflowStatusString.SUCCESS.value
+    if not execute_workflow or (
+        not dbos.debug_mode
+        and (
+            wf_status == WorkflowStatusString.ERROR.value
+            or wf_status == WorkflowStatusString.SUCCESS.value
+        )
     ):
         dbos.logger.debug(
             f"Workflow {new_wf_id} already completed with status {wf_status}. Directly returning a workflow handle."
@@ -597,6 +611,10 @@ def decorate_transaction(
                                         ctx.function_id,
                                     )
                                 )
+                                if dbos.debug_mode and recorded_output is None:
+                                    raise DBOSException(
+                                        "Transaction output not found in debug mode"
+                                    )
                                 if recorded_output:
                                     dbos.logger.debug(
                                         f"Replaying transaction, id: {ctx.function_id}, name: {attributes['name']}"
@@ -780,6 +798,8 @@ def decorate_step(
                 recorded_output = dbos._sys_db.check_operation_execution(
                     ctx.workflow_id, ctx.function_id
                 )
+                if dbos.debug_mode and recorded_output is None:
+                    raise DBOSException("Step output not found in debug mode")
                 if recorded_output:
                     dbos.logger.debug(
                         f"Replaying step, id: {ctx.function_id}, name: {attributes['name']}"

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/_dbos.py

@@ -313,6 +313,7 @@ class DBOS:
         dbos_logger.info("Initializing DBOS")
         self.config: ConfigFile = config
         self._launched: bool = False
+        self._debug_mode: bool = False
         self._sys_db_field: Optional[SystemDatabase] = None
         self._app_db_field: Optional[ApplicationDatabase] = None
         self._registry: DBOSRegistry = _get_or_create_dbos_registry()
@@ -380,23 +381,32 @@ class DBOS:
         rv: AdminServer = self._admin_server_field
         return rv
 
+    @property
+    def debug_mode(self) -> bool:
+        return self._debug_mode
+
     @classmethod
-    def launch(cls) -> None:
+    def launch(cls, *, debug_mode: bool = False) -> None:
         if _dbos_global_instance is not None:
-            _dbos_global_instance._launch()
+            _dbos_global_instance._launch(debug_mode=debug_mode)
 
-    def _launch(self) -> None:
+    def _launch(self, *, debug_mode: bool = False) -> None:
         try:
             if self._launched:
                 dbos_logger.warning(f"DBOS was already launched")
                 return
             self._launched = True
+            self._debug_mode = debug_mode
             if GlobalParams.app_version == "":
                 GlobalParams.app_version = self._registry.compute_app_version()
             dbos_logger.info(f"Application version: {GlobalParams.app_version}")
             self._executor_field = ThreadPoolExecutor(max_workers=64)
-            self._sys_db_field = SystemDatabase(self.config)
-            self._app_db_field = ApplicationDatabase(self.config)
+            self._sys_db_field = SystemDatabase(self.config, debug_mode=debug_mode)
+            self._app_db_field = ApplicationDatabase(self.config, debug_mode=debug_mode)
+
+            if debug_mode:
+                return
+
             admin_port = self.config["runtimeConfig"].get("admin_port")
             if admin_port is None:
                 admin_port = 3001

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/_dbos_config.py

@@ -192,7 +192,11 @@ def load_config(
     data = cast(ConfigFile, data)
     db_connection = load_db_connection()
     if not silent:
-        if data["database"].get("hostname"):
+        if os.getenv("DBOS_DBHOST"):
+            print(
+                "[bold blue]Loading database connection parameters from debug environment variables[/bold blue]"
+            )
+        elif data["database"].get("hostname"):
             print(
                 "[bold blue]Loading database connection parameters from dbos-config.yaml[/bold blue]"
             )
@@ -205,32 +209,62 @@ def load_config(
                 "[bold blue]Using default database connection parameters (localhost)[/bold blue]"
             )
 
+    dbos_dbport: Optional[int] = None
+    dbport_env = os.getenv("DBOS_DBPORT")
+    if dbport_env:
+        try:
+            dbos_dbport = int(dbport_env)
+        except ValueError:
+            pass
+    dbos_dblocalsuffix: Optional[bool] = None
+    dblocalsuffix_env = os.getenv("DBOS_DBLOCALSUFFIX")
+    if dblocalsuffix_env:
+        try:
+            dbos_dblocalsuffix = dblocalsuffix_env.casefold() == "true".casefold()
+        except ValueError:
+            pass
+
     data["database"]["hostname"] = (
-        data["database"].get("hostname") or db_connection.get("hostname") or "localhost"
+        os.getenv("DBOS_DBHOST")
+        or data["database"].get("hostname")
+        or db_connection.get("hostname")
+        or "localhost"
     )
+
     data["database"]["port"] = (
-        data["database"].get("port") or db_connection.get("port") or 5432
+        dbos_dbport or data["database"].get("port") or db_connection.get("port") or 5432
     )
     data["database"]["username"] = (
-        data["database"].get("username") or db_connection.get("username") or "postgres"
+        os.getenv("DBOS_DBUSER")
+        or data["database"].get("username")
+        or db_connection.get("username")
+        or "postgres"
     )
     data["database"]["password"] = (
-        data["database"].get("password")
+        os.getenv("DBOS_DBPASSWORD")
+        or data["database"].get("password")
         or db_connection.get("password")
         or os.environ.get("PGPASSWORD")
         or "dbos"
     )
-    data["database"]["local_suffix"] = (
-        data["database"].get("local_suffix")
-        or db_connection.get("local_suffix")
-        or False
-    )
+
+    local_suffix = False
+    dbcon_local_suffix = db_connection.get("local_suffix")
+    if dbcon_local_suffix is not None:
+        local_suffix = dbcon_local_suffix
+    if data["database"].get("local_suffix") is not None:
+        local_suffix = data["database"].get("local_suffix")
+    if dbos_dblocalsuffix is not None:
+        local_suffix = dbos_dblocalsuffix
+    data["database"]["local_suffix"] = local_suffix
 
     # Configure the DBOS logger
     config_logger(data)
 
     # Check the connectivity to the database and make sure it's properly configured
-    if use_db_wizard:
+    # Note, never use db wizard if the DBOS is running in debug mode (i.e. DBOS_DEBUG_WORKFLOW_ID env var is set)
+    debugWorkflowId = os.getenv("DBOS_DEBUG_WORKFLOW_ID")
+    if use_db_wizard and debugWorkflowId is None:
         data = db_wizard(data, config_file_path)
 
     if "local_suffix" in data["database"] and data["database"]["local_suffix"]:

dbos-0.23.0a9/dbos/_debug.py

@@ -0,0 +1,45 @@
+import re
+import runpy
+import sys
+from typing import Union
+
+from dbos import DBOS
+
+
+class PythonModule:
+    def __init__(self, module_name: str):
+        self.module_name = module_name
+
+
+def debug_workflow(workflow_id: str, entrypoint: Union[str, PythonModule]) -> None:
+    # include the current directory (represented by empty string) in the search path
+    # if it not already included
+    if "" not in sys.path:
+        sys.path.insert(0, "")
+    if isinstance(entrypoint, str):
+        runpy.run_path(entrypoint)
+    elif isinstance(entrypoint, PythonModule):
+        runpy.run_module(entrypoint.module_name)
+    else:
+        raise ValueError("Invalid entrypoint type. Must be a string or PythonModule.")
+
+    DBOS.logger.info(f"Debugging workflow {workflow_id}...")
+    DBOS.launch(debug_mode=True)
+    handle = DBOS.execute_workflow_id(workflow_id)
+    handle.get_result()
+    DBOS.logger.info("Workflow Debugging complete. Exiting process.")
+
+
+def parse_start_command(command: str) -> Union[str, PythonModule]:
+    match = re.match(r"fastapi\s+run\s+(\.?[\w/]+\.py)", command)
+    if match:
+        return match.group(1)
+    match = re.match(r"python3?\s+(\.?[\w/]+\.py)", command)
+    if match:
+        return match.group(1)
+    match = re.match(r"python3?\s+-m\s+([\w\.]+)", command)
+    if match:
+        return PythonModule(match.group(1))
+    raise ValueError(
+        "Invalid command format. Must be 'fastapi run <script>' or 'python <script>' or 'python -m <module>'"
+    )

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/_sys_db.py

@@ -156,7 +156,7 @@ _buffer_flush_interval_secs = 1.0
 
 class SystemDatabase:
 
-    def __init__(self, config: ConfigFile):
+    def __init__(self, config: ConfigFile, *, debug_mode: bool = False):
         self.config = config
 
         sysdb_name = (
@@ -165,26 +165,27 @@ class SystemDatabase:
             else config["database"]["app_db_name"] + SystemSchema.sysdb_suffix
         )
 
-        # If the system database does not already exist, create it
-        postgres_db_url = sa.URL.create(
-            "postgresql+psycopg",
-            username=config["database"]["username"],
-            password=config["database"]["password"],
-            host=config["database"]["hostname"],
-            port=config["database"]["port"],
-            database="postgres",
-            # fills the "application_name" column in pg_stat_activity
-            query={"application_name": f"dbos_transact_{GlobalParams.executor_id}"},
-        )
-        engine = sa.create_engine(postgres_db_url)
-        with engine.connect() as conn:
-            conn.execution_options(isolation_level="AUTOCOMMIT")
-            if not conn.execute(
-                sa.text("SELECT 1 FROM pg_database WHERE datname=:db_name"),
-                parameters={"db_name": sysdb_name},
-            ).scalar():
-                conn.execute(sa.text(f"CREATE DATABASE {sysdb_name}"))
-        engine.dispose()
+        if not debug_mode:
+            # If the system database does not already exist, create it
+            postgres_db_url = sa.URL.create(
+                "postgresql+psycopg",
+                username=config["database"]["username"],
+                password=config["database"]["password"],
+                host=config["database"]["hostname"],
+                port=config["database"]["port"],
+                database="postgres",
+                # fills the "application_name" column in pg_stat_activity
+                query={"application_name": f"dbos_transact_{GlobalParams.executor_id}"},
+            )
+            engine = sa.create_engine(postgres_db_url)
+            with engine.connect() as conn:
+                conn.execution_options(isolation_level="AUTOCOMMIT")
+                if not conn.execute(
+                    sa.text("SELECT 1 FROM pg_database WHERE datname=:db_name"),
+                    parameters={"db_name": sysdb_name},
+                ).scalar():
+                    conn.execute(sa.text(f"CREATE DATABASE {sysdb_name}"))
+            engine.dispose()
 
         system_db_url = sa.URL.create(
             "postgresql+psycopg",
@@ -203,25 +204,41 @@ class SystemDatabase:
         )
 
         # Run a schema migration for the system database
-        migration_dir = os.path.join(
-            os.path.dirname(os.path.realpath(__file__)), "_migrations"
-        )
-        alembic_cfg = Config()
-        alembic_cfg.set_main_option("script_location", migration_dir)
-        logging.getLogger("alembic").setLevel(logging.WARNING)
-        # Alembic requires the % in URL-escaped parameters to itself be escaped to %%.
-        escaped_conn_string = re.sub(
-            r"%(?=[0-9A-Fa-f]{2})",
-            "%%",
-            self.engine.url.render_as_string(hide_password=False),
-        )
-        alembic_cfg.set_main_option("sqlalchemy.url", escaped_conn_string)
-        try:
-            command.upgrade(alembic_cfg, "head")
-        except Exception as e:
-            dbos_logger.warning(
-                f"Exception during system database construction. This is most likely because the system database was configured using a later version of DBOS: {e}"
+        if not debug_mode:
+            migration_dir = os.path.join(
+                os.path.dirname(os.path.realpath(__file__)), "_migrations"
             )
+            alembic_cfg = Config()
+            alembic_cfg.set_main_option("script_location", migration_dir)
+            logging.getLogger("alembic").setLevel(logging.WARNING)
+            # Alembic requires the % in URL-escaped parameters to itself be escaped to %%.
+            escaped_conn_string = re.sub(
+                r"%(?=[0-9A-Fa-f]{2})",
+                "%%",
+                self.engine.url.render_as_string(hide_password=False),
+            )
+            alembic_cfg.set_main_option("sqlalchemy.url", escaped_conn_string)
+            try:
+                command.upgrade(alembic_cfg, "head")
+            except Exception as e:
+                dbos_logger.warning(
+                    f"Exception during system database construction. This is most likely because the system database was configured using a later version of DBOS: {e}"
+                )
+                alembic_cfg = Config()
+                alembic_cfg.set_main_option("script_location", migration_dir)
+                # Alembic requires the % in URL-escaped parameters to itself be escaped to %%.
+                escaped_conn_string = re.sub(
+                    r"%(?=[0-9A-Fa-f]{2})",
+                    "%%",
+                    self.engine.url.render_as_string(hide_password=False),
+                )
+                alembic_cfg.set_main_option("sqlalchemy.url", escaped_conn_string)
+                try:
+                    command.upgrade(alembic_cfg, "head")
+                except Exception as e:
+                    dbos_logger.warning(
+                        f"Exception during system database construction. This is most likely because the system database was configured using a later version of DBOS: {e}"
+                    )
 
         self.notification_conn: Optional[psycopg.connection.Connection] = None
         self.notifications_map: Dict[str, threading.Condition] = {}
@@ -237,6 +254,7 @@ class SystemDatabase:
 
         # Now we can run background processes
         self._run_background_processes = True
+        self._debug_mode = debug_mode
 
     # Destroy the pool when finished
     def destroy(self) -> None:
@@ -258,6 +276,8 @@ class SystemDatabase:
         *,
         max_recovery_attempts: int = DEFAULT_MAX_RECOVERY_ATTEMPTS,
     ) -> WorkflowStatuses:
+        if self._debug_mode:
+            raise Exception("called insert_workflow_status in debug mode")
         wf_status: WorkflowStatuses = status["status"]
 
         cmd = (
@@ -357,6 +377,8 @@ class SystemDatabase:
         *,
         conn: Optional[sa.Connection] = None,
     ) -> None:
+        if self._debug_mode:
+            raise Exception("called update_workflow_status in debug mode")
         wf_status: WorkflowStatuses = status["status"]
 
         cmd = (
@@ -406,6 +428,8 @@ class SystemDatabase:
         self,
         workflow_id: str,
     ) -> None:
+        if self._debug_mode:
+            raise Exception("called cancel_workflow in debug mode")
         with self.engine.begin() as c:
             # Remove the workflow from the queues table so it does not block the table
             c.execute(
@@ -426,6 +450,8 @@ class SystemDatabase:
         self,
         workflow_id: str,
     ) -> None:
+        if self._debug_mode:
+            raise Exception("called resume_workflow in debug mode")
         with self.engine.begin() as c:
             # Check the status of the workflow. If it is complete, do nothing.
             row = c.execute(
@@ -573,6 +599,9 @@ class SystemDatabase:
     def update_workflow_inputs(
         self, workflow_uuid: str, inputs: str, conn: Optional[sa.Connection] = None
     ) -> None:
+        if self._debug_mode:
+            raise Exception("called update_workflow_inputs in debug mode")
+
         cmd = (
             pg.insert(SystemSchema.workflow_inputs)
             .values(
@@ -737,6 +766,8 @@ class SystemDatabase:
     def record_operation_result(
         self, result: OperationResultInternal, conn: Optional[sa.Connection] = None
     ) -> None:
+        if self._debug_mode:
+            raise Exception("called record_operation_result in debug mode")
         error = result["error"]
         output = result["output"]
         assert error is None or output is None, "Only one of error or output can be set"
@@ -796,6 +827,11 @@ class SystemDatabase:
             recorded_output = self.check_operation_execution(
                 workflow_uuid, function_id, conn=c
             )
+            if self._debug_mode and recorded_output is None:
+                raise Exception(
+                    "called send in debug mode without a previous execution"
+                )
+
             if recorded_output is not None:
                 dbos_logger.debug(
                     f"Replaying send, id: {function_id}, destination_uuid: {destination_uuid}, topic: {topic}"
@@ -839,6 +875,8 @@ class SystemDatabase:
 
         # First, check for previous executions.
         recorded_output = self.check_operation_execution(workflow_uuid, function_id)
+        if self._debug_mode and recorded_output is None:
+            raise Exception("called recv in debug mode without a previous execution")
         if recorded_output is not None:
             dbos_logger.debug(f"Replaying recv, id: {function_id}, topic: {topic}")
             if recorded_output["output"] is not None:
@@ -988,6 +1026,9 @@ class SystemDatabase:
     ) -> float:
         recorded_output = self.check_operation_execution(workflow_uuid, function_id)
         end_time: float
+        if self._debug_mode and recorded_output is None:
+            raise Exception("called sleep in debug mode without a previous execution")
+
         if recorded_output is not None:
             dbos_logger.debug(f"Replaying sleep, id: {function_id}, seconds: {seconds}")
             assert recorded_output["output"] is not None, "no recorded end time"
@@ -1022,6 +1063,10 @@ class SystemDatabase:
             recorded_output = self.check_operation_execution(
                 workflow_uuid, function_id, conn=c
             )
+            if self._debug_mode and recorded_output is None:
+                raise Exception(
+                    "called set_event in debug mode without a previous execution"
+                )
             if recorded_output is not None:
                 dbos_logger.debug(f"Replaying set_event, id: {function_id}, key: {key}")
                 return  # Already sent before
@@ -1066,6 +1111,10 @@ class SystemDatabase:
             recorded_output = self.check_operation_execution(
                 caller_ctx["workflow_uuid"], caller_ctx["function_id"]
             )
+            if self._debug_mode and recorded_output is None:
+                raise Exception(
+                    "called get_event in debug mode without a previous execution"
+                )
             if recorded_output is not None:
                 dbos_logger.debug(
                     f"Replaying get_event, id: {caller_ctx['function_id']}, key: {key}"
@@ -1128,6 +1177,9 @@ class SystemDatabase:
         return value
 
     def _flush_workflow_status_buffer(self) -> None:
+        if self._debug_mode:
+            raise Exception("called _flush_workflow_status_buffer in debug mode")
+
         """Export the workflow status buffer to the database, up to the batch size."""
         if len(self._workflow_status_buffer) == 0:
             return
@@ -1158,6 +1210,9 @@ class SystemDatabase:
                     break
 
     def _flush_workflow_inputs_buffer(self) -> None:
+        if self._debug_mode:
+            raise Exception("called _flush_workflow_inputs_buffer in debug mode")
+
         """Export the workflow inputs buffer to the database, up to the batch size."""
         if len(self._workflow_inputs_buffer) == 0:
             return
@@ -1222,6 +1277,8 @@ class SystemDatabase:
         )
 
     def enqueue(self, workflow_id: str, queue_name: str) -> None:
+        if self._debug_mode:
+            raise Exception("called enqueue in debug mode")
         with self.engine.begin() as c:
             c.execute(
                 pg.insert(SystemSchema.workflow_queue)
@@ -1233,6 +1290,9 @@ class SystemDatabase:
             )
 
     def start_queued_workflows(self, queue: "Queue", executor_id: str) -> List[str]:
+        if self._debug_mode:
+            return []
+
         start_time_ms = int(time.time() * 1000)
         if queue.limiter is not None:
             limiter_period_ms = int(queue.limiter["period"] * 1000)
@@ -1383,6 +1443,9 @@ class SystemDatabase:
             return ret_ids
 
     def remove_from_queue(self, workflow_id: str, queue: "Queue") -> None:
+        if self._debug_mode:
+            raise Exception("called remove_from_queue in debug mode")
+
         with self.engine.begin() as c:
             if queue.limiter is None:
                 c.execute(
@@ -1398,6 +1461,8 @@ class SystemDatabase:
                 )
 
     def clear_queue_assignment(self, workflow_id: str) -> None:
+        if self._debug_mode:
+            raise Exception("called clear_queue_assignment in debug mode")
         with self.engine.begin() as c:
             c.execute(
                 sa.update(SystemSchema.workflow_queue)

{dbos-0.23.0a8 → dbos-0.23.0a9}/dbos/cli/cli.py

@@ -15,6 +15,8 @@ from rich import print
 from rich.prompt import IntPrompt
 from typing_extensions import Annotated
 
+from dbos._debug import debug_workflow, parse_start_command
+
 from .. import load_config
 from .._app_db import ApplicationDatabase
 from .._dbos_config import _is_valid_app_name
@@ -232,6 +234,22 @@ def reset(
         return
 
 
+@app.command(help="Replay Debug a DBOS workflow")
+def debug(
+    workflow_id: Annotated[str, typer.Argument(help="Workflow ID to debug")],
+) -> None:
+    config = load_config(silent=True, use_db_wizard=False)
+    start = config["runtimeConfig"]["start"]
+    if not start:
+        typer.echo("No start commands found in 'dbos-config.yaml'")
+        raise typer.Exit(code=1)
+    if len(start) > 1:
+        typer.echo("Multiple start commands found in 'dbos-config.yaml'")
+        raise typer.Exit(code=1)
+    entrypoint = parse_start_command(start[0])
+    debug_workflow(workflow_id, entrypoint)
+
+
 @workflow.command(help="List workflows for your application")
 def list(
     limit: Annotated[

{dbos-0.23.0a8 → dbos-0.23.0a9}/pyproject.toml

@@ -27,7 +27,7 @@ dependencies = [
 ]
 requires-python = ">=3.9"
 readme = "README.md"
-version = "0.23.0a8"
+version = "0.23.0a9"
 
 [project.license]
 text = "MIT"

{dbos-0.23.0a8 → dbos-0.23.0a9}/tests/test_config.py

@@ -4,6 +4,7 @@ import os
 from unittest.mock import mock_open
 
 import pytest
+import pytest_mock
 
 # Public API
 from dbos import load_config
@@ -422,3 +423,40 @@ def test_no_db_wizard(mocker):
     with pytest.raises(DBOSInitializationError) as exc_info:
         load_config(mock_filename)
     assert "Could not connect" in str(exc_info.value)
+
+
+def test_debug_override(mocker: pytest_mock.MockFixture):
+    mock_config = """
+        name: "some-app"
+        language: "python"
+        runtimeConfig:
+            start:
+                - "python3 main.py"
+        database:
+          hostname: 'localhost'
+          port: 5432
+          username: 'postgres'
+          password: 'super-secret-password'
+          local_suffix: true
+    """
+    mocker.patch(
+        "builtins.open", side_effect=generate_mock_open(mock_filename, mock_config)
+    )
+
+    mocker.patch.dict(
+        os.environ,
+        {
+            "DBOS_DBHOST": "fakehost",
+            "DBOS_DBPORT": "1234",
+            "DBOS_DBUSER": "fakeuser",
+            "DBOS_DBPASSWORD": "fakepassword",
+            "DBOS_DBLOCALSUFFIX": "false",
+        },
+    )
+
+    configFile = load_config(mock_filename, use_db_wizard=False)
+    assert configFile["database"]["hostname"] == "fakehost"
+    assert configFile["database"]["port"] == 1234
+    assert configFile["database"]["username"] == "fakeuser"
+    assert configFile["database"]["password"] == "fakepassword"
+    assert configFile["database"]["local_suffix"] == False

dbos-0.23.0a9/tests/test_debug.py

@@ -0,0 +1,147 @@
+import uuid
+
+import pytest
+import sqlalchemy as sa
+
+from dbos import DBOS, ConfigFile, SetWorkflowID
+from dbos._dbos import _get_dbos_instance
+from dbos._debug import PythonModule, parse_start_command
+from dbos._schemas.system_database import SystemSchema
+
+
+def test_parse_fast_api_command() -> None:
+    command = "fastapi run app/main.py"
+    expected = "app/main.py"
+    actual = parse_start_command(command)
+    assert actual == expected
+
+
+def test_parse_python_command() -> None:
+    command = "python app/main.py"
+    expected = "app/main.py"
+    actual = parse_start_command(command)
+    assert actual == expected
+
+
+def test_parse_python3_command() -> None:
+    command = "python3 app/main.py"
+    expected = "app/main.py"
+    actual = parse_start_command(command)
+    assert actual == expected
+
+
+def test_parse_python_module_command() -> None:
+    command = "python -m some_module"
+    actual = parse_start_command(command)
+    assert isinstance(actual, PythonModule)
+    assert actual.module_name == "some_module"
+
+
+def test_parse_python3_module_command() -> None:
+    command = "python3 -m some_module"
+    actual = parse_start_command(command)
+    assert isinstance(actual, PythonModule)
+    assert actual.module_name == "some_module"
+
+
+def get_recovery_attempts(wfuuid: str) -> int:
+    dbos = _get_dbos_instance()
+    with dbos._sys_db.engine.connect() as c:
+        stmt = sa.select(
+            SystemSchema.workflow_status.c.recovery_attempts,
+            SystemSchema.workflow_status.c.created_at,
+            SystemSchema.workflow_status.c.updated_at,
+        ).where(SystemSchema.workflow_status.c.workflow_uuid == wfuuid)
+        result = c.execute(stmt).fetchone()
+        assert result is not None
+        recovery_attempts, created_at, updated_at = result
+        return int(recovery_attempts)
+
+
+def test_wf_debug(dbos: DBOS, config: ConfigFile) -> None:
+    wf_counter: int = 0
+    step_counter: int = 0
+
+    @DBOS.workflow()
+    def test_workflow(var: str) -> str:
+        nonlocal wf_counter
+        wf_counter += 1
+        res = test_step(var)
+        DBOS.logger.info("I'm test_workflow")
+        return res
+
+    @DBOS.step()
+    def test_step(var: str) -> str:
+        nonlocal step_counter
+        step_counter += 1
+        DBOS.logger.info("I'm test_step")
+        return var
+
+    wfuuid = str(uuid.uuid4())
+    with SetWorkflowID(wfuuid):
+        handle = DBOS.start_workflow(test_workflow, "test")
+        result = handle.get_result()
+        assert result == "test"
+        assert wf_counter == 1
+        assert step_counter == 1
+
+    expected_retry_attempts = get_recovery_attempts(wfuuid)
+
+    DBOS.destroy()
+    DBOS(config=config)
+    DBOS.launch(debug_mode=True)
+
+    handle = DBOS.execute_workflow_id(wfuuid)
+    result = handle.get_result()
+    assert result == "test"
+    assert wf_counter == 2
+    assert step_counter == 1
+
+    actual_retry_attempts = get_recovery_attempts(wfuuid)
+    assert actual_retry_attempts == expected_retry_attempts
+
+
+def test_wf_debug_exception(dbos: DBOS, config: ConfigFile) -> None:
+    wf_counter: int = 0
+    step_counter: int = 0
+
+    @DBOS.workflow()
+    def test_workflow(var: str) -> str:
+        nonlocal wf_counter
+        wf_counter += 1
+        res = test_step(var)
+        DBOS.logger.info("I'm test_workflow")
+        raise Exception("test_wf_debug_exception")
+
+    @DBOS.step()
+    def test_step(var: str) -> str:
+        nonlocal step_counter
+        step_counter += 1
+        DBOS.logger.info("I'm test_step")
+        return var
+
+    wfuuid = str(uuid.uuid4())
+    with SetWorkflowID(wfuuid):
+        handle = DBOS.start_workflow(test_workflow, "test")
+        with pytest.raises(Exception) as excinfo:
+            handle.get_result()
+        assert str(excinfo.value) == "test_wf_debug_exception"
+
+        assert wf_counter == 1
+        assert step_counter == 1
+
+    expected_retry_attempts = get_recovery_attempts(wfuuid)
+
+    DBOS.destroy()
+    DBOS(config=config)
+    DBOS.launch(debug_mode=True)
+
+    handle = DBOS.execute_workflow_id(wfuuid)
+    with pytest.raises(Exception) as excinfo:
+        handle.get_result()
+    assert str(excinfo.value) == "test_wf_debug_exception"
+    assert wf_counter == 2
+    assert step_counter == 1
+
+    actual_retry_attempts = get_recovery_attempts(wfuuid)
+    assert actual_retry_attempts == expected_retry_attempts