Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 159 additions & 0 deletions adapters/sqlite/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
# SQLite Adapter

A pure Go SQLite implementation for the workflow library's `RecordStore`, `TimeoutStore`, and `EventStreamer` interfaces.

## Features

- **Pure Go**: Uses `modernc.org/sqlite` (no CGO dependencies)
- **Complete Implementation**: All three core interfaces supported
- **Minimal Dependencies**: Only SQLite driver and workflow library
- **Optimized Configuration**: WAL mode, proper pragmas, and retry logic
- **Thread-Safe**: Safe for concurrent use within SQLite's limitations

## Interfaces Implemented

- ✅ **RecordStore**: Store and retrieve workflow records with transactional outbox pattern
- ✅ **TimeoutStore**: Manage workflow timeouts with expiration tracking
- ✅ **EventStreamer**: Event streaming with SQLite-based persistence and cursor tracking

## Installation

```go
go get github.com/luno/workflow/adapters/sqlite
```

## Quick Start

```go
package main

import (
"context"
"log"

"github.com/luno/workflow/adapters/sqlite"
)

func main() {
// Open database with optimized settings
db, err := sqlite.Open("workflow.db")
if err != nil {
log.Fatal(err)
}
defer db.Close()

// Initialize schema
if err := sqlite.InitSchema(db); err != nil {
log.Fatal(err)
}

// Create adapters
recordStore := sqlite.NewRecordStore(db)
timeoutStore := sqlite.NewTimeoutStore(db)
eventStreamer := sqlite.NewEventStreamer(db)

// Use with workflow builder
// builder := workflow.NewBuilder[MyType](...)
// .AddRecordStore(recordStore)
// .AddTimeoutStore(timeoutStore)
// .AddEventStreamer(eventStreamer)
}
```

## Configuration

The `sqlite.Open()` function automatically configures SQLite for optimal workflow usage:

- **WAL Mode**: Write-Ahead Logging for better concurrency
- **Busy Timeout**: 5-second wait for database locks
- **Cache Size**: Increased for better performance
- **Single Connection**: Optimized for SQLite's architecture

## Schema

The adapter creates these tables automatically:

- `workflow_records`: Store workflow execution records
- `workflow_outbox`: Transactional outbox for events
- `workflow_timeouts`: Timeout tracking with expiration
- `workflow_events`: Event streaming log
- `workflow_cursors`: Consumer position tracking

## Usage Notes

### Concurrency Limitations

SQLite is designed for single-writer scenarios. While this adapter includes retry logic and optimizations:

- ✅ **Good for**: Single-node applications, moderate load, development/testing
- ⚠️ **Limited**: High-concurrency scenarios with many concurrent writers
- ❌ **Not for**: Multi-node deployments, high-throughput production systems

For high-concurrency scenarios, consider:
- `sqlstore` + `sqltimeout` (MySQL/PostgreSQL)
- `reflexstreamer` (dedicated event streaming)
- `kafkastreamer` (Kafka-based streaming)

### Event Streaming

The EventStreamer implementation:
- Stores events in SQLite tables (not in-memory)
- Supports `StreamFromLatest()` option
- Uses polling-based consumption (10ms intervals by default)
- Includes automatic retry logic for database locks

### Error Handling

The adapter includes retry logic for common SQLite contention issues:
- Automatic retry on `SQLITE_BUSY` errors
- Exponential backoff for lock conflicts
- Graceful handling of concurrent access patterns

## Testing

All adapters are tested against the standard adapter test suite:

```bash
go test -v
```

**Note**: The full `RunEventStreamerTest` may timeout in high-concurrency scenarios due to SQLite's single-writer nature. Individual interface tests pass completely.

## Performance Characteristics

- **Read Performance**: Excellent with proper indexing
- **Write Performance**: Good for moderate loads
- **Concurrent Reads**: Supported via WAL mode
- **Concurrent Writes**: Limited by SQLite's single-writer design
- **Storage**: Efficient, single-file database

## Best Practices

1. **Use for appropriate workloads**: Single-node, moderate concurrency
2. **Monitor database size**: SQLite can handle large databases efficiently
3. **Regular maintenance**: Use `PRAGMA optimize` periodically
4. **Backup strategy**: Simple file-based backups work well
5. **Connection management**: Use single connection per process

## Comparison with Other Adapters

| Feature | SQLite | SQL + Timeout | Reflex + Kafka | In-Memory |
|---------|---------|---------------|----------------|-----------|
| Setup Complexity | Low | Medium | High | None |
| Production Ready | Limited | Yes | Yes | No |
| Multi-Node | No | Yes | Yes | No |
| Persistence | Yes | Yes | Yes | No |
| High Concurrency | No | Yes | Yes | Yes |

## Contributing

This adapter follows the same patterns as other workflow adapters. When contributing:

1. Run the full test suite
2. Follow existing error handling patterns
3. Maintain compatibility with the workflow interfaces
4. Update documentation for any new features

## License

