Replace echo stub with database components

5 components for Postgres + Redis:
- postgres_exec: INSERT/UPDATE/DELETE with positional params
- postgres_query: SELECT with configurable row shape
- redis_dedup: SET NX EX, routes new vs seen
- redis_set, redis_get: primitives

Connection pools (pgxpool, go-redis) cached per DSN/URL across calls.
Credentials flow in via the input message, not component settings.

Author: tpoxa

README.md

@@ -1,70 +1,60 @@
-# Tiny Systems Example Module
+# Tiny Systems Database Module
 
-Template repository for building your own Tiny Systems module. Fork this repo to get started.
+Postgres and Redis components for Tiny Systems flows.
 
-## What's Included
+## Components
 
-A minimal Echo component that receives a message and passes it through:
+| Name | Purpose |
+|---|---|
+| `postgres_exec` | Run INSERT/UPDATE/DELETE with positional parameters; emits `rowsAffected`. |
+| `postgres_query` | Run SELECT; emits `rows[]` keyed by column name with a configurable row shape. |
+| `redis_dedup` | Atomic "first seen" check via `SET NX EX`; routes new IDs to **out_new** and duplicates to **out_seen**. |
+| `redis_set` | Set a key, with optional TTL and NX. |
+| `redis_get` | Get a key, returns `found=false` for missing keys without raising an error. |
+
+All components take their connection string (`dsn` for Postgres, `url` for Redis) **per message**, so a single deployed module can talk to many databases. Connections are pooled by DSN/URL across calls.
+
+## Patterns
+
+### Dedup-then-route
 
-```go
-func (t *Component) Handle(ctx context.Context, handler module.Handler, port string, msg interface{}) any {
-    if in, ok := msg.(InMessage); ok {
-        return handler(ctx, OutPort, in.Context)
-    }
-    return fmt.Errorf("invalid message")
-}
+```
+ticker → http_request(api) → json_decode → array_split → redis_dedup
+                                                            ├── out_new  → … process and store ──→ postgres_exec
+                                                            └── out_seen → drop
 ```
 
-This demonstrates the core patterns:
-- Component interface (`GetInfo`, `Handle`, `Ports`, `Instance`)
-- Input/output ports with typed messages
-- Handler response propagation (blocking I/O)
-- `configurable:"true"` struct tag for edge data mapping
+Use `redis_dedup` for "have I already processed this ID?" checks. `keyPrefix` + `id` form the composite key. TTL determines how long Redis remembers — set it longer than the polling cycle plus margin.
 
-## Project Structure
+### Insert with parameters
 
 ```
-cmd/main.go              # Entry point — registers components, runs CLI
-components/echo/echo.go  # Example component
-go.mod                   # SDK dependency (github.com/tiny-systems/module)
+redis_dedup:out_new → postgres_exec
+                       sql: INSERT INTO matched_posts (id, source, title, score) VALUES ($1, $2, $3, $4)
+                       params: ["{{$.id}}", "reddit", "{{$.context.title}}", "{{$.context.score}}"]
 ```
 
-## Getting Started
+### Query with configurable row shape
+
+In `postgres_query` settings, define the expected row shape:
 
-1. **Use this template** — click "Use this template" on GitHub
-2. **Rename the module** in `go.mod`
-3. **Add your components** under `components/`
-4. **Register them** via `init()` + `registry.Register()`
+```json
+{
+  "row": { "id": "abc", "title": "title", "score": 0 }
+}
+```
+
+Downstream edges can then navigate `$.rows[0].title`, `$.count`, etc.
 
 ## Run Locally
 
 ```shell
 go run cmd/main.go run \
-  --name=my-org/my-module-v1 \
+  --name=tiny-systems/database-module-v0 \
   --namespace=tinysystems \
