feat(api,cli): add PostgreSQL store infrastructure and scaffolding

Implement base structure for PostgreSQL store using bun ORM as an
alternative to MongoDB. Store method signatures defined but not yet
implemented. Both API server and CLI now support database selection via
environment variable.

- Add PostgreSQL connection and configuration in api/server.go and
  cli/main.go
- Create pg store package with method signatures for all store
  operations
- Implement database connection, migration system, and logging options
- Add testcontainers-based test infrastructure for PostgreSQL
- Define entity models and store interface implementation skeleton
- Configure bun ORM with pgx driver for PostgreSQL operations

Author: heiytor

.env

@@ -36,6 +36,8 @@ SHELLHUB_AUTO_SSL=false
 
 SHELLHUB_DATABASE=mongo
 
+SHELLHUB_POSTGRES_HOST=postgres
+SHELLHUB_POSTGRES_PORT=5432
 SHELLHUB_POSTGRES_USERNAME=admin
 SHELLHUB_POSTGRES_PASSWORD=admin
 SHELLHUB_POSTGRES_DATABASE=main

api/server.go

@@ -2,14 +2,17 @@ package main
 
 import (
 	"context"
+	"errors"
 	"os"
 
 	"github.com/getsentry/sentry-go"
 	"github.com/labstack/echo/v4"
 	"github.com/shellhub-io/shellhub/api/routes"
 	"github.com/shellhub-io/shellhub/api/services"
+	"github.com/shellhub-io/shellhub/api/store"
 	"github.com/shellhub-io/shellhub/api/store/mongo"
 	"github.com/shellhub-io/shellhub/api/store/mongo/options"
+	"github.com/shellhub-io/shellhub/api/store/pg"
 	"github.com/shellhub-io/shellhub/pkg/api/internalclient"
 	"github.com/shellhub-io/shellhub/pkg/cache"
 	"github.com/shellhub-io/shellhub/pkg/geoip/geolite2"
@@ -19,9 +22,22 @@ import (
 )
 
 type env struct {
+	Database string `env:"DATABASE,default=mongo"`
+
 	// MongoURI specifies the connection string for MongoDB.
 	MongoURI string `env:"MONGO_URI,default=mongodb://mongo:27017/main"`
 
+	// PostgresHost specifies the host for PostgreSQL.
+	PostgresHost string `env:"POSTGRES_HOST,default=postgres"`
+	// PostgresPort specifies the port for PostgreSQL.
+	PostgresPort string `env:"POSTGRES_PORT,default=5432"`
+	// PostgresUsername specifies the username for authenticate PostgreSQL.
+	PostgresUsername string `env:"POSTGRES_USERNAME,default=admin"`
+	// PostgresUser specifies the password for authenticate PostgreSQL.
+	PostgresPassword string `env:"POSTGRES_PASSWORD,default=admin"`
+	// PostgresDatabase especifica o nome do banco de dados PostgreSQL a ser utilizado.
+	PostgresDatabase string `env:"POSTGRES_DATABASE,default=main"`
+
 	// RedisURI specifies the connection string for Redis.
 	RedisURI string `env:"REDIS_URI,default=redis://redis:6379"`
 	// RedisCachePoolSize defines the maximum number of concurrent connections to Redis cache.
@@ -75,14 +91,22 @@ func (s *Server) Setup(ctx context.Context) error {
 
 	log.Debug("Redis cache initialized successfully")
 
-	store, err := mongo.NewStore(ctx, s.env.MongoURI, cache, options.RunMigatrions)
-	if err != nil {
-		log.
-			WithError(err).
-			Fatal("failed to create the store")
+	var store store.Store
+	switch s.env.Database {
+	case "mongodb":
+		store, err = mongo.NewStore(ctx, s.env.MongoURI, cache, options.RunMigatrions)
+	case "postgres":
+		uri := pg.URI(s.env.PostgresHost, s.env.PostgresPort, s.env.PostgresUsername, s.env.PostgresPassword, s.env.PostgresDatabase)
+		store, err = pg.New(ctx, uri)
+	default:
+		log.WithField("database", s.env.Database).Error("invalid database")
+		return errors.New("invalid database")
 	}
 
-	log.Debug("MongoDB store connected successfully")
+	if err != nil {
+		log.WithError(err).Error("failed to create the store")
+		return err
+	}
 
 	apiClient, err := internalclient.NewClient(nil, internalclient.WithAsynqWorker(s.env.RedisURI))
 	if err != nil {

api/store/pg/api-key.go

@@ -0,0 +1,20 @@
+package pg
+
+import (
+	"context"
+
+	"github.com/shellhub-io/shellhub/api/store"
+	"github.com/shellhub-io/shellhub/pkg/models"
+)
+
+func (pg *Pg) APIKeyCreate(ctx context.Context, APIKey *models.APIKey) (insertedID string, err error)
+
+func (pg *Pg) APIKeyResolve(ctx context.Context, resolver store.APIKeyResolver, value string, opts ...store.QueryOption) (*models.APIKey, error)
+
+func (pg *Pg) APIKeyConflicts(ctx context.Context, tenantID string, target *models.APIKeyConflicts) (conflicts []string, has bool, err error)
+
+func (pg *Pg) APIKeyList(ctx context.Context, opts ...store.QueryOption) (apiKeys []models.APIKey, count int, err error)
+
+func (pg *Pg) APIKeySave(ctx context.Context, apiKey *models.APIKey) (err error)
+
+func (pg *Pg) APIKeyDelete(ctx context.Context, apiKey *models.APIKey) (err error)

api/store/pg/dbtest/dbtest.go

@@ -0,0 +1,54 @@
+package dbtest
+
+import (
+	"context"
+	"io"
+	"log"
+	"time"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/postgres"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+// Server represents a Postgres test server instance.
+type Server struct {
+	container *postgres.PostgresContainer
+}
+
+// Up starts a new Postgres container. Use [Server.ConnectionString] to access the connection string.
+func (srv *Server) Up(ctx context.Context, verbose bool) error {
+	if !verbose {
+		testcontainers.Logger = log.New(io.Discard, "", 0)
+	}
+
+	opts := []testcontainers.ContainerCustomizer{
+		postgres.WithDatabase("test"),
+		postgres.WithUsername("admin"),
+		postgres.WithPassword("admin"),
+		testcontainers.WithWaitStrategy(wait.ForLog("database system is ready to accept connections").WithOccurrence(2).WithStartupTimeout(5 * time.Second)),
+	}
+
+	container, err := postgres.Run(ctx, "postgres:18.0", opts...)
+	if err != nil {
+		return err
+	}
+
+	srv.container = container
+
+	return nil
+}
+
+// Down gracefully terminates the Postgres container.
+func (srv *Server) Down(ctx context.Context) error {
+	return srv.container.Terminate(ctx)
+}
+
+func (srv *Server) ConnectionString(ctx context.Context) (string, error) {
+	cIP, err := srv.container.ContainerIP(ctx)
+	if err != nil {
+		return "", err
+	}
+
+	return "postgres://admin:admin@" + cIP + ":5432/test", nil
+}

api/store/pg/dbtest/fixtures.go

@@ -0,0 +1,12 @@
+package dbtest
+
+import (
+	"path/filepath"
+	"runtime"
+)
+
+func FixturesPath() string {
+	_, file, _, _ := runtime.Caller(0)
+
+	return filepath.Join(filepath.Dir(file), "fixtures")
+}

api/store/pg/device.go

@@ -0,0 +1,25 @@
+package pg
+
+import (
+	"context"
+	"time"
+
+	"github.com/shellhub-io/shellhub/api/store"
+	"github.com/shellhub-io/shellhub/pkg/models"
+)
+
+func (pg *Pg) DeviceCreate(ctx context.Context, device *models.Device) (insertedUID string, err error)
+
+func (pg *Pg) DeviceList(ctx context.Context, acceptable store.DeviceAcceptable, opts ...store.QueryOption) ([]models.Device, int, error)
+
+func (pg *Pg) DeviceResolve(ctx context.Context, resolver store.DeviceResolver, value string, opts ...store.QueryOption) (*models.Device, error)
+
+func (pg *Pg) DeviceConflicts(ctx context.Context, target *models.DeviceConflicts) (conflicts []string, has bool, err error)
+
+func (pg *Pg) DeviceUpdate(ctx context.Context, device *models.Device) error
+
+func (pg *Pg) DeviceHeartbeat(ctx context.Context, uids []string, lastSeen time.Time) (modifiedCount int64, err error)
+
+func (pg *Pg) DeviceDelete(ctx context.Context, device *models.Device) error
+
+func (pg *Pg) DeviceDeleteMany(ctx context.Context, uids []string) (deletedCount int64, err error)

api/store/pg/member.go

@@ -0,0 +1,13 @@
+package pg
+
+import (
+	"context"
+
+	"github.com/shellhub-io/shellhub/pkg/models"
+)
+
+func (pg *Pg) NamespaceAddMember(ctx context.Context, tenantID string, member *models.Member) error
+
+func (pg *Pg) NamespaceUpdateMember(ctx context.Context, tenantID string, memberID string, changes *models.MemberChanges) error
+
+func (pg *Pg) NamespaceRemoveMember(ctx context.Context, tenantID string, memberID string) error

api/store/pg/namespace.go

@@ -0,0 +1,26 @@
+package pg
+
+import (
+	"context"
+
+	"github.com/shellhub-io/shellhub/api/store"
+	"github.com/shellhub-io/shellhub/pkg/models"
+)
+
+func (pg *Pg) NamespaceList(ctx context.Context, opts ...store.QueryOption) ([]models.Namespace, int, error)
+
+func (pg *Pg) NamespaceResolve(ctx context.Context, resolver store.NamespaceResolver, value string) (*models.Namespace, error)
+
+func (pg *Pg) NamespaceGetPreferred(ctx context.Context, userID string) (*models.Namespace, error)
+
+func (pg *Pg) NamespaceCreate(ctx context.Context, namespace *models.Namespace) (*models.Namespace, error)
+
+func (pg *Pg) NamespaceConflicts(ctx context.Context, target *models.NamespaceConflicts) (conflicts []string, has bool, err error)
+
+func (pg *Pg) NamespaceUpdate(ctx context.Context, namespace *models.Namespace) error
+
+func (pg *Pg) NamespaceIncrementDeviceCount(ctx context.Context, tenantID string, status models.DeviceStatus, count int64) error
+
+func (pg *Pg) NamespaceDelete(ctx context.Context, namespace *models.Namespace) error
+
+func (pg *Pg) NamespaceDeleteMany(ctx context.Context, tenantIDs []string) (int64, error)

api/store/pg/options/log.go

@@ -0,0 +1,39 @@
+package options
+
+import (
+	"context"
+	"os"
+
+	"github.com/oiime/logrusbun"
+	"github.com/sirupsen/logrus"
+	"github.com/uptrace/bun"
+)
+
+func Log(level string, verbose bool) Option {
+	return func(ctx context.Context, db *bun.DB) error {
+		level, err := logrus.ParseLevel(level)
+		if err != nil {
+			return err
+		}
+
+		logger := &logrus.Logger{
+			Out:       os.Stderr,
+			Formatter: new(logrus.TextFormatter),
+			Hooks:     make(logrus.LevelHooks),
+			Level:     level,
+		}
+
+		db.AddQueryHook(logrusbun.NewQueryHook(
+			logrusbun.WithEnabled(true),
+			logrusbun.WithVerbose(verbose),
+			logrusbun.WithQueryHookOptions(logrusbun.QueryHookOptions{
+				Logger:     logger,
+				QueryLevel: logrus.DebugLevel,
+				ErrorLevel: logrus.ErrorLevel,
+				SlowLevel:  logrus.WarnLevel,
+			}),
+		))
+
+		return nil
+	}
+}

api/store/pg/options/migrate.go

@@ -0,0 +1,61 @@
+package options
+
+import (
+	"context"
+
+	"github.com/shellhub-io/shellhub/api/store/pg/migrations"
+	log "github.com/sirupsen/logrus"
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/migrate"
+)
+
+func Migrate() Option {
+	return func(ctx context.Context, db *bun.DB) error {
+		log.Info("starting database migration")
+
+		migrations, err := migrations.FetchMigrations()
+		if err != nil {
+			log.WithError(err).Error("failed to fetch migrations")
+
+			return err
+		}
+
+		migrator := migrate.NewMigrator(db, migrations)
+		if err := migrator.Init(context.Background()); err != nil {
+			log.WithError(err).Error("failed to start migrations tables")
+
+			return err
+		}
+
+		if err := migrator.Lock(ctx); err != nil {
+			log.WithError(err).Error("failed to acquire migration lock")
+
+			return err
+		}
+
+		defer func() {
+			if err := migrator.Unlock(ctx); err != nil {
+				log.WithError(err).Error("failed to release migration lock")
+			} else {
+				log.Debug("migration lock released successfully")
+			}
+		}()
+
+		group, err := migrator.Migrate(ctx)
+		if err != nil {
+			log.WithError(err).Error("migration failed")
+
+			return err
+		}
+
+		if group.IsZero() {
+			log.Info("no new migrations to run (database is up to date)")
+
+			return nil
+		}
+
+		log.Info("migration completed successfully")
+
+		return nil
+	}
+}