RPC Services UI Reference

This file documents the storage and management of RPC services in DBFlux.

DBFlux now persists a first-class RPC services foundation through RpcServiceKind:

• Driver — adapted into runtime database drivers
• AuthProvider — adapted into runtime auth-provider registries in both the app and the MCP server

Storage

RPC services are stored in SQLite at ~/.local/share/dbflux/dbflux.db, not in a JSON file.

Tables:

• cfg_services — main service record (socket_id, service_kind, command, startup_timeout_ms, enabled)
• cfg_services.api_family, cfg_services.api_major, cfg_services.api_minor — optional RPC API contract metadata
• cfg_service_args — ordered process arguments
• cfg_service_env — environment variables

Schema

-- Base table (migration 001). `service_kind` is added by migration 005 and
-- `api_family`/`api_major`/`api_minor` by migration 006; they are shown here
-- inline for reference but are not part of the base DDL.
CREATE TABLE cfg_services (
    socket_id TEXT PRIMARY KEY,
    enabled INTEGER DEFAULT 1,
    command TEXT,
    startup_timeout_ms INTEGER,        -- no SQL-level default; the 5000ms
                                       -- fallback (DEFAULT_STARTUP_TIMEOUT_MS)
                                       -- is applied in app code
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
    service_kind TEXT NOT NULL DEFAULT 'driver',  -- added by migration 005
    api_family TEXT,                              -- added by migration 006
    api_major INTEGER,                            -- added by migration 006
    api_minor INTEGER                             -- added by migration 006
);

CREATE TABLE cfg_service_args (
    id TEXT PRIMARY KEY,
    service_id TEXT NOT NULL REFERENCES cfg_services(socket_id),
    position INTEGER NOT NULL,
    value TEXT NOT NULL
);

CREATE TABLE cfg_service_env (
    id TEXT PRIMARY KEY,
    service_id TEXT NOT NULL REFERENCES cfg_services(socket_id),
    key TEXT NOT NULL,
    value TEXT NOT NULL
);

Managing Services

Services are managed through the Settings UI under the RPC Services section, not by editing files directly.

To add or edit a service:

1. Open Settings → RPC Services
2. Add a new service or select an existing one
3. Choose the service kind (Driver or Auth Provider)
4. Configure socket ID, command path, arguments, environment variables, and timeout
5. Save changes

Notes:

• Driver services are active in the runtime and keep the existing rpc:<socket_id> driver identity.
• Auth Provider services are active in runtime auth-provider registries only; they never appear as drivers.
• DBFlux preserves compatibility for driver registration IDs as rpc:<socket_id>.
• If API metadata is missing on an existing driver row, DBFlux defaults it to the current driver_rpc contract at version 1.1.
• If API metadata is missing on an auth-provider row, DBFlux defaults it to the current auth_provider_rpc contract at version 1.2.
• api_family / api_major are used as startup preflight for auth providers before DBFlux probes the socket.

Semantics

• socket_id is used literally as the socket filename
• DBFlux internally identifies each service as rpc:<socket_id>
• DBFlux classifies each service by service_kind before runtime adaptation
• Driver name/icon/category/form come from the service’s Hello response (driver_metadata, form_definition), not from configuration
• Services with service_kind='driver' that fail to complete the RPC handshake (Hello) during startup are not registered
• Services with service_kind='auth_provider' are loaded into auth-provider registries when they pass compatibility checks and probe successfully
• Driver-path negotiation selects the highest mutually supported compatible minor version during Hello, then requires every later envelope to use that exact negotiated version
• Auth-provider negotiation follows the same family/major/minor scheme under auth_provider_rpc; incompatible family or major versions are skipped before registration

Fields

• socket_id (required): local socket name used by DBFlux and the service.
  • Allowed characters: ASCII letters, numbers, ., _, -
  • Path separators, spaces, and other punctuation are rejected.
  • The value is passed to the platform socket namespace as-is, so keep it short and stable.
• command (optional): executable to run when DBFlux needs to start the service.
  • If omitted and args is also empty, DBFlux treats the service as already running and does not spawn anything.
  • For driver, if omitted and args is non-empty, DBFlux launches dbflux-driver-host.
  • For auth_provider, if DBFlux must launch the service, command must be set explicitly.
• args (optional): process arguments.
• env (optional): environment variables for the spawned process.
• startup_timeout_ms (optional): max wait time for socket readiness after spawn.
  • Default: 5000

Common Mistakes

• Mismatched socket names between the service configuration and service args
• Relative command path that does not resolve under the DBFlux process environment
• Editing the database directly instead of through the Settings UI
• Service not implementing required Hello fields for the current RPC protocol version
• Omitting command while providing partial args; if you want DBFlux to launch the default host, args must include both --driver and --socket.
• Configuring an auth-provider service with args but no command; DBFlux will reject that launch config instead of assuming the driver host