temporalite

README

Temporalite

⚠️ This project is experimental and not suitable for production use. ⚠️

Temporalite is a distribution of Temporal that runs as a single process with zero runtime dependencies.

Persistence to disk and an in-memory mode are both supported via SQLite.

Check out this video for a brief introduction and demo: youtu.be/Hz7ZZzafBoE [16:13] -- demo starts at 11:28

Why

The primary goal of Temporalite is to make it simple and fast to run Temporal locally or in testing environments.

Features that align with this goal:

• Easy setup and teardown
• Fast startup time
• Minimal resource overhead: no dependencies on a container runtime or database server
• Support for Windows, Linux, and macOS
• Ships with a web interface

Getting Started

Download and Start Temporal Server Locally

Download and extract the latest release from GitHub releases.

Start Temporal server:

temporalite start --namespace default

At this point you should have a server running on localhost:7233 and a web interface at http://localhost:8233.

Use CLI

Use Temporal's command line tool tctl to interact with the local Temporalite server.

tctl namespace list
tctl workflow list

Configuration

Use the help flag to see all available options:

temporalite start -h

Namespace Registration

Namespaces can be pre-registered at startup so they're available to use right away:

temporalite start --namespace foo --namespace bar

Registering namespaces the old-fashioned way via tctl --namespace foo namespace register works too!

Persistence Modes

File on Disk

By default temporalite persists state to a file in the current user's config directory. This path may be overridden:

temporalite start -f my_test.db

Ephemeral

An in-memory mode is also available. Note that all data will be lost on each restart.

temporalite start --ephemeral

Web UI

By default the web UI is started with Temporalite. The UI can be disabled via a runtime flag:

temporalite start --headless

To build without static UI assets, use the headless build tag when running go build.

Dynamic Config

Some advanced uses require Temporal dynamic configuration values which are usually set via a dynamic configuration file inside the Temporal configuration file. Alternatively, dynamic configuration values can be set via --dynamic-config-value KEY=JSON_VALUE.

For example, to disable search attribute cache to make created search attributes available for use right away:

temporalite start --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=true

Development

To compile the source run:

go build -o dist/temporalite ./cmd/temporalite 

To run all tests:

go test ./...

Known Issues

• When consuming Temporalite as a library in go mod, you may want to replace grpc-gateway with a fork to address URL escaping issue in UI. See https://github.com/temporalio/temporalite/pull/118

Documentation

Index

• type Server
  • func NewServer(opts ...ServerOption) (*Server, error)
  • func (s *Server) FrontendHostPort() string
  • func (s *Server) NewClient(ctx context.Context, namespace string) (client.Client, error)
  • func (s *Server) NewClientWithOptions(ctx context.Context, options client.Options) (client.Client, error)
  • func (s *Server) Start() error
  • func (s *Server) Stop()
• type ServerOption
  • func WithBaseConfig(base *config.Config) ServerOption
  • func WithDatabaseFilePath(filepath string) ServerOption
  • func WithDynamicConfigValue(key dynamicconfig.Key, value []dynamicconfig.ConstrainedValue) ServerOption
  • func WithDynamicPorts() ServerOption
  • func WithFrontendIP(address string) ServerOption
  • func WithFrontendPort(port int) ServerOption
  • func WithLogger(logger log.Logger) ServerOption
  • func WithMetricsPort(port int) ServerOption
  • func WithNamespaces(namespaces ...string) ServerOption
  • func WithPersistenceDisabled() ServerOption
  • func WithSQLitePragmas(pragmas map[string]string) ServerOption
  • func WithSearchAttributeCacheDisabled() ServerOption
  • func WithUI(server liteconfig.UIServer) ServerOption
  • func WithUpstreamOptions(options ...temporal.ServerOption) ServerOption

Types

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps temporal.Server.

func NewServer

func NewServer(opts ...ServerOption) (*Server, error)

NewServer returns a new instance of Server.

func (*Server) FrontendHostPort

func (s *Server) FrontendHostPort() string

FrontendHostPort returns the host:port for this server.

When constructing a Temporalite client from within the same process, NewClient or NewClientWithOptions should be used instead.

func (*Server) NewClient

func (s *Server) NewClient(ctx context.Context, namespace string) (client.Client, error)

NewClient initializes a client ready to communicate with the Temporal server in the target namespace.

func (*Server) NewClientWithOptions

func (s *Server) NewClientWithOptions(ctx context.Context, options client.Options) (client.Client, error)

NewClientWithOptions is the same as NewClient but allows further customization.

To set the client's namespace, use the corresponding field in client.Options.

Note that the HostPort and ConnectionOptions fields of client.Options will always be overridden.

func (*Server) Start

func (s *Server) Start() error

Start temporal server.

func (*Server) Stop

func (s *Server) Stop()

Stop the server.

type ServerOption

type ServerOption interface {
	// contains filtered or unexported methods
}

func WithBaseConfig

func WithBaseConfig(base *config.Config) ServerOption

WithBaseConfig sets the default Temporal server configuration.

Storage and client configuration will always be overridden, however base config can be used to enable settings like TLS or authentication.

func WithDatabaseFilePath

func WithDatabaseFilePath(filepath string) ServerOption

WithDatabaseFilePath persists state to the file at the specified path.

func WithDynamicConfigValue

func WithDynamicConfigValue(key dynamicconfig.Key, value []dynamicconfig.ConstrainedValue) ServerOption

WithDynamicConfigValue sets the given dynamic config key with the given set of values. This will overwrite the key if already set.

func WithDynamicPorts

func WithDynamicPorts() ServerOption

WithDynamicPorts starts Temporal on system-chosen ports.

func WithFrontendIP

func WithFrontendIP(address string) ServerOption

WithFrontendIP binds the temporal-frontend GRPC service to a specific IP (eg. `0.0.0.0`) Check net.ParseIP for supported syntax; only IPv4 is supported.

When unspecified, the frontend service will bind to localhost.

func WithFrontendPort

func WithFrontendPort(port int) ServerOption

WithFrontendPort sets the listening port for the temporal-frontend GRPC service.

When unspecified, the default port number of 7233 is used.

func WithLogger

func WithLogger(logger log.Logger) ServerOption

WithLogger overrides the default logger.

func WithMetricsPort

func WithMetricsPort(port int) ServerOption

WithMetricsPort sets the listening port for metrics.

When unspecified, the port will be system-chosen.

func WithNamespaces

func WithNamespaces(namespaces ...string) ServerOption

WithNamespaces registers each namespace on Temporal start.

func WithPersistenceDisabled

func WithPersistenceDisabled() ServerOption

WithPersistenceDisabled disables file persistence and uses the in-memory storage driver. State will be reset on each process restart.

func WithSQLitePragmas

func WithSQLitePragmas(pragmas map[string]string) ServerOption

WithSQLitePragmas applies pragma statements to SQLite on Temporal start.

func WithSearchAttributeCacheDisabled

func WithSearchAttributeCacheDisabled() ServerOption

WithSearchAttributeCacheDisabled disables search attribute caching. This delegates to WithDynamicConfigValue.

func WithUI

func WithUI(server liteconfig.UIServer) ServerOption

WithUI enables the Temporal web interface.

When unspecified, Temporal will run in headless mode.

This option accepts a UIServer implementation in order to avoid bloating programs that do not need to embed the UI. See ./cmd/temporalite/main.go for an example of usage.

func WithUpstreamOptions

func WithUpstreamOptions(options ...temporal.ServerOption) ServerOption

WithUpstreamOptions registers Temporal server options.