-  --version=1.0.0
+  --version=0.1.0
 ```
 
-## Build and Deploy
-
-```shell
-# Build container image
-docker build -t myregistry/my-module:1.0.0 .
-docker push myregistry/my-module:1.0.0
-
-# Install via Helm
-helm repo add tinysystems https://tiny-systems.github.io/module/
-helm install my-module tinysystems/tinysystems-operator \
-  --set controllerManager.manager.image.repository=myregistry/my-module
-```
-
-## Resources
-
-- [Developer Guide](https://docs.tinysystems.io/developer-guide/getting-started/hello-world-component) — build your first component
-- [Module SDK](https://github.com/tiny-systems/module) — core library
-- [Component Examples](https://docs.tinysystems.io/examples/components/simple-transformer) — real-world patterns
-- [Tiny Systems Platform](https://tinysystems.io) — visual editor and module directory
-
 ## License
 
-This module's source code is MIT-licensed. It depends on the [Tiny Systems Module SDK](https://github.com/tiny-systems/module) (BSL 1.1). See [LICENSE](LICENSE) for details.
+MIT for this module's source. Depends on [Tiny Systems Module SDK](https://github.com/tiny-systems/module) (BSL 1.1).

cmd/main.go

@@ -3,27 +3,30 @@ package main
 import (
 	"context"
 	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
 	"github.com/rs/zerolog"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
-	_ "github.com/tiny-systems/example-module/components/echo"
+	_ "github.com/tiny-systems/database-module/components/postgresexec"
+	_ "github.com/tiny-systems/database-module/components/postgresquery"
+	_ "github.com/tiny-systems/database-module/components/redisdedup"
+	_ "github.com/tiny-systems/database-module/components/redisget"
+	_ "github.com/tiny-systems/database-module/components/redisset"
 	"github.com/tiny-systems/module/cli"
-	"os"
-	"os/signal"
-	"syscall"
 )
 
-// RootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Use:   "server",
-	Short: "tiny-system's example module",
+	Short: "tiny-system's database module — Postgres and Redis components",
 	Run: func(cmd *cobra.Command, args []string) {
-		cmd.Help()
+		_ = cmd.Help()
 	},
 }
 
 func main() {
-	// Default level for this example is info, unless debug flag is present
 	zerolog.SetGlobalLevel(zerolog.InfoLevel)
 	viper.AutomaticEnv()
 	if viper.GetBool("debug") {

components/echo/echo.go

@@ -0,0 +1,52 @@
+// Package pool caches database connections across component invocations.
+// Postgres pools are keyed by DSN; Redis clients are keyed by URL.
+// Each unique DSN/URL produces one shared pool that lives for the process lifetime.
+package pool
+
+import (
+	"context"
+	"sync"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/redis/go-redis/v9"
+)
+
+var (
+	pgPools      sync.Map // map[string]*pgxpool.Pool
+	redisClients sync.Map // map[string]*redis.Client
+)
+
+// Postgres returns a cached pgx pool for the given DSN, creating one on first use.
+func Postgres(ctx context.Context, dsn string) (*pgxpool.Pool, error) {
+	if v, ok := pgPools.Load(dsn); ok {
+		return v.(*pgxpool.Pool), nil
+	}
+	p, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		return nil, err
+	}
+	if actual, loaded := pgPools.LoadOrStore(dsn, p); loaded {
+		p.Close()
+		return actual.(*pgxpool.Pool), nil
+	}
+	return p, nil
+}
+
+// Redis returns a cached Redis client for the given URL, creating one on first use.
+func Redis(url string) (*redis.Client, error) {
+	if v, ok := redisClients.Load(url); ok {
+		return v.(*redis.Client), nil
+	}
+	opts, err := redis.ParseURL(url)
+	if err != nil {
+		return nil, err
+	}
+	c := redis.NewClient(opts)
+	if actual, loaded := redisClients.LoadOrStore(url, c); loaded {
+		if closeErr := c.Close(); closeErr != nil {
+			_ = closeErr
+		}
+		return actual.(*redis.Client), nil
+	}
+	return c, nil
+}

components/pool/pool.go

@@ -0,0 +1,122 @@
+package postgresexec
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/tiny-systems/database-module/components/pool"
+	"github.com/tiny-systems/module/api/v1alpha1"
+	"github.com/tiny-systems/module/module"
+	"github.com/tiny-systems/module/registry"
+)
+
+const (
+	ComponentName = "postgres_exec"
+	RequestPort   = "request"
+	ResponsePort  = "response"
+	ErrorPort     = "error"
+)
+
+type Context any
+
+type Settings struct {
+	EnableErrorPort bool `json:"enableErrorPort" required:"true" title:"Enable Error Port"`
+}
+
+type Request struct {
+	Context Context `json:"context,omitempty" configurable:"true" title:"Context"`
+	DSN     string  `json:"dsn" required:"true" minLength:"1" title:"DSN" description:"Postgres connection string (e.g. postgres://user:pass@host:port/db?sslmode=disable)"`
+	SQL     string  `json:"sql" required:"true" minLength:"1" title:"SQL" description:"INSERT/UPDATE/DELETE with $1, $2, ... placeholders" format:"textarea"`
+	Params  []any   `json:"params,omitempty" title:"Params" description:"Positional parameters for $1, $2, ..."`
+}
+
+type Response struct {
+	Context      Context `json:"context,omitempty" configurable:"true" title:"Context"`
+	RowsAffected int64   `json:"rowsAffected" title:"Rows Affected"`
+}
+
+type Error struct {
+	Context Context `json:"context,omitempty" configurable:"true" title:"Context"`
+	Error   string  `json:"error" title:"Error"`
+}
+
+type Component struct {
+	settings Settings
+}
+
+func (c *Component) Instance() module.Component {
+	return &Component{}
+}
+
+func (c *Component) GetInfo() module.ComponentInfo {
+	return module.ComponentInfo{
+		Name:        ComponentName,
+		Description: "Postgres Exec",
+		Info:        "Executes INSERT/UPDATE/DELETE against Postgres with positional parameters. Connection pool is cached per DSN across calls.",
+		Tags:        []string{"Postgres", "SQL", "DB"},
+	}
+}
+
+func (c *Component) Handle(ctx context.Context, handler module.Handler, port string, msg any) any {
+	switch port {
+	case v1alpha1.SettingsPort:
+		in, ok := msg.(Settings)
+		if !ok {
+			return fmt.Errorf("invalid settings")
+		}
+		c.settings = in
+		return nil
+
+	case RequestPort:
+		in, ok := msg.(Request)
+		if !ok {
+			return fmt.Errorf("invalid request")
+		}
+		return c.run(ctx, handler, in)
+	}
+	return fmt.Errorf("port %s not supported", port)
+}
+
+func (c *Component) run(ctx context.Context, handler module.Handler, in Request) any {
+	p, err := pool.Postgres(ctx, in.DSN)
+	if err != nil {
+		return c.fail(ctx, handler, in.Context, err)
+	}
+
+	tag, err := p.Exec(ctx, in.SQL, in.Params...)
+	if err != nil {
+		return c.fail(ctx, handler, in.Context, err)
+	}
+
+	return handler(ctx, ResponsePort, Response{
+		Context:      in.Context,
+		RowsAffected: tag.RowsAffected(),
+	})
+}
+
+func (c *Component) fail(ctx context.Context, handler module.Handler, reqCtx Context, err error) any {
+	if !c.settings.EnableErrorPort {
+		return err
+	}
+	return handler(ctx, ErrorPort, Error{Context: reqCtx, Error: err.Error()})
+}
+
+func (c *Component) Ports() []module.Port {
+	ports := []module.Port{
+		{Name: v1alpha1.SettingsPort, Label: "Settings", Configuration: c.settings},
+		{Name: RequestPort, Label: "Request", Configuration: Request{}, Position: module.Left},
+		{Name: ResponsePort, Label: "Response", Source: true, Configuration: Response{}, Position: module.Right},
+	}
+	if !c.settings.EnableErrorPort {
+		return ports
+	}
+	return append(ports, module.Port{
+		Name: ErrorPort, Label: "Error", Source: true, Configuration: Error{}, Position: module.Bottom,
+	})
+}
+
+var _ module.Component = (*Component)(nil)
+
+func init() {
+	registry.Register(&Component{})
+}