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

Build from source using go install:

Note: Go 1.18 or greater is currently required.

go install github.com/DataDog/temporalite/cmd/temporalite@latest

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

The temporalite binary can be compiled to omit static assets for installations that will never use the UI:

go install -tags headless github.com/DataDog/temporalite/cmd/temporalite@latest

The UI can also be disabled via a runtime flag:

temporalite start --headless

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 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 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 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 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.