Same as the workflow library.
80 changes: 80 additions & 0 deletions adapters/sqlite/example_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
package sqlite_test

import (
"context"
"path/filepath"
"testing"
"time"

"github.com/luno/workflow"
"github.com/stretchr/testify/require"

"github.com/luno/workflow/adapters/sqlite"
)

func TestSQLiteAdapterExample(t *testing.T) {
// Create a temporary database
tempDir := t.TempDir()
dbPath := filepath.Join(tempDir, "example.db")

// Open SQLite database with optimized settings
db, err := sqlite.Open(dbPath)
require.NoError(t, err)
defer db.Close()

// Initialize schema
err = sqlite.InitSchema(db)
require.NoError(t, err)

// Create adapters
recordStore := sqlite.NewRecordStore(db)
timeoutStore := sqlite.NewTimeoutStore(db)
eventStreamer := sqlite.NewEventStreamer(db)

ctx := context.Background()

// Example: RecordStore usage
record := &workflow.Record{
WorkflowName: "example_workflow",
ForeignID: "user-123",
RunID: "run-456",
RunState: workflow.RunStateInitiated,
Status: 1,
Object: []byte(`{"data":"example"}`),
Meta: workflow.Meta{StatusDescription: "example status"},
}

err = recordStore.Store(ctx, record)
require.NoError(t, err)

// Lookup record
retrieved, err := recordStore.Lookup(ctx, "run-456")
require.NoError(t, err)
require.Equal(t, "user-123", retrieved.ForeignID)

// Example: TimeoutStore usage
expireAt := time.Now().Add(1 * time.Hour)
err = timeoutStore.Create(ctx, "example_workflow", "user-123", "run-456", 1, expireAt)
require.NoError(t, err)

timeouts, err := timeoutStore.List(ctx, "example_workflow")
require.NoError(t, err)
require.Len(t, timeouts, 1)

// Example: EventStreamer usage (basic)
sender, err := eventStreamer.NewSender(ctx, "example_topic")
require.NoError(t, err)
defer sender.Close()

headers := map[workflow.Header]string{
workflow.HeaderTopic: "example_topic",
workflow.HeaderWorkflowName: "example_workflow",
workflow.HeaderForeignID: "user-123",
}

err = sender.Send(ctx, "user-123", 1, headers)
require.NoError(t, err)

t.Log("SQLite adapters created successfully!")
t.Log("Database file:", dbPath)
}
40 changes: 40 additions & 0 deletions adapters/sqlite/go.mod
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
module github.com/luno/workflow/adapters/sqlite

go 1.24.2

replace github.com/luno/workflow => ../..

require (
github.com/luno/workflow v0.3.0
github.com/stretchr/testify v1.10.0
modernc.org/sqlite v1.34.4
)

