Skip to content

Commit a5aeb48

Browse files
maxdmlmaxdml
authored
doc.go + a few scope updates (#125)
- Add an extensive `doc.go` with - Make conductor private - Add a `README.md `to the CLI
1 parent 42b5dc6 commit a5aeb48

File tree

8 files changed

+497
-290
lines changed

8 files changed

+497
-290
lines changed

‎README.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,6 @@
1212
#### [Documentation](https://docs.dbos.dev/)   •   [Examples](https://docs.dbos.dev/examples)   •   [Github](https://github.com/dbos-inc)
1313
</div>
1414

15-
#### This Golang version of DBOS Transact is in Alpha!
16-
For production ready Transacts, check our [Python](https://github.com/dbos-inc/dbos-transact-py) and [TypeScript](https://github.com/dbos-inc/dbos-transact-ts) versions.
17-
1815
---
1916

2017
## What is DBOS?
@@ -74,7 +71,7 @@ func stepTwo(ctx context.Context) (string, error) {
7471
}
7572
func main() {
7673
// Initialize a DBOS context
77-
ctx, err := dbos.NewDBOSContext(dbos.Config{
74+
ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
7875
DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
7976
AppName: "myapp",
8077
})
@@ -147,7 +144,7 @@ func task(ctx dbos.DBOSContext, i int) (int, error) {
147144

148145
func main() {
149146
// Initialize a DBOS context
150-
ctx, err := dbos.NewDBOSContext(dbos.Config{
147+
ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
151148
DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
152149
AppName: "myapp",
153150
})

‎cmd/dbos/README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# DBOS CLI
2+
3+
The DBOS CLI is a command-line interface for managing DBOS workflows.
4+
5+
## Installation
6+
7+
### From Source
8+
```bash
9+
go install github.com/dbos-inc/dbos-transact-golang/cmd/dbos
10+
```
11+
12+
### Build Locally
13+
```bash
14+
go build -o dbos .
15+
```
16+
17+
## Configuration
18+
19+
### Database URL Configuration
20+
21+
The CLI requires a DBOS system database URL to operate. The URL is resolved in the following order of precedence:
22+
23+
1. **Command-line flag**: `--db-url` or `-D` flag
24+
2. **Configuration file**: `database_url` field in `dbos-config.yaml`
25+
3. **Environment variable**: `DBOS_SYSTEM_DATABASE_URL`
26+
27+
Example:
28+
```bash
29+
# Using command-line flag (highest priority)
30+
dbos migrate --db-url postgres://user:pass@localhost/mydb
31+
32+
# Using config file (dbos-config.yaml)
33+
database_url: postgres://user:pass@localhost/mydb
34+
35+
# Using environment variable (lowest priority)
36+
export DBOS_SYSTEM_DATABASE_URL=postgres://user:pass@localhost/mydb
37+
dbos migrate
38+
```
39+
40+
### Configuration File
41+
42+
The CLI uses a `dbos-config.yaml` file for configuration. By default, it looks for this file in the current directory. You can specify a different config file using the `--config` flag.
43+
44+
```yaml
45+
name: my-dbos-app
46+
database_url: ${DBOS_SYSTEM_DATABASE_URL}
47+
48+
runtimeConfig:
49+
start:
50+
- go run .
51+
52+
database:
53+
migrate:
54+
- echo "Running migrations..."
55+
```
56+
57+
## Global Options
58+
59+
These options are available for all commands:
60+
61+
- `-D, --db-url <url>` - Your DBOS system database URL
62+
- `--config <file>` - Config file (default: dbos-config.yaml)
63+
- `--verbose` - Enable verbose mode (DEBUG level logging)
64+
65+
## Commands
66+
67+
### `dbos init [project-name]`
68+
Initialize a new DBOS application from a template.
69+
70+
**Usage:**
71+
```bash
72+
dbos init myapp
73+
```
74+
75+
Creates a new DBOS application with:
76+
- `main.go` - Entry point with example workflow
77+
- `go.mod` - Go module file
78+
- `dbos-config.yaml` - DBOS configuration
79+
80+
### `dbos migrate`
81+
Create DBOS system tables in your database. This command runs the migration commands specified in the `database.migrate` section of your config file.
82+
83+
**Options:**
84+
- `-r, --app-role <role>` - The role with which you will run your DBOS application
85+
86+
**Usage:**
87+
```bash
88+
dbos migrate
89+
dbos migrate --app-role myapp_role
90+
```
91+
92+
The migrate commands are defined in `dbos-config.yaml`:
93+
```yaml
94+
database:
95+
migrate:
96+
- echo "Running migrations..."
97+
- go run ./migrations
98+
```
99+
100+
### `dbos reset`
101+
Reset the DBOS system database, deleting metadata about past workflows and steps. _This is a permanent, destructive action!_
102+
103+
**Options:**
104+
- `-y, --yes` - Skip confirmation prompt
105+
106+
**Usage:**
107+
```bash
108+
dbos reset
109+
dbos reset --yes # Skip confirmation
110+
```
111+
112+
### `dbos start`
113+
Start your DBOS application using the start commands defined in the `runtimeConfig.start` section of your `dbos-config.yaml`.
114+
115+
**Usage:**
116+
```bash
117+
dbos start
118+
```
119+
120+
The start commands are defined in `dbos-config.yaml`:
121+
```yaml
122+
runtimeConfig:
123+
start:
124+
- go run .
125+
# Can have multiple commands that run in sequence
126+
```
127+
128+
### `dbos postgres`
129+
Manage a local PostgreSQL database with Docker for development.
130+
131+
#### `dbos postgres start`
132+
Start a local Postgres database container with pgvector extension.
133+
134+
**Usage:**
135+
```bash
136+
dbos postgres start
137+
```
138+
139+
Creates a PostgreSQL container with:
140+
- Container name: `dbos-db`
141+
- Port: 5432
142+
- Default database: `dbos`
143+
- Default user: `postgres`
144+
- Default password: `dbos`
145+
146+
#### `dbos postgres stop`
147+
Stop the local Postgres database container.
148+
149+
**Usage:**
150+
```bash
151+
dbos postgres stop
152+
```
153+
154+
### `dbos workflow`
155+
Manage DBOS workflows.
156+
157+
#### `dbos workflow list`
158+
List workflows for your application.
159+
160+
**Options:**
161+
- `-l, --limit <number>` - Limit the results returned (default: 10)
162+
- `-o, --offset <number>` - Offset for pagination
163+
- `-S, --status <status>` - Filter by status (PENDING, SUCCESS, ERROR, ENQUEUED, CANCELLED, or MAX_RECOVERY_ATTEMPTS_EXCEEDED)
164+
- `-n, --name <name>` - Retrieve workflows with this name
165+
- `-u, --user <user>` - Retrieve workflows run by this user
166+
- `-v, --application-version <version>` - Retrieve workflows with this application version
167+
- `-s, --start-time <timestamp>` - Retrieve workflows starting after this timestamp (ISO 8601)
168+
- `-e, --end-time <timestamp>` - Retrieve workflows starting before this timestamp (ISO 8601)
169+
- `-q, --queue <queue>` - Retrieve workflows on this queue
170+
- `-Q, --queues-only` - Retrieve only queued workflows
171+
- `-d, --sort-desc` - Sort the results in descending order (older first)
172+
173+
**Usage:**
174+
```bash
175+
dbos workflow list
176+
dbos workflow list --limit 50 --status SUCCESS
177+
dbos workflow list --name "ProcessOrder" --user "admin"
178+
```
179+
180+
#### `dbos workflow get [workflow-id]`
181+
Retrieve the status of a specific workflow.
182+
183+
**Usage:**
184+
```bash
185+
dbos workflow get abc123def456
186+
```
187+
188+
Returns detailed information about the workflow including its status, start time, end time, and other metadata.
189+
190+
#### `dbos workflow steps [workflow-id]`
191+
List the steps of a workflow.
192+
193+
**Usage:**
194+
```bash
195+
dbos workflow steps abc123def456
196+
```
197+
198+
Shows all the steps executed within a workflow, their status, and execution details.
199+
200+
#### `dbos workflow cancel [workflow-id]`
201+
Cancel a workflow so it is no longer automatically retried or restarted.
202+
203+
**Usage:**
204+
```bash
205+
dbos workflow cancel abc123def456
206+
```
207+
208+
#### `dbos workflow resume [workflow-id]`
209+
Resume a workflow that has been cancelled.
210+
211+
**Usage:**
212+
```bash
213+
dbos workflow resume abc123def456
214+
```
215+
216+
#### `dbos workflow fork [workflow-id]`
217+
Fork a workflow from the beginning or from a specific step.
218+
219+
**Options:**
220+
- `-s, --step <number>` - Restart from this step (default: 1)
221+
- `-f, --forked-workflow-id <id>` - Custom workflow ID for the forked workflow
222+
- `-a, --application-version <version>` - Application version for the forked workflow
223+
224+
**Usage:**
225+
```bash
226+
dbos workflow fork abc123def456
227+
dbos workflow fork abc123def456 --step 3
228+
dbos workflow fork abc123def456 --forked-workflow-id custom-id-123
229+
```
230+
231+
### `dbos version`
232+
Show the version and exit.
233+
234+
**Usage:**
235+
```bash
236+
dbos version
237+
```
238+
239+
## License
240+
241+
See the main project LICENSE file for details.

‎dbos/conductor.go‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ const (
2626
_WRITE_DEADLINE = 5 * time.Second
2727
)
2828

29-
// ConductorConfig contains configuration for the conductor
30-
type ConductorConfig struct {
29+
// conductorConfig contains configuration for the conductor
30+
type conductorConfig struct {
3131
url string
3232
apiKey string
3333
appName string
@@ -55,14 +55,14 @@ type Conductor struct {
5555
pingCancel context.CancelFunc
5656
}
5757

58-
// Launch starts the conductor main goroutine
59-
func (c *Conductor) Launch() {
58+
// launch starts the conductor main goroutine
59+
func (c *Conductor) launch() {
6060
c.logger.Info("Launching conductor")
6161
c.wg.Add(1)
6262
go c.run()
6363
}
6464

65-
func NewConductor(dbosCtx *dbosContext, config ConductorConfig) (*Conductor, error) {
65+
func newConductor(dbosCtx *dbosContext, config conductorConfig) (*Conductor, error) {
6666
if config.apiKey == "" {
6767
return nil, fmt.Errorf("conductor API key is required")
6868
}
@@ -96,7 +96,7 @@ func NewConductor(dbosCtx *dbosContext, config ConductorConfig) (*Conductor, err
9696
return c, nil
9797
}
9898

99-
func (c *Conductor) Shutdown(timeout time.Duration) {
99+
func (c *Conductor) shutdown(timeout time.Duration) {
100100
c.stopOnce.Do(func() {
101101
if c.pingCancel != nil {
102102
c.pingCancel()

0 commit comments

Comments
 (0)