{"id":31455304,"url":"https://github.com/dbos-inc/dbos-transact-java","last_synced_at":"2025-10-01T09:07:36.632Z","repository":{"id":311967065,"uuid":"1000380571","full_name":"dbos-inc/dbos-transact-java","owner":"dbos-inc","description":"DBOS Transact Java SDK ","archived":false,"fork":false,"pushed_at":"2025-09-29T18:27:51.000Z","size":971,"stargazers_count":19,"open_issues_count":9,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-29T18:29:50.012Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbos-inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-11T17:32:15.000Z","updated_at":"2025-09-29T18:27:53.000Z","dependencies_parsed_at":"2025-09-12T21:13:10.475Z","dependency_job_id":"1b3ad3fb-ecd8-468b-866d-88c914d262b9","html_url":"https://github.com/dbos-inc/dbos-transact-java","commit_stats":null,"previous_names":["dbos-inc/dbos-transact-java"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dbos-inc/dbos-transact-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbos-inc%2Fdbos-transact-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbos-inc%2Fdbos-transact-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbos-inc%2Fdbos-transact-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbos-inc%2Fdbos-transact-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbos-inc","download_url":"https://codeload.github.com/dbos-inc/dbos-transact-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbos-inc%2Fdbos-transact-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277818187,"owners_count":25882365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-01T02:00:09.286Z","response_time":88,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-01T09:07:35.098Z","updated_at":"2025-10-01T09:07:36.624Z","avatar_url":"https://github.com/dbos-inc.png","language":"Java","readme":"\u003cdiv align=\"center\"\u003e\n\n# DBOS Transact: Lightweight Durable Workflows\n# Java version in preview + under active development\n\n#### [Documentation](https://docs.dbos.dev/) \u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;  [Examples](https://docs.dbos.dev/examples) \u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp; [Github](https://github.com/dbos-inc) \u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp; [Discord](https://discord.com/invite/jsmC6pXGgX)\n\u003c/div\u003e\n\n---\n\n## What is DBOS?\n\nDBOS provides lightweight durable workflows built on top of Postgres.\nInstead of managing your own workflow orchestrator or task queue system, you can use DBOS to add durable workflows and queues to your program in just a few lines of code.\n\nTo get started, follow the [quickstart](https://docs.dbos.dev/quickstart) to install this open-source library and connect it to a Postgres database.\nThen, annotate workflows and steps in your program to make it durable!\nThat's all you need to do\u0026mdash;DBOS is entirely contained in this open-source library, there's no additional infrastructure for you to configure or manage.\n\n## When Should I Use DBOS?\n\nYou should consider using DBOS if your application needs to **reliably handle failures**.\nFor example, you might be building a payments service that must reliably process transactions even if servers crash mid-operation, or a long-running data pipeline that needs to resume seamlessly from checkpoints rather than restart from the beginning when interrupted.\n\nHandling failures is costly and complicated, requiring complex state management and recovery logic as well as heavyweight tools like external orchestration services.\nDBOS makes it simpler: annotate your code to checkpoint it in Postgres and automatically recover from any failure.\nDBOS also provides powerful Postgres-backed primitives that makes it easier to write and operate reliable code, including durable queues, notifications, scheduling, event processing, and programmatic workflow management.\n\n## Features\n\n\u003cdetails open\u003e\u003csummary\u003e\u003cstrong\u003e💾 Durable Workflows\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nDBOS workflows make your program **durable** by checkpointing its state in Postgres.\nIf your program ever fails, when it restarts all your workflows will automatically resume from the last completed step.\n\nYou add durable workflows to your existing Java program by annotating ordinary functions as workflows and steps:\n\n```java\n\npublic interface WorkflowService {\n    void setStepService(StepService stepService);\n    String exampleWorkflow(String input) ;\n}\n\npublic interface StepService {\n    void stepOne() ;\n    void stepTwo() ;\n}\n\npublic class WorkflowServiceImpl implements WorkflowService {\n\n    private Stepservice stepService;\n    public void setStepService(StepService stepService) {\n        this.stepService = stepService;\n    }\n    \n    @Workflow(name = \"exampleWorkflow\")\n    public String exampleWorkflow(String input) {\n        stepService.stepOne();\n        stepService.stepTwo();\n        return input + input;\n    }\n    \n}\n\npublic class StepServiceImpl implements StepService {\n\n    @Step(name = \"stepOne\")\n    public void stepOne() {\n        logger.info(\"Executed stepOne\") ;\n    }\n    @Step(name = \"stepTwo\")\n    public void stepTwo() {\n        logger.info(\"Executed stepTwo\") ;\n    }\n    \n}\n\npublic class Demo {\n    \n    public static void main(String[] args) {\n        \n        DBOSConfig dbosConfig = new DBOSConfig.Builder()\n                .name(\"demo\")\n                .dbHost(\"localhost\")\n                .dbPort(5432)\n                .dbUser(\"postgres\")\n                .sysDbName(\"demo_dbos_sys\")\n                .build() ;\n        // Remember to export the DB password to the env variable PGPASSWORD\n\n        DBOS dbos = DBOS.initialize(dbosConfig);\n        dbos.launch();\n        \n        WorkflowService syncExample = dbos.\u003cWorkflowService\u003eWorkflow()\n                .interfaceClass(WorkflowService.class)\n                .implementation(new WorkflowServiceImpl())\n                .build();\n\n        StepService steps = dbos.\u003cStepService\u003eWorkflow()\n                .interfaceClass(StepService.class)\n                .implementation(new StepServiceImpl())\n                .build();\n        \n        syncExample.setStepService(steps);\n\n        String output = syncExample.exampleWorkflow(\"HelloDBOS\") ;\n        System.out.println(\"Sync result: \" + output);\n    }\n}\n\n\n```\n\nWorkflows are particularly useful for\n\n- Orchestrating business processes so they seamlessly recover from any failure.\n- Building observable and fault-tolerant data pipelines.\n- Operating an AI agent, or any application that relies on unreliable or non-deterministic APIs.\n\n[Read more ↗️]()\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003e📒 Durable Queues\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nDBOS queues help you **durably** run tasks in the background.\nYou can enqueue a task (which can be a single step or an entire workflow) from a durable workflow and one of your processes will pick it up for execution.\nDBOS manages the execution of your tasks: it guarantees that tasks complete, and that their callers get their results without needing to resubmit them, even if your application is interrupted.\n\nQueues also provide flow control, so you can limit the concurrency of your tasks on a per-queue or per-process basis.\nYou can also set timeouts for tasks, rate limit how often queued tasks are executed, deduplicate tasks, or prioritize tasks.\n\nYou can add queues to your workflows in just a couple lines of code.\nThey don't require a separate queueing service or message broker\u0026mdash;just Postgres.\n\n```java\n\n\n public void queuedTasks() {\n     Queue q = dbos.Queue(\"childQ\").build();\n\n     for (int i = 0; i \u003c 3; i++) {\n\n         String wid = \"child\" + i;\n         DBOSOptions options = new DBOSOptions.Builder(wid).queue(q).build();\n         List\u003cWorkflowHandle\u003cString\u003e\u003e handles = new ArrayList\u003c\u003e();\n         try (SetDBOSOptions o = new SetDBOSOptions(options)) {\n             handles.add(dbos.startWorkflow(()-\u003esimpleService.childWorkflow(wid)));\n         }\n     }\n\n     for (int i = 0 ; i \u003c 3 ; i++) {\n         String wid = \"child\"+i;\n         System.out.println(h.getResult());\n     }\n }\n```\n\n[Read more ↗️](https://docs.dbos.dev/python/tutorials/queue-tutorial)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003e📒 Asynchronous execution \u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nDBOS can run your workflows asynchronously without you needing to make any changes to the interface or implementation. \n\nThis is ideal for long-running workflows whose result might not be available immediately. \nYou code can return at a later point and check the status for completion and/or retrive the result.\n\n\n```java\n\n\n public void runAsyncWorkflow() {\n\n     WorkflowService asyncExample = dbos.\u003cWorkflowService\u003eWorkflow()\n             .interfaceClass(WorkflowService.class)\n             .implementation(new WorkflowServiceImpl())\n             .build();\n\n     StepService steps = dbos.\u003cStepService\u003eWorkflow()\n             .interfaceClass(StepService.class)\n             .implementation(new StepServiceImpl())\n             .build();\n\n     syncExample.setStepService(steps);\n\n     String workflowId = \"wf-124\";\n     options = new DBOSOptions.Builder(workflowId).async().build();\n     WorkflowHandle\u003cString\u003e handle = null;\n     try (SetDBOSOptions id = new SetDBOSOptions(options)) {\n         handle = dbos.startWorkflow(()-\u003esyncExample.exampleWorkflow(\"HelloDBOS\"));\n     }\n     \n     result = handle.getResult();\n }\n```\n\n[Read more ↗️](https://docs.dbos.dev/python/tutorials/queue-tutorial)\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003e📅 Durable Scheduling\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nSchedule workflows using cron syntax, or use durable sleep to pause workflows for as long as you like (even days or weeks) before executing.\n\nYou can schedule a workflow using a single annotation:\n\n```java\n\npublic class SchedulerImpl {\n    \n    @Workflow(name = \"every5Second\")\n    @Scheduled(cron = \"0/5 * * * * ?\")\n    public void every5Second(Instant schedule , Instant actual) {\n        log.info(\"Executed workflow  \"+  schedule.toString() + \"   \" + actual.toString()) ;\n    }\n}\n\n// In your main\n// dbos.scheduleWorkflow(new SchedulerImpl());\n```\n\n[Read more ↗️](https://docs.dbos.dev/python/tutorials/scheduled-workflows)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003e📫 Durable Notifications\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nPause your workflow executions until a notification is received, or emit events from your workflow to send progress updates to external clients.\nAll notifications are stored in Postgres, so they can be sent and received with exactly-once semantics.\nSet durable timeouts when waiting for events, so you can wait for as long as you like (even days or weeks) through interruptions or restarts, then resume once a notification arrives or the timeout is reached.\n\nFor example, build a reliable billing workflow that durably waits for a notification from a payments service, processing it exactly-once:\n\n```java\n@workflow(name = \"billing\")\npublic void billingWorkflow() {\n    // retrieve DBOS instance from context\n    var dbos = DBOSContext.dbosInstance().get();\n\n    // Calculate the charge, then submit the bill to a payments service\n    String payment_status = (String) dbos.recv(PAYMENT_STATUS, timeout = payment_service_timeout);\n    if (payment_status.equals(\"paid\")) {\n        // handle paid\n    } else {\n        // handle not paid\n    }\n}\n\n@workflow(name = \"payment\") \npublic void payment() {\n    var dbos = DBOSContext.dbosInstance().get();\n    dbos.send(targetWorkflowId, PAYMENT_STATUS, \"paid\") ;\n}\n      \n```\n\u003c/details\u003e\n\n\n## Getting Started\n\nTo get started, follow the [quickstart](https://docs.dbos.dev/quickstart) to install this open-source library and connect it to a Postgres database.\nThen, check out the [programming guide](https://docs.dbos.dev/python/programming-guide) to learn how to build with durable workflows and queues.\n\n## Documentation\n\n[https://docs.dbos.dev](https://docs.dbos.dev)\n\n## Examples\n\n[https://docs.dbos.dev/examples](https://docs.dbos.dev/examples)\n\n## DBOS vs. Other Systems\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eDBOS vs. Temporal\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nBoth DBOS and Temporal provide durable execution, but DBOS is implemented in a lightweight Postgres-backed library whereas Temporal is implemented in an externally orchestrated server.\n\nYou can add DBOS to your program by installing this open-source library, connecting it to Postgres, and annotating workflows and steps.\nBy contrast, to add Temporal to your program, you must rearchitect your program to move your workflows and steps (activities) to a Temporal worker, configure a Temporal server to orchestrate those workflows, and access your workflows only through a Temporal client.\n[This blog post](https://www.dbos.dev/blog/durable-execution-coding-comparison) makes the comparison in more detail.\n\n**When to use DBOS:** You need to add durable workflows to your applications with minimal rearchitecting, or you are using Postgres.\n\n**When to use Temporal:** You don't want to add Postgres to your stack, or you need a language DBOS doesn't support yet.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eDBOS vs. Airflow\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nDBOS and Airflow both provide workflow abstractions.\nAirflow is targeted at data science use cases, providing many out-of-the-box connectors but requiring workflows be written as explicit DAGs and externally orchestrating them from an Airflow cluster.\nAirflow is designed for batch operations and does not provide good performance for streaming or real-time use cases.\nDBOS is general-purpose, but is often used for data pipelines, allowing developers to write workflows as code and requiring no infrastructure except Postgres.\n\n**When to use DBOS:** You need the flexibility of writing workflows as code, or you need higher performance than Airflow is capable of (particularly for streaming or real-time use cases).\n\n**When to use Airflow:** You need Airflow's ecosystem of connectors.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eDBOS vs. Celery/BullMQ\u003c/strong\u003e\u003c/summary\u003e\n\n####\n\nDBOS provides a similar queue abstraction to dedicated queueing systems like Celery or BullMQ: you can declare queues, submit tasks to them, and control their flow with concurrency limits, rate limits, timeouts, prioritization, etc.\nHowever, DBOS queues are **durable and Postgres-backed** and integrate with durable workflows.\nFor example, in DBOS you can write a durable workflow that enqueues a thousand tasks and waits for their results.\nDBOS checkpoints the workflow and each of its tasks in Postgres, guaranteeing that even if failures or interruptions occur, the tasks will complete and the workflow will collect their results.\nBy contrast, Celery/BullMQ are Redis-backed and don't provide workflows, so they provide fewer guarantees but better performance.\n\n**When to use DBOS:** You need the reliability of enqueueing tasks from durable workflows.\n\n**When to use Celery/BullMQ**: You don't need durability, or you need very high throughput beyond what your Postgres server can support.\n\u003c/details\u003e\n\n## Community\n\nIf you want to ask questions or hang out with the community, join us on [Discord](https://discord.gg/fMwQjeW5zg)!\nIf you see a bug or have a feature request, don't hesitate to open an issue here on GitHub.\nIf you're interested in contributing, check out our [contributions guide](./CONTRIBUTING.md).\n\n\n\n\n\n\n","funding_links":[],"categories":["\u003ca name=\"Java\"\u003e\u003c/a\u003eJava"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbos-inc%2Fdbos-transact-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbos-inc%2Fdbos-transact-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbos-inc%2Fdbos-transact-java/lists"}