Module attach 

Registry of attached databases for cross-database queries.

The primary workspace opened by crate::engine::Engine is always addressable under the reserved alias "local". Callers can attach additional .hyper files under user-chosen aliases via AttachRegistry::attach; the registry tracks every live attachment so it can be replayed after an crate::error::ErrorCode::ConnectionLost auto-reconnect rebuilds the underlying Hyper connection.

Future kinds

AttachSource is a tagged enum so future remote kinds (TCP to a standard hyperd, gRPC to a Data 360 Hyper) plug in without breaking the registry API or the MCP tool schemas. Only AttachSource::LocalFile is implemented today; the MCP tool layer rejects other kind values with a clear “not yet supported” message.

Safety model

• Path policy. LocalFile paths must be absolute and canonicalized (.. components rejected) so the LLM cannot traverse outside the filesystem root via relative tricks.
• Alias policy. Aliases are validated as strict SQL identifiers ([A-Za-z_][A-Za-z0-9_]{0,62}) and cannot collide with "local".
• Read-only posture. Attachments default to read-only. Writable mode is opt-in and is still subject to the server-level --read-only guard — --read-only always wins.

Structs

AttachRegistry

Live set of attachments keyed by alias. Thread-safe via an internal Mutex; all operations are serial, which matches the rest of the engine’s single-connection model.

AttachRequest

Request shape for AttachRegistry::attach. Pre-validated by the MCP tool layer; the registry re-validates defensively because it is also the entry point for replay.

AttachedDb

One live attachment. Constructed by AttachRegistry::attach and returned unchanged until the alias is detached.

Enums

AttachSource

Where an attached database lives. Kind-tagged so future remote variants (TCP, gRPC) can slot in without breaking the registry API or MCP tool schemas.

OnMissing

Policy for what AttachRegistry::attach should do when the requested LocalFile path does not exist. Applies only to the local_file kind today; remote kinds (tcp, grpc) will ignore it.

Constants

LOCAL_ALIAS

Alias reserved for the server’s primary workspace. Users cannot attach under this name; copy_query treats target_database: "local" the same as the unqualified default.

Functions

validate_alias

Validate a user-supplied alias. Must match [A-Za-z_][A-Za-z0-9_]{0,62} and must not equal LOCAL_ALIAS. The 63-char cap matches the PostgreSQL identifier limit Hyper inherits.

validate_input_path

Validate a user-supplied file path that must already exist.

validate_local_path

Validate a LocalFile path. Must be absolute, must exist, must canonicalize cleanly with no .. components in the result. Returns the canonical path on success.

validate_local_path_for_create

Validate a LocalFile path for the create-if-missing code path.

validate_output_path

Validate a user-supplied output path that may not yet exist.