currently, only one schema is supported in search_path

Error message

currently, only one schema is supported in search_path

What it means

JuiceFS's SQL metadata engine supports a `search_path` query parameter for PostgreSQL to select which schema holds the JuiceFS tables, but currently accepts only a single schema. If the URL's search_path contains multiple comma-separated schemas (valid for plain PostgreSQL clients), the client is rejected with this explicit error instead of silently choosing one.

Source

Thrown at pkg/meta/sql.go:477

	if encode := query.Encode(); encode != "" {
		addr = fmt.Sprintf("%s?%s", baseUrl, encode)
	} else {
		addr = baseUrl
	}

	if driver == "postgres" {
		addr = driver + "://" + addr
		driver = "pgx"

		parse, err := url.Parse(addr)
		if err != nil {
			return nil, fmt.Errorf("parse url %s failed: %s", addr, err)
		}
		searchPath = parse.Query().Get("search_path")
		if searchPath != "" {
			if len(strings.Split(searchPath, ",")) > 1 {
				return nil, fmt.Errorf("currently, only one schema is supported in search_path")
			}
		}
	}

	if driver == "sqlite3" {
		DirBatchNum["db"] = 4096 // SQLITE_MAX_VARIABLE_NUMBER limit
	}

	var engine *xorm.Engine
	if creator, ok := engineCreator[driver]; ok {
		engine, err = creator(addr)
	} else {
		engine, err = xorm.NewEngine(driver, addr)
	}
	if err != nil {
		return nil, fmt.Errorf("unable to use data source %s: %s", driver, err)
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

Edit the metadata URL so search_path contains exactly one schema, e.g. `?search_path=jfs`.
If tables exist in several schemas, use a separate JuiceFS volume per schema.
Drop the extra schemas inherited from other tools from the JuiceFS URL only.
Check release notes for updated multi-schema support before assuming the limitation persists.

Example fix

// before
--meta 'postgres://user:pass@host:5432/db?search_path=public,jfs'
// after
--meta 'postgres://user:pass@host:5432/db?search_path=jfs'

Defensive patterns

Strategy: validation

Validate before calling

sp := u.Query().Get("search_path")
if strings.Contains(sp, ",") {
    return errors.New("JuiceFS supports only a single schema in search_path")
}

Prevention

Always set search_path to a single dedicated schema for JuiceFS tables.
Keep other tools' multi-schema search_path out of the JuiceFS URL.
Document the intended schema next to the mount configuration.
Check release notes for multi-schema support before relying on it.

When it happens

Trigger: Formatting or mounting with a metadata URL like `postgres://user:pass@host/db?search_path=public,jfs` — a comma-separated multi-schema search_path — while creating the dbMeta client.

Common situations: Copying a PG connection string tuned for other tools that set a schema search order (`search_path=app,public`); inheriting a cluster-wide multi-schema default search_path; migrating volumes with both old and new schemas listed.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/674a09c9dc52058f. Report an issue: GitHub.