Document Introspection (#346)

Document all programmatic workflow introspection methods. Give workflow
management its own top-level page.

Author: kraftp

docs/production/dbos-cloud/cloud-cli.md

@@ -107,7 +107,7 @@ This command retrieves the status of a Postgres database instance
 This command resets your password for a Postgres database instance.
 
 **Arguments:**
-- `[database-instance-name]`: The name of the database instance to provision.
+- `[database-instance-name]`: The name of the database instance whose password to reset.
 - `-W, --password [string]`: Your new password for this database instance. If not provided, will be prompted on the command line. Passwords must contain 8 or more characters.
 
 ---
@@ -122,43 +122,18 @@ This command destroys a previously-provisioned Postgres database instance.
 
 ---
 
-### `dbos-cloud db local`
+### `dbos-cloud db url`
 
 **Description:**
-Configure `dbos-config.yaml` to use a DBOS Cloud Postgres server for local development.
-This command also sets the `local_suffix` field in `dbos-config.yaml`, so your application will suffix its application database name with `_local` while running locally.
-This isolates the database you use for local development from the database used by your app deployed to DBOS Cloud even though both use the same Postgres server.
-
-
-**Arguments:**
-- `[database-instance-name]`: The name of the database instance to which to connect.
-- `-W, --password [string]`: Your password for this database instance. If not provided, will be prompted on the command line.
-
----
-
-### `dbos-cloud db connect`
-
-**Description:**
-This command loads your cloud database's connection parameters into your local `dbos-config.yaml`.
+This command retrives your cloud database connection URL.
 
 **Arguments:**
 - `[database-instance-name]`: The name of the database instance to which to connect.
+- `-S, --show-password`: Whether to show your database password in the output.
 - `-W, --password [string]`: Your password for this database instance. If not provided, will be prompted on the command line.
 
 ---
 
-### `dbos-cloud db restore`
-
-**Description:**
-This command performs [PostgreSQL point-in-time-recovery](https://www.postgresql.org/docs/current/continuous-archiving.html) to create a new database instance containing the state of your database instance at a previous point in time.
-After restoration is complete, we recommend using [`change-database-instance`](#dbos-cloud-app-change-database-instance) to redeploy your applications to the new database instance, then [destroying](#dbos-cloud-db-destroy) the original.
-
-**Arguments:**
-- `<database-instance-name>`: The name of the database instance to restore from.
-- `-t, --restore-time <string>`: The timestamp to restore from, in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339). Must be within the backup retention period of your database (24 hours for free-tier users).
-- `-n, --target-name <string>`: The name of the new database instance to create.
----
-
 ### `dbos-cloud db link`
 
 **Description:**
@@ -312,12 +287,11 @@ It retrieves an application's logs.
 **Description:**
 This command must be run from an application root directory.
 It redeploys the application to a new database instance.
-It is meant to be used with [`database restore`](#dbos-cloud-db-restore) during disaster recovery to transfer the application to the restored database instance.
 
 **Arguments:**
 - `--verbose`: Logs debug information about the deployment process, including config file processing and files sent.
 - `-d, --database <string>` The name of the new database instance for this application.
-- `-p, --previous-version [number]`: The ID of a previous version of this application. If this is supplied, redeploy that version instead of deploying from the application directory. During restoration, we recommend deploying to the version active at the timestamp to which you recovered. You can list previous versions and their IDs and timestamps with the [versions command](#dbos-cloud-app-versions).
+- `-p, --previous-version [number]`: The ID of a previous version of this application. If this is supplied, redeploy that version instead of deploying from the application directory.
 
 ---
 

docs/production/dbos-cloud/database-management.md

@@ -65,42 +65,6 @@ While it is occasionally necessary, be careful when manually changing the schema
 Be careful making breaking schema changes such as deleting or renaming a column—they may break active workflows running on a previous application version.
 :::
 
-### Database Recovery
-
-:::info
-Database recovery is not available for [linked databases](./byod-management.md)
-:::
-
-DBOS Cloud can use [PostgreSQL point-in-time-recovery](https://www.postgresql.org/docs/current/continuous-archiving.html) to restore your database to a previous state, for example to recover from data corruption or loss.
-First, run the [`database restore`](./cloud-cli.md#dbos-cloud-db-restore) to create a new database instance containing the state of your database instance at a previous point in time:
-
-```shell
-dbos-cloud db restore <database-name> -t <timestamp> -n <new-db-instance-name>
-```
-
-The timestamp must be in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format and must be within the backup retention period of your database (24 hours for free-tier users).
-
-After the database is restored, you can redeploy your applications to it with [`app change-database-instance`](./cloud-cli.md#dbos-cloud-app-change-database-instance).
-For each application connected to the original database instance, run:
-
-```shell
-dbos-cloud app change-database-instance --database <new-db-instance-name>
-```
-
-If you wish to restore your application to a previous version (such as the version that was running at the recovery timestamp), you can do this with the `--previous-version` parameter:
-
-```shell
-dbos-cloud app change-database-instance --database <new-db-instance-name> --previous-version <version-id>
-```
-
-For more information on application version management, see [here](./application-management.md#managing-application-versions).
-
-Finally, destroy the original database instance:
-
-```shell
-dbos-cloud db destroy <original-database-instance-name>
-```
-
 ### Destroying Database Instances
 
 To destroy a database instance, run:

docs/python/reference/contexts.md

@@ -229,6 +229,140 @@ async def example_workflow(var1: str, var2: str):
 handle: WorkflowHandleAsync = await DBOS.start_workflow_async(example_workflow, "var1", "var2")
 ```
 
+## Workflow Management Methods
+
+### list_workflows
+```python
+def list_workflows(
+    *,
+    workflow_ids: Optional[List[str]] = None,
+    status: Optional[str] = None,
+    start_time: Optional[str] = None,
+    end_time: Optional[str] = None,
+    name: Optional[str] = None,
+    app_version: Optional[str] = None,
+    user: Optional[str] = None,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    sort_desc: bool = False,
+) -> List[WorkflowStatus]:
+```
+
+Retrieve a list of [`WorkflowStatus`](#workflow-status) of all workflows matching specified criteria.
+
+**Parameters:**
+- **workflow_ids**: Retrieve workflows with these IDs.
+- **status**: Retrieve workflows with this status (Must be `ENQUEUED`, `PENDING`, `SUCCESS`, `ERROR`, `CANCELLED`, or `RETRIES_EXCEEDED`)
+- **start_time**: Retrieve workflows started after this (RFC 3339-compliant) timestamp.
+- **end_time**: Retrieve workflows started before this (RFC 3339-compliant) timestamp.
+- **name**: Retrieve workflows with this fully-qualified name.
+- **app_version**: Retrieve workflows tagged with this application version.
+- **user**: Retrieve workflows run by this authenticated user.
+- **limit**: Retrieve up to this many workflows.
+- **offset**: Skip this many workflows from the results returned (for pagination).
+- **sort_desc**: Whether to sort the results in descending (`True`) or ascending (`False`) order by workflow start time.
+
+### list_queued_workflows
+```python
+def list_queued_workflows(
+    *,
+    queue_name: Optional[str] = None,
+    status: Optional[str] = None,
+    start_time: Optional[str] = None,
+    end_time: Optional[str] = None,
+    name: Optional[str] = None,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    sort_desc: bool = False,
+) -> List[WorkflowStatus]:
+```
+
+Retrieve a list of [`WorkflowStatus`](#workflow-status) of all **currently enqueued** workflows matching specified criteria.
+
+**Parameters:**
+- **queue_name**: Retrieve workflows running on this queue.
+- **status**: Retrieve workflows with this status (Must be `ENQUEUED` or `PENDING`)
+- **start_time**: Retrieve workflows enqueued after this (RFC 3339-compliant) timestamp.
+- **end_time**: Retrieve workflows enqueued before this (RFC 3339-compliant) timestamp.
+- **name**: Retrieve workflows with this fully-qualified name.
+- **limit**: Retrieve up to this many workflows.
+- **offset**: Skip this many workflows from the results returned (for pagination).
+
+### cancel_workflow
+
+```python
+DBOS.cancel_workflow(
+    workflow_id: str,
+) -> None
+```
+
+Cancel a workflow.
+This sets is status to `CANCELLED`, removes it from its queue (if it is enqueued) and preempts its execution (interrupting it at the beginning of its next step)
+
+### resume_workflow
+
+```python
+DBOS.resume_workflow(
+    workflow_id: str,
+) -> WorkflowHandle[R]
+```
+
+Resume a workflow.
+This immediately starts it from its last completed step.
+You can use this to resume workflows that are cancelled or have exceeded their maximum recovery attempts.
+You can also use this to start an enqueued workflow immediately, bypassing its queue.
+
+### restart_workflow
+
+```python
+DBOS.restart_workflow(
+    workflow_id: str,
+) -> WorkflowHandle[R]
+```
+
+Start a new execution of a workflow with the same inputs as the original, but a new workflow ID.
+
+### Workflow Status
+
+Some workflow introspection and management methods return a `WorkflowStatus`.
+This object has the following definition:
+
+```python
+class WorkflowStatus:
+    # The workflow ID
+    workflow_id: str
+    # The workflow status. Must be one of ENQUEUED, PENDING, SUCCESS, ERROR, CANCELLED, or RETRIES_EXCEEDED
+    status: str
+    # The name of the workflow function
+    name: str
+    # The name of the workflow's class, if any
+    class_name: Optional[str]
+    # The name with which the workflow's class instance was configured, if any
+    config_name: Optional[str]
+    # The user who ran the workflow, if specified
+    authenticated_user: Optional[str]
+    # The role with which the workflow ran, if specified
+    assumed_role: Optional[str]
+    # All roles which the authenticated user could assume
+    authenticated_roles: Optional[list[str]]
+    # The deserialized workflow input object
+    input: Optional[WorkflowInputs]
+    # The workflow's output, if any
+    output: Optional[Any]
+    # The error the workflow threw, if any
+    error: Optional[Exception]
+    # Workflow start time, as a Unix epoch timestamp in ms
+    created_at: Optional[int]
+    # Last time the workflow status was updated, as a Unix epoch timestamp in ms
+    updated_at: Optional[int]
+    # If this workflow was enqueued, on which queue
+    queue_name: Optional[str]
+    # The executor to most recently executed this workflow
+    executor_id: Optional[str]
+    # The application version on which this workflow was started
+    app_version: Optional[str]
+```
+
 ## Context Variables
 
 ### logger
@@ -262,34 +396,42 @@ DBOS.workflow_id: str
 May only be accessed from within a workflow, step, or transaction.
 Return the identity of the current workflow.
 
-### span
+### step_id
 
 ```python
-DBOS.span: opentelemetry.trace.Span
+DBOS.step_id: int
 ```
 
-Retrieve the OpenTelemetry span associated with the curent request.
-You can use this to set custom attributes in your span.
+Returns the unique ID of the current step within a workflow.
 
-### request
+### step_status
 
 ```python
-DBOS.request: Request
+DBOS.step_status: StepStatus
 ```
 
-May only be accessed from within the handler of a FastAPI request, or in a function called from the handler.
-Retrieve request information parsed from FastAPI:
+Return the status of the currently executing step.
+This object has the following properties:
+
 ```python
-headers: Headers # The request headers
-path_params: dict[str, Any] # The request's path parameters
-query_params QueryParams # The request's query parameters
-url: URL # The URL to which the request was sent
-base_url: URL # The base URL of the request
-client: Optional[Address] # Information about the client that sent the request
-cookies: dict[str, str] # The request's cookie parameters
-method: str # The HTTP method of the request
+class StepStatus:
+    # The unique ID of this step in its workflow.
+    step_id: int
+    # For steps with automatic retries, which attempt number (zero-indexed) is currently executing.
+    current_attempt: Optional[int]
+    # For steps with automatic retries, the maximum number of attempts that will be made before the step fails.
+    max_attempts: Optional[int]
 ```
 
+### span
+
+```python
+DBOS.span: opentelemetry.trace.Span
+```
+
+Retrieve the OpenTelemetry span associated with the curent request.
+You can use this to set custom attributes in your span.
+
 ### config
 
 ```python

docs/python/reference/workflow_handles.md

@@ -34,7 +34,7 @@ Wait for the workflow to complete, then return its result.
 handle.get_status() -> WorkflowStatus
 ```
 
-Retrieve the [workflow's status](#workflowstatus), defined below.
+Retrieve the [`WorkflowStatus`](./contexts.md#workflow-status) of a workflow.
 
 
 ## WorkflowHandleAsync
@@ -63,18 +63,4 @@ Asynchronously wait for the workflow to complete, then return its result. Simila
 handle.get_status() -> Coroutine[Any, Any, WorkflowStatus]
 ```
 
-Asynchronously retrieves the [workflow's status](#workflowstatus), defined below.
-
-## WorkflowStatus
-
-```python
-class WorkflowStatus:
-    workflow_id: str # The workflow's ID
-    status: str # The workflow's current state. One of PENDING, SUCCESS, ERROR, RETRIES_EXCEEDED, or CANCELLED
-    name: str # The fully qualified name of the workflow function
-    class_name: Optional[str] # If the workflow function is a class method, the name of the class
-    config_name: Optional[str] # If the workflow function is a method of a configured class, the name of the class configuration
-    authenticated_user: Optional[str] # The authenticated user running the workflow
-    assumed_role: Optional[str] # The role with which the workflow is run
-    authenticatedRoles: Optional[List[str]] # All roles which the authenticated user could assume
-```
+Asynchronously retrieve the [`WorkflowStatus`](./contexts.md#workflow-status) of a workflow.

docs/python/tutorials/queue-tutorial.md

@@ -139,41 +139,3 @@ def process_event(event: str):
 def event_endpoint(event: str):
     queue.enqueue(process_event, event)
  ```
-
-
-### Queue Management
-
-Because DBOS manages queues in Postgres, you can view and manage queued functions from the command line.
-These commands are also available for applications deployed to DBOS Cloud using the [cloud CLI](../../production/dbos-cloud/cloud-cli.md).
-
-#### Listing Queued Functions
-
-You can list all currently enqueued functions with:
-
-```shell
-dbos workflow list
-```
-
-By default, this lists all currently enqueued functions, including queued functions that are currently executing, but not completed functions
-You can parameterize this command for advanced search, see full documentation [here](../reference/cli.md#dbos-workflow-queue-list).
-
-#### Removing Queued Functions
-
-You can remove a function from a queue with:
-
-```shell
-dbos workflow cancel <workflow-id>
-```
-
-This removes the function from its queue and transitions it to a `CANCELLED` state, so it will not run unless manually resumed.
-
-#### Resuming Workflows
-
-You can start execution of an enqueued function with:
-
-```shell
-dbos workflow resume <workflow-id>
-```
-
-This starts execution immediately, bypassing the queue and transitioning the function to a `PENDING` state.
-It also removes the function from its queue.