require (
github.com/beorn7/perks v1.0.1 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
github.com/ncruces/go-strftime v0.1.9 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/prometheus/client_golang v1.22.0 // indirect
github.com/prometheus/client_model v0.6.1 // indirect
github.com/prometheus/common v0.62.0 // indirect
github.com/prometheus/procfs v0.15.1 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
golang.org/x/exp v0.0.0-20231108232855-2478ac86f678 // indirect
golang.org/x/sys v0.31.0 // indirect
google.golang.org/protobuf v1.36.6 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
k8s.io/utils v0.0.0-20240921022957-49e7df575cb6 // indirect
modernc.org/gc/v3 v3.0.0-20241004144649-1aea3fae8852 // indirect
modernc.org/libc v1.61.4 // indirect
modernc.org/mathutil v1.6.0 // indirect
modernc.org/memory v1.8.0 // indirect
modernc.org/strutil v1.2.0 // indirect
modernc.org/token v1.1.0 // indirect
)
90 changes: 90 additions & 0 deletions adapters/sqlite/go.sum
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd h1:gbpYu9NMq8jhDVbvlGkMFWCjLFlqqEZjEmObmhUy6Vo=
github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd/go.mod h1:kf6iHlnVGwgKolg33glAes7Yg/8iWP8ukqeldJSO7jw=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/prometheus/client_golang v1.22.0 h1:rb93p9lokFEsctTys46VnV1kLCDpVZ0a/Y92Vm0Zc6Q=
github.com/prometheus/client_golang v1.22.0/go.mod h1:R7ljNsLXhuQXYZYtw6GAE9AZg8Y7vEW5scdCXrWRXC0=
github.com/prometheus/client_model v0.6.1 h1:ZKSh/rekM+n3CeS952MLRAdFwIKqeY8b62p8ais2e9E=
github.com/prometheus/client_model v0.6.1/go.mod h1:OrxVMOVHjw3lKMa8+x6HeMGkHMQyHDk9E3jmP2AmGiY=
github.com/prometheus/common v0.62.0 h1:xasJaQlnWAeyHdUBeGjXmutelfJHWMRr+Fg4QszZ2Io=
github.com/prometheus/common v0.62.0/go.mod h1:vyBcEuLSvWos9B1+CyL7JZ2up+uFzXhkqml0W5zIY1I=
github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
golang.org/x/exp v0.0.0-20231108232855-2478ac86f678 h1:mchzmB1XO2pMaKFRqk/+MV3mgGG96aqaPXaMifQU47w=
golang.org/x/exp v0.0.0-20231108232855-2478ac86f678/go.mod h1:zk2irFbV9DP96SEBUUAy67IdHUaZuSnrz1n472HUCLE=
golang.org/x/mod v0.19.0 h1:fEdghXQSo20giMthA7cd28ZC+jts4amQ3YMXiP5oMQ8=
golang.org/x/mod v0.19.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
golang.org/x/tools v0.23.0 h1:SGsXPZ+2l4JsgaCKkx+FQ9YZ5XEtA1GZYuoDjenLjvg=
golang.org/x/tools v0.23.0/go.mod h1:pnu6ufv6vQkll6szChhK3C3L/ruaIv5eBeztNG8wtsI=
google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
k8s.io/utils v0.0.0-20240921022957-49e7df575cb6 h1:MDF6h2H/h4tbzmtIKTuctcwZmY0tY9mD9fNT47QO6HI=
k8s.io/utils v0.0.0-20240921022957-49e7df575cb6/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=
modernc.org/cc/v4 v4.23.1 h1:WqJoPL3x4cUufQVHkXpXX7ThFJ1C4ik80i2eXEXbhD8=
modernc.org/cc/v4 v4.23.1/go.mod h1:HM7VJTZbUCR3rV8EYBi9wxnJ0ZBRiGE5OeGXNA0IsLQ=
modernc.org/ccgo/v4 v4.23.1 h1:N49a7JiWGWV7lkPE4yYcvjkBGZQi93/JabRYjdWmJXc=
modernc.org/ccgo/v4 v4.23.1/go.mod h1:JoIUegEIfutvoWV/BBfDFpPpfR2nc3U0jKucGcbmwDU=
modernc.org/fileutil v1.3.0 h1:gQ5SIzK3H9kdfai/5x41oQiKValumqNTDXMvKo62HvE=
modernc.org/fileutil v1.3.0/go.mod h1:XatxS8fZi3pS8/hKG2GH/ArUogfxjpEKs3Ku3aK4JyQ=
modernc.org/gc/v2 v2.5.0 h1:bJ9ChznK1L1mUtAQtxi0wi5AtAs5jQuw4PrPHO5pb6M=
modernc.org/gc/v2 v2.5.0/go.mod h1:wzN5dK1AzVGoH6XOzc3YZ+ey/jPgYHLuVckd62P0GYU=
modernc.org/gc/v3 v3.0.0-20241004144649-1aea3fae8852 h1:IYXPPTTjjoSHvUClZIYexDiO7g+4x+XveKT4gCIAwiY=
modernc.org/gc/v3 v3.0.0-20241004144649-1aea3fae8852/go.mod h1:Qz0X07sNOR1jWYCrJMEnbW/X55x206Q7Vt4mz6/wHp4=
modernc.org/libc v1.61.4 h1:wVyqEx6tlltte9lPTjq0kDAdtdM9c4JH8rU6M1ZVawA=
modernc.org/libc v1.61.4/go.mod h1:VfXVuM/Shh5XsMNrh3C6OkfL78G3loa4ZC/Ljv9k7xc=
modernc.org/mathutil v1.6.0 h1:fRe9+AmYlaej+64JsEEhoWuAYBkOtQiMEU7n/XgfYi4=
modernc.org/mathutil v1.6.0/go.mod h1:Ui5Q9q1TR2gFm0AQRqQUaBWFLAhQpCwNcuhBOSedWPo=
modernc.org/memory v1.8.0 h1:IqGTL6eFMaDZZhEWwcREgeMXYwmW83LYW8cROZYkg+E=
modernc.org/memory v1.8.0/go.mod h1:XPZ936zp5OMKGWPqbD3JShgd/ZoQ7899TUuQqxY+peU=
modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
modernc.org/sortutil v1.2.0 h1:jQiD3PfS2REGJNzNCMMaLSp/wdMNieTbKX920Cqdgqc=
modernc.org/sortutil v1.2.0/go.mod h1:TKU2s7kJMf1AE84OoiGppNHJwvB753OYfNl2WRb++Ss=
modernc.org/sqlite v1.34.4 h1:sjdARozcL5KJBvYQvLlZEmctRgW9xqIZc2ncN7PU0P8=
modernc.org/sqlite v1.34.4/go.mod h1:3QQFCG2SEMtc2nv+Wq4cQCH7Hjcg+p/RMlS1XK+zwbk=
modernc.org/strutil v1.2.0 h1:agBi9dp1I+eOnxXeiZawM8F4LawKv4NzGWSaLfyeNZA=
modernc.org/strutil v1.2.0/go.mod h1:/mdcBmfOibveCTBxUl5B5l6W+TTH1FXPLHZE6bTosX0=
modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
Loading
Loading