Struct ConnectionParams 

#[non_exhaustive]
pub struct ConnectionParams {

    pub host: Option<String>,
    pub port: Option<u16>,
    pub database: Option<String>,
    pub username: Option<String>,
    pub path: Option<String>,
    pub password: Option<String>,
    pub options: BTreeMap<String, String>,
    pub ssl_mode: SslMode,
    pub ssl_root_cert: Option<PathBuf>,
    pub ssl_cert: Option<PathBuf>,
    pub ssl_key: Option<PathBuf>,
    pub ssh: Option<SshConfig>,
    pub pre_connect: Vec<PreConnectStep>,
    pub color: Option<ConnectionColor>,
    pub confirm_writes: bool,
    pub read_only: bool,
}

Driver-agnostic connection parameters.

Each driver decides which fields are required; unused fields remain None. Engine-specific tuning is expressed through Self::options.

Marked #[non_exhaustive] so adding new optional fields (color, confirm_writes, read_only, future TLS knobs, …) is a non-breaking change. Construct with ..Default::default() or via the public setter pattern.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

host: Option<String>

port: Option<u16>

database: Option<String>

username: Option<String>

path: Option<String>

password: Option<String>

Optional password material declared in the configuration file.

v1.x stored passwords exclusively in the OS keyring (or fell back to ~/.pgpass / env vars). v2.0 accepts an optional in-file value so users can express:

• a literal password (discouraged, but supported for parity);
• an ${env:VAR} placeholder, expanded by narwhal_config::interpolate at load time — same vocabulary as every other string field;
• a vault reference: vault:hashicorp/<path>#<field> or 1password:op://Vault/Item/field, resolved at connect time by narwhal_config::vault::VaultRegistry.

Resolution order at runtime is:

1. If password is present and parses as a vault reference → the configured provider returns the secret.
2. If password is present and is not a reference → it is used verbatim (after env interpolation).
3. Else, the keyring is consulted by connection.id.
4. Else, the ~/.pgpass / env-var fallback runs.

The reference is stored as a plain String because that is the on-disk shape; the resolved secret is held in secrecy::SecretString from the moment the resolver runs.

options: BTreeMap<String, String>

ssl_mode: SslMode

TLS/SSL mode. Defaults to SslMode::Prefer for network drivers and SslMode::Disable for file-local drivers (sqlite, duckdb).

ssl_root_cert: Option<PathBuf>

Path to the CA/root certificate bundle (PEM format).

ssl_cert: Option<PathBuf>

Path to the client certificate (PEM format).

ssl_key: Option<PathBuf>

Path to the client private key (PEM format).

ssh: Option<SshConfig>

Optional SSH tunnel. When Some, crate::ssh::SshTunnel::spawn brings up a local-port-forward before the driver connects and rewrites host/port to the loopback side of the tunnel.

pre_connect: Vec<PreConnectStep>

L36 #7: ordered list of shell commands executed before the connection is opened. Each step’s stdout can be captured into a named variable and substituted into the remaining string fields of ConnectionParams via ${preconnect:NAME} placeholders. The canonical use case is fetching a short-lived password from a secrets manager (vault kv get …) or a kubectl pod IP before the driver dials in.

color: Option<ConnectionColor>

optional accent colour for the TUI border + status bar while this connection is active. None keeps the theme default. Production users typically set color = "red" so “am I on prod?” is answered by a glance at the screen edge.

confirm_writes: bool

when true, mutating statements (INSERT, UPDATE, DELETE, DDL, …) prompt for a confirmation modal before they reach the driver. Bare reads run without confirmation. Recommended on every connection that touches production data.

read_only: bool

when true, the session is opened in driver-enforced read-only mode (SET default_transaction_read_only TO ON on PG, PRAGMA query_only = ON on SQLite, etc.) and the TUI applies the same syntactic guard MCP uses (narwhal_sql::guard_read_only) before each run. Either layer rejecting the statement aborts it without driver round trip.

Implementations

impl ConnectionParams

pub fn with(f: impl FnOnce(&mut Self)) -> Self

Construct a ConnectionParams by mutating the default via f. The canonical way to build a ConnectionParams from outside the narwhal-core crate — the struct is marked #[non_exhaustive] so struct-literal construction (including functional update syntax ..Default::default()) is forbidden.

Minimal network connection:

use narwhal_core::ConnectionParams;
let p = ConnectionParams::with(|p| {
p.host = Some("db.local".into());
p.port = Some(5432);
});
assert_eq!(p.port, Some(5432));

Production-tagged connection with the v1.1 safety knobs:

use narwhal_core::{ConnectionColor, ConnectionParams};
let p = ConnectionParams::with(|p| {
p.host = Some("prod-db.example.com".into());
p.port = Some(5432);
p.database = Some("appdb".into());
p.color = Some(ConnectionColor::Red);
p.confirm_writes = true;
p.read_only = true;
});
assert_eq!(p.color, Some(ConnectionColor::Red));
assert!(p.read_only);

Trait Implementations

impl Clone for ConnectionParams

fn clone(&self) -> ConnectionParams

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConnectionParams

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConnectionParams

fn default() -> ConnectionParams

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ConnectionParams

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ConnectionParams

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.