Cluster: Allow configuration of database and user prefix #98

Signed-off-by: Michael Mayer <michael@photoprism.app>

Author: lastzero

AGENTS.md

@@ -426,6 +426,6 @@ Note: Across our public documentation, official images, and in production, the c
 - Theme endpoint: `GET /api/v1/cluster/theme` streams a zip from `conf.ThemePath()`; only reinstall when `app.js` is missing and always use the header helpers in `pkg/http/header`.
 - Registration flow: send `rotate=true` only for MySQL/MariaDB nodes without credentials, treat 401/403/404 as terminal, include `ClientID` + `ClientSecret` when renaming an existing node, and persist only newly generated secrets or DB settings.
 - Registry & DTOs: use the client-backed registry (`NewClientRegistryWithConfig`)—the file-backed version is legacy—and treat migration as complete only after swapping callsites, building, and running focused API/CLI tests. Nodes are keyed by UUID v7 (`/api/v1/cluster/nodes/{uuid}`), the registry interface stays UUID-first (`Get`, `FindByNodeUUID`, `FindByClientID`, `RotateSecret`, `DeleteAllByUUID`), CLI lookups resolve `uuid → ClientID → name`, and DTOs normalize `Database.{Name,User,Driver,RotatedAt}` while exposing `ClientSecret` only during creation/rotation. `nodes rm --all-ids` cleans duplicate client rows, admin responses may include `AdvertiseUrl`/`Database`, client/user sessions stay redacted, registry files live under `conf.PortalConfigPath()/nodes/` (mode 0600), and `ClientData` no longer stores `NodeUUID`.
-- Provisioner & DSN: database/user names use UUID-based HMACs (`cluster_d<hmac11>`, `cluster_u<hmac11>`); `BuildDSN` accepts a `driver` but falls back to MySQL format with a warning when unsupported.
+- Provisioner & DSN: database/user names use UUID-based HMACs (`<prefix>d<hmac11>`, `<prefix>u<hmac11>` where the prefix defaults to `cluster_` but may be overridden via the portal-only `database-provision-prefix` flag); `BuildDSN` accepts a `driver` but falls back to MySQL format with a warning when unsupported.
 - If we add Postgres provisioning support, extend `BuildDSN` and `provisioner.DatabaseDriver` handling, add validations, and return `driver=postgres` consistently in API/CLI.
 - Testing: exercise Portal endpoints with `httptest`, guard extraction paths with `pkg/fs.Unzip` size caps, and expect admin-only fields to disappear when authenticated as a client/user session.

internal/config/config_db.go

@@ -19,6 +19,7 @@ import (
 	"github.com/photoprism/photoprism/internal/entity/migrate"
 	"github.com/photoprism/photoprism/internal/event"
 	"github.com/photoprism/photoprism/internal/mutex"
+	"github.com/photoprism/photoprism/internal/service/cluster"
 	"github.com/photoprism/photoprism/pkg/clean"
 )
 
@@ -303,6 +304,55 @@ func (c *Config) DatabasePassword() string {
 	}
 }
 
+// DatabaseProvisionPrefix returns the sanitized prefix for provisioned database names and users.
+func (c *Config) DatabaseProvisionPrefix() string {
+	prefix := strings.TrimSpace(c.options.DatabaseProvisionPrefix)
+
+	if prefix == "" {
+		return cluster.DefaultDatabaseProvisionPrefix
+	}
+
+	prefix = strings.ToLower(prefix)
+
+	cleaned := make([]rune, 0, len(prefix))
+	prevUnderscore := false
+
+	for _, r := range prefix {
+		switch {
+		case r >= 'a' && r <= 'z':
+			cleaned = append(cleaned, r)
+			prevUnderscore = false
+		case r >= '0' && r <= '9':
+			if len(cleaned) == 0 {
+				continue
+			}
+			cleaned = append(cleaned, r)
+			prevUnderscore = false
+		case r == '_' || r == '-' || r == ' ':
+			if len(cleaned) == 0 || prevUnderscore {
+				continue
+			}
+			cleaned = append(cleaned, '_')
+			prevUnderscore = true
+		default:
+			continue
+		}
+
+		if len(cleaned) >= cluster.DatabaseProvisionPrefixMaxLen {
+			break
+		}
+	}
+
+	if len(cleaned) == 0 {
+		return cluster.DefaultDatabaseProvisionPrefix
+	}
+
+	result := string(cleaned)
+	c.options.DatabaseProvisionPrefix = result
+
+	return result
+}
+
 // ShouldAutoRotateDatabase decides whether callers should request DB rotation automatically.
 // It is used by both the CLI and node bootstrap to avoid unnecessary provisioning calls.
 func (c *Config) ShouldAutoRotateDatabase() bool {

internal/config/config_db_test.go

@@ -199,6 +199,25 @@ func TestConfig_DatabasePassword(t *testing.T) {
 	assert.Equal(t, "", c.DatabasePassword())
 }
 
+func TestDatabaseProvisionPrefix(t *testing.T) {
+	t.Run("Default", func(t *testing.T) {
+		conf := NewConfig(CliTestContext())
+		resetDatabaseOptions(conf)
+		assert.Equal(t, cluster.DefaultDatabaseProvisionPrefix, conf.DatabaseProvisionPrefix())
+	})
+	t.Run("SanitizeAndTrim", func(t *testing.T) {
+		conf := NewConfig(CliTestContext())
+		resetDatabaseOptions(conf)
+		conf.options.DatabaseProvisionPrefix = "  My Custom-Prefix!!  "
+
+		got := conf.DatabaseProvisionPrefix()
+
+		assert.Equal(t, "my_custom_prefix", got)
+		assert.LessOrEqual(t, len(got), cluster.DatabaseProvisionPrefixMaxLen)
+		assert.Equal(t, got, conf.options.DatabaseProvisionPrefix)
+	})
+}
+
 func TestShouldAutoRotateDatabase(t *testing.T) {
 	t.Run("PortalAlwaysFalse", func(t *testing.T) {
 		conf := NewMinimalTestConfig(t.TempDir())

internal/config/flags.go

@@ -921,6 +921,13 @@ var Flags = CliFlags{
 			EnvVars: EnvVars("DATABASE_PROVISION_DRIVER"),
 			Hidden:  true,
 		}}, {
+		Flag: &cli.StringFlag{
+			Name:    "database-provision-prefix",
+			Usage:   "auto-provisioning name `PREFIX` for generated database names and users",
+			Value:   cluster.DefaultDatabaseProvisionPrefix,
+			EnvVars: EnvVars("DATABASE_PROVISION_PREFIX"),
+			Hidden:  true,
+		}}, {
 		Flag: &cli.StringFlag{
 			Name:    "database-provision-dsn",
 			Usage:   "auto-provisioning `DSN`",

internal/config/options.go

@@ -189,6 +189,7 @@ type Options struct {
 	DatabaseConns           int           `yaml:"DatabaseConns" json:"-" flag:"database-conns"`
 	DatabaseConnsIdle       int           `yaml:"DatabaseConnsIdle" json:"-" flag:"database-conns-idle"`
 	DatabaseProvisionDriver string        `yaml:"DatabaseProvisionDriver" json:"-" flag:"database-provision-driver"`
+	DatabaseProvisionPrefix string        `yaml:"DatabaseProvisionPrefix" json:"-" flag:"database-provision-prefix"`
 	DatabaseProvisionDSN    string        `yaml:"DatabaseProvisionDSN" json:"-" flag:"database-provision-dsn"`
 	FFmpegBin               string        `yaml:"FFmpegBin" json:"-" flag:"ffmpeg-bin"`
 	FFmpegEncoder           string        `yaml:"FFmpegEncoder" json:"FFmpegEncoder" flag:"ffmpeg-encoder"`

internal/config/report.go

@@ -192,7 +192,17 @@ func (c *Config) Report() (rows [][]string, cols []string) {
 		{"jwt-scope", c.JWTAllowedScopes().String()},
 		{"jwt-leeway", fmt.Sprintf("%d", c.JWTLeeway())},
 		{"advertise-url", c.AdvertiseUrl()},
+	}...)
 
+	if c.Portal() {
+		rows = append(rows, [][]string{
+			{"database-provision-driver", c.options.DatabaseProvisionDriver},
+			{"database-provision-prefix", c.DatabaseProvisionPrefix()},
+			{"database-provision-dsn", maskDatabaseProvisionDSN(c.options.DatabaseProvisionDSN)},
+		}...)
+	}
+
+	rows = append(rows, [][]string{
 		// Proxy Servers.
 		{"https-proxy", c.HttpsProxy()},
 		{"https-proxy-insecure", fmt.Sprintf("%t", c.HttpsProxyInsecure())},
@@ -345,3 +355,21 @@ func (c *Config) Report() (rows [][]string, cols []string) {
 
 	return rows, cols
 }
+
+func maskDatabaseProvisionDSN(dsn string) string {
+	if dsn == "" {
+		return ""
+	}
+
+	ds := NewDSN(dsn)
+	if ds.Password == "" {
+		return dsn
+	}
+
+	needle := ":" + ds.Password + "@"
+	if strings.Contains(dsn, needle) {
+		return strings.Replace(dsn, needle, ":***@", 1)
+	}
+
+	return dsn
+}

internal/service/cluster/examples.go internal/service/cluster/const.gointernal/service/cluster/examples.go renamed to internal/service/cluster/const.go

@@ -1,5 +1,13 @@
 package cluster
 
+// Default values used by cluster provisioning helpers.
+const (
+	// DefaultDatabaseProvisionPrefix is applied to auto-provisioned database names and user accounts.
+	DefaultDatabaseProvisionPrefix = "cluster_"
+	// DatabaseProvisionPrefixMaxLen keeps generated usernames within the MySQL 32 character budget.
+	DatabaseProvisionPrefixMaxLen = 20
+)
+
 // Example values used by documentation and tests to illustrate cluster tokens.
 const (
 	// ExampleJoinToken represents a valid portal join token.

internal/service/cluster/provisioner/README.md

@@ -2,13 +2,13 @@
 
 ## Overview
 
-The provisioner package manages per-node MariaDB schemas and users for cluster deployments. It derives deterministic identifiers from the cluster UUID and node name, creates or rotates credentials via the admin DSN, and exposes helpers (`EnsureCredentials`, `DropCredentials`, `GenerateCredentials`) that API and CLI layers can reuse when onboarding or rotating nodes.
+The provisioner package manages per-node MariaDB schemas and users for cluster deployments. It derives deterministic identifiers from the cluster UUID and node name using a configurable prefix (default `cluster_`), creates or rotates credentials via the admin DSN, and exposes helpers (`EnsureCredentials`, `DropCredentials`, `GenerateCredentials`) that API and CLI layers can reuse when onboarding or rotating nodes.
 
 ## Development Workflow
 
 - Configuration lives in `database.go`. The admin connection string is `ProvisionDSN` (default `root:photoprism@tcp(mariadb:4001)/photoprism?...`). Adjust only when running against a different host or password.
 - `EnsureCredentials` accepts node UUID and name, creates the schema if needed, and returns credentials plus rotation metadata. `DropCredentials` revokes grants, drops the user, and removes the schema. Both functions require a context; prefer `context.WithTimeout` in callers.
-- Identifier generation is centralized in `GenerateCredentials`. Call it instead of handcrafting database or user names so tests, CLI, and API stay aligned.
+- Identifier generation is centralized in `GenerateCredentials`. Call it instead of handcrafting database or user names so tests, CLI, and API stay aligned. The resulting identifiers follow `<prefix>d<hmac11>` for schemas and `<prefix>u<hmac11>` for users. Portal deployments may override the prefix via the `database-provision-prefix` flag; defaults are `cluster_d…` / `cluster_u…`.
 
 ## Testing Guidelines
 
@@ -31,12 +31,12 @@ The provisioner package manages per-node MariaDB schemas and users for cluster d
 - Connect from the dev container using `mariadb` (already configured to reach `mariadb:4001`). Common snippets:
   ```bash
   cat <<'SQL' | mariadb
-  SHOW DATABASES LIKE 'cluster_d%';
+  SHOW DATABASES LIKE 'cluster_d%'; -- adjust prefix if database-provision-prefix overrides the default
   SQL
   ```
   ```bash
   cat <<'SQL' | mariadb
-  SELECT User, Host FROM mysql.user WHERE User LIKE 'cluster_u%';
+  SELECT User, Host FROM mysql.user WHERE User LIKE 'cluster_u%'; -- adjust prefix if needed
   SQL
   ```
 - Manually drop leftover resources when iterating outside tests:

internal/service/cluster/provisioner/naming.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	"github.com/photoprism/photoprism/internal/config"
+	"github.com/photoprism/photoprism/internal/service/cluster"
 	"github.com/photoprism/photoprism/pkg/rnd"
 )
 
@@ -16,20 +17,38 @@ const (
 	// Final pattern without slugs (UUID-based):
 	//   database: cluster_d<hmac11>
 	//   username: cluster_u<hmac11>
-	prefix     = "photoprism_"
 	dbSuffix   = 11
 	userSuffix = 11
 	// Budgets: keep user conservative for MySQL compatibility; MariaDB allows more.
 	userMax = 32
 	dbMax   = 64
+	// prefixMax ensures usernames remain within the MySQL identifier limit.
+	prefixMax = cluster.DatabaseProvisionPrefixMaxLen
 )
 
+// DatabasePrefix stores the default identifier prefix for provisioned databases and users.
+// Portal deployments override this value during initialization based on configuration.
+var DatabasePrefix = cluster.DefaultDatabaseProvisionPrefix
+
 // GenerateCredentials computes deterministic database name and user for a node under the given portal
 // plus a random password. Naming is stable for a given (clusterUUID, nodeUUID) pair and changes
 // if the cluster UUID or node UUID changes.
 func GenerateCredentials(conf *config.Config, nodeUUID, nodeName string) (dbName, dbUser, dbPass string) {
 	clusterUUID := conf.ClusterUUID()
 
+	prefix := DatabasePrefix
+	if conf != nil {
+		if p := conf.DatabaseProvisionPrefix(); p != "" {
+			prefix = p
+		}
+	}
+	if prefix == "" {
+		prefix = cluster.DefaultDatabaseProvisionPrefix
+	}
+	if len(prefix) > prefixMax {
+		prefix = prefix[:prefixMax]
+	}
+
 	// Compute base32 (no padding) HMAC suffixes scoped by cluster UUID and node UUID.
 	sName := hmacBase32("db-name:"+clusterUUID, nodeUUID)
 	sUser := hmacBase32("db-user:"+clusterUUID, nodeUUID)

internal/service/cluster/provisioner/naming_test.go

@@ -8,9 +8,12 @@ import (
 	"github.com/stretchr/testify/assert"
 
 	"github.com/photoprism/photoprism/internal/config"
+	"github.com/photoprism/photoprism/internal/service/cluster"
 )
 
 func TestGenerateCredentials_StabilityAndBudgets(t *testing.T) {
+	DatabasePrefix = cluster.DefaultDatabaseProvisionPrefix
+
 	c := config.NewConfig(config.CliTestContext())
 	// Fix the cluster UUID via options to ensure determinism.
 	c.Options().ClusterUUID = "11111111-1111-4111-8111-111111111111"
@@ -26,11 +29,13 @@ func TestGenerateCredentials_StabilityAndBudgets(t *testing.T) {
 	// Budgets and patterns.
 	assert.LessOrEqual(t, len(user1), 32)
 	assert.LessOrEqual(t, len(db1), 64)
-	assert.Contains(t, db1, "photoprism_")
-	assert.Contains(t, user1, "photoprism_")
+	assert.Contains(t, db1, cluster.DefaultDatabaseProvisionPrefix)
+	assert.Contains(t, user1, cluster.DefaultDatabaseProvisionPrefix)
 }
 
 func TestGenerateCredentials_DifferentPortal(t *testing.T) {
+	DatabasePrefix = cluster.DefaultDatabaseProvisionPrefix
+
 	c1 := config.NewConfig(config.CliTestContext())
 	c2 := config.NewConfig(config.CliTestContext())
 	c1.Options().ClusterUUID = "11111111-1111-4111-8111-111111111111"
@@ -44,6 +49,8 @@ func TestGenerateCredentials_DifferentPortal(t *testing.T) {
 }
 
 func TestGenerateCredentials_Truncation(t *testing.T) {
+	DatabasePrefix = cluster.DefaultDatabaseProvisionPrefix
+
 	c := config.NewConfig(config.CliTestContext())
 	c.Options().ClusterUUID = "11111111-1111-4111-8111-111111111111"
 	longName := "this-is-a-very-very-long-node-name-that-should-be-truncated-to-fit-username-and-db-budgets"
@@ -53,6 +60,24 @@ func TestGenerateCredentials_Truncation(t *testing.T) {
 	assert.LessOrEqual(t, len(db), 64)
 }
 
+func TestGenerateCredentials_CustomPrefix(t *testing.T) {
+	DatabasePrefix = cluster.DefaultDatabaseProvisionPrefix
+
+	c := config.NewConfig(config.CliTestContext())
+	c.Options().ClusterUUID = "11111111-1111-4111-8111-111111111111"
+	c.Options().DatabaseProvisionPrefix = "My-Custom Prefix!"
+
+	prefix := c.DatabaseProvisionPrefix()
+	assert.Equal(t, "my_custom_prefix", prefix)
+
+	db, user, _ := GenerateCredentials(c, "11111111-1111-4111-8111-222222222222", "pp-node-02")
+
+	assert.True(t, strings.HasPrefix(db, prefix+"d"))
+	assert.True(t, strings.HasPrefix(user, prefix+"u"))
+	assert.LessOrEqual(t, len(user), 32)
+	assert.LessOrEqual(t, len(db), 64)
+}
+
 func TestBuildDSN(t *testing.T) {
 	dsn := BuildDSN("mysql", "mariadb", 3306, "user", "pass", "dbname")
 	assert.Contains(t, dsn, "user:pass@tcp(mariadb:3306)/dbname")