From fcf09c683fcf4e12b29e854074ae148400f1f753 Mon Sep 17 00:00:00 2001 From: sdairs Date: Mon, 16 Nov 2026 16:53:31 +0000 Subject: [PATCH 1/5] feat(local): run local Postgres natively from a downloaded bundle (#1464) Prototype. `local postgres start` now runs a postmaster from a portable PostgreSQL + pg_clickhouse bundle instead of a Docker container; `--docker` keeps the container runtime, and an instance keeps the runtime it was created with. - pg_bundle: manifest fetch (no credentials), mandatory sha256 check before extraction, cache in ~/.clickhouse/postgres keyed on name + sha256 prefix, atomic install, cache-first resolution so resumes work offline. - pg_native: initdb via --pwfile with scram-sha-256 and the builtin C.UTF-8 locale, loopback-only postmaster in its own process group, pg_isready readiness, SIGINT then SIGQUIT stop guarded by postmaster.pid and cwd, 0600 state file with credentials and the bundle identity last used. - postgres: one runtime decision for start (select_start_runtime) and ServerInfo::pg_runtime for everything else; Docker-only options and root are usage errors. - `local install postgres@` installs the bundle; `--docker` pulls the image. Co-Authored-By: Claude Fable 5.2 --- crates/clickhousectl/src/error.rs | 17 + crates/clickhousectl/src/local/cli.rs | 64 +- crates/clickhousectl/src/local/mod.rs | 47 +- crates/clickhousectl/src/local/output.rs | 75 +- crates/clickhousectl/src/local/pg_bundle.rs | 773 +++++++++++++++++ crates/clickhousectl/src/local/pg_native.rs | 498 +++++++++++ crates/clickhousectl/src/local/postgres.rs | 813 +++++++++++++++++- crates/clickhousectl/src/local/server.rs | 65 +- .../src/version_manager/download.rs | 12 + scripts/classify-install-integration.py | 3 + .../test_classify_install_integration.py | 3 + 11 files changed, 2277 insertions(+), 93 deletions(-) create mode 100644 crates/clickhousectl/src/local/pg_bundle.rs create mode 100644 crates/clickhousectl/src/local/pg_native.rs diff --git a/crates/clickhousectl/src/error.rs b/crates/clickhousectl/src/error.rs index 2eea62402..f03c0d367 100644 --- a/crates/clickhousectl/src/error.rs +++ b/crates/clickhousectl/src/error.rs @@ -639,6 +639,23 @@ pub enum Error { #[error("Postgres error: {0}")] PostgresUsage(String), + /// No usable Postgres bundle for the native runtime: the manifest is not + /// readable by this version, or names nothing for this request and + /// platform. Self-composed, including its recovery guidance. + #[error("Postgres bundle unavailable: {0}")] + PostgresBundleUnavailable(String), + + /// A downloaded Postgres bundle does not match the sha256 its manifest + /// names; nothing was extracted or installed. + #[error( + "Postgres bundle '{file}' failed verification: expected sha256 {expected}, got {actual}; nothing was installed" + )] + PostgresBundleChecksum { + file: String, + expected: String, + actual: String, + }, + /// A child process whose status must be returned unchanged. This is /// intentionally not printed as a clickhousectl error by `run_parsed`. #[error("child process exited with code {0}")] diff --git a/crates/clickhousectl/src/local/cli.rs b/crates/clickhousectl/src/local/cli.rs index 212b17b56..1271196bc 100644 --- a/crates/clickhousectl/src/local/cli.rs +++ b/crates/clickhousectl/src/local/cli.rs @@ -136,7 +136,8 @@ const INSTALL_AFTER_HELP: &str = "\ CONTEXT FOR AGENTS: The first ClickHouse version installed becomes the default; later installs do not change it. `clickhousectl local use ` auto-installs a missing version and sets it as default. - `postgres@` pulls a Docker image instead (needs Docker running) and never sets a default. + `postgres@` (17, 18 or .) downloads a PostgreSQL build with pg_clickhouse + for `local postgres`; with --docker it pulls that image tag instead. Neither sets a default. --binary copies the file (e.g. build/programs/clickhouse) and installs it as the version its `--version` reports; rebuild and pass --force to replace that version."; @@ -306,12 +307,13 @@ CONTEXT FOR AGENTS: command: ServerCommands, }, - /// Manage local Postgres instances (Docker-backed) + /// Manage local Postgres instances #[command( visible_alias = "pg", after_help = "\ CONTEXT FOR AGENTS: - Requires Docker installed and running. + Runs a downloaded PostgreSQL build with pg_clickhouse (`CREATE EXTENSION pg_clickhouse` can + query a `local clickhouse` server); `start --docker` runs a Postgres image instead. Each instance is keyed on (name, major version); pass --version when one name has two majors. Omitting NAME selects \"default\", else the only instance name; several without \"default\" errors listing them. `remove` never guesses: it takes only \"default\" or an explicit name. @@ -393,13 +395,13 @@ CONTEXT FOR AGENTS: args: Vec, }, - /// Install a ClickHouse version or Postgres image + /// Install a ClickHouse version or a Postgres build #[command( after_help = INSTALL_AFTER_HELP, group(ArgGroup::new("source").args(["version", "binary"]).required(true)) )] Install { - /// Version ("latest", "stable", "lts", 25.12, 25.12.9.61) or image selector (postgres@18) + /// Version ("latest", "stable", "lts", 25.12, 25.12.9.61) or Postgres selector (postgres@18) version: Option, /// Install a local ClickHouse build under the version it reports @@ -409,6 +411,10 @@ CONTEXT FOR AGENTS: /// Re-install even if already installed #[arg(long)] force: bool, + + /// Pull the Postgres Docker image instead; only with postgres@ + #[arg(long, conflicts_with = "binary")] + docker: bool, }, /// List installed or available ClickHouse versions @@ -684,13 +690,14 @@ pub enum PostgresCommands { /// Start a Postgres instance #[command(after_help = "\ CONTEXT FOR AGENTS: - An existing stopped instance for the same (name, major) is resumed with its stored settings, so - --port/--user/--password/--database/-e are ignored on a resume. A resume whose stored port another - process holds fails with port_in_use; free that port, then start again. + The first start of a version downloads its PostgreSQL build; later starts work offline. + An existing stopped instance for the same (name, major) is resumed in its own runtime with its + stored settings, so --port/--user/--password/--database/-e are ignored on a resume. A resume + whose stored port another process holds fails with port_in_use; free that port, then start again. Without --version, an existing instance selects the major; two majors under one name error. The generated password is printed once by start — re-read connection details later with `postgres dotenv` or `postgres client`. - A failed fresh start rolls back the container and data it created; pre-existing data is kept.")] + A failed fresh start rolls back what it created; pre-existing data is kept.")] Start { /// Server name (default: "default", or random if default is already running) #[arg(value_name = "NAME", conflicts_with = "name_flag", value_parser = parse_pg_server_name_arg, add = complete_postgres_servers())] @@ -706,9 +713,9 @@ CONTEXT FOR AGENTS: )] name_flag: Option, - /// Postgres image tag, major 17 or 18 (e.g. 17-alpine, 18.1). Default: 18 + /// Postgres version: 17, 18 or .. Default: 18 /// - /// Pulls the image if it is not present locally. + /// With --docker, any 17 or 18 image tag (e.g. 17-alpine, 18-bookworm). #[arg(long, short = 'v', value_parser = crate::local::postgres::parse_pg_tag_arg)] version: Option, @@ -718,19 +725,19 @@ CONTEXT FOR AGENTS: #[arg(long, value_parser = parse_port_arg)] port: Option, - /// POSTGRES_USER (default: postgres) + /// Superuser name (default: postgres) #[arg(long)] user: Option, - /// POSTGRES_PASSWORD (default: random 24-char alphanumeric) + /// Superuser password (default: random 24-char alphanumeric) #[arg(long)] password: Option, - /// POSTGRES_DB (default: postgres) + /// Database to create (default: postgres) #[arg(long)] database: Option, - /// Extra container env vars; repeatable, each key at most once + /// Container env vars, repeatable, one per key; only with --docker /// /// POSTGRES_USER, POSTGRES_DB and PGDATA are managed and rejected here — use /// --user/--database. POSTGRES_PASSWORD is accepted, but not together with --password. @@ -742,6 +749,12 @@ CONTEXT FOR AGENTS: )] env: Vec, + /// Run a Postgres Docker image instead (needs Docker running) + /// + /// Applies to a new instance; an existing one keeps its runtime. + #[arg(long)] + docker: bool, + /// Seconds to wait for PostgreSQL readiness (maximum: 600) #[arg( long, @@ -782,11 +795,11 @@ CONTEXT FOR AGENTS: /// Stop all Postgres instances in this project StopAll, - /// Remove a stopped Postgres instance and its data + /// Remove a Postgres instance and its data #[command(after_help = "\ CONTEXT FOR AGENTS: - Irreversible: removes the container and deletes its data directory. Stop the instance first — - removing a running one errors.")] + Irreversible: deletes the instance's data directory, and its container if it has one. A + running native instance is stopped first; stop a Docker one before removing it.")] Remove { /// Name of the instance to remove (default: "default") #[arg(value_name = "NAME", conflicts_with = "name_flag", value_parser = parse_pg_server_name_arg, add = complete_postgres_servers())] @@ -810,8 +823,8 @@ CONTEXT FOR AGENTS: /// Connect to a running Postgres instance with psql #[command(after_help = "\ CONTEXT FOR AGENTS: - Managed mode (the default; NAME selects one) execs host `psql` when it is on PATH, else runs - psql inside the container via `docker exec`. + Managed mode (the default; NAME selects one) runs the `psql` that ships with the instance's + PostgreSQL build. For a Docker instance it uses host `psql` when on PATH, else the container's. Direct mode (--host/--port) requires `psql` on PATH and connects as user/database \"postgres\" with no password; it does not read managed credentials. Put wrapper options before `--`; all arguments after it go to psql. @@ -1302,6 +1315,7 @@ mod tests { version: None, binary: Some(binary), force: true, + docker: false, } = local_command(&[ "install", "--binary", @@ -1325,6 +1339,16 @@ mod tests { "{version}" ); } + // --docker selects how a Postgres selector installs, never a binary. + assert_eq!( + local_parse_error(&["install", "--binary", "./clickhouse", "--docker"]).kind(), + clap::error::ErrorKind::ArgumentConflict + ); + let LocalCommands::Install { docker: true, .. } = + local_command(&["install", "postgres@18-bookworm", "--docker"]) + else { + panic!("expected a Docker image install"); + }; } #[test] diff --git a/crates/clickhousectl/src/local/mod.rs b/crates/clickhousectl/src/local/mod.rs index 91e986e91..61645966a 100644 --- a/crates/clickhousectl/src/local/mod.rs +++ b/crates/clickhousectl/src/local/mod.rs @@ -3,6 +3,8 @@ pub mod config; pub mod discovery; pub mod docker; pub mod output; +pub(crate) mod pg_bundle; +pub(crate) mod pg_native; pub mod postgres; pub(crate) mod procinfo; pub mod server; @@ -28,9 +30,10 @@ pub async fn run(cmd: LocalCommands, json: bool) -> Result<()> { version, binary, force, + docker, } => match (version, binary) { (None, Some(binary)) => install_binary(&binary, force, json).await, - (Some(version), None) => install(version, force, json).await, + (Some(version), None) => install(version, force, docker, json).await, _ => unreachable!("clap requires exactly one of a version or --binary"), }, LocalCommands::List { remote } => { @@ -82,8 +85,33 @@ pub async fn run(cmd: LocalCommands, json: bool) -> Result<()> { } } -async fn install_postgres(tag: &str, force: bool, json: bool) -> Result<()> { +/// `local install postgres@`: fetch the native bundle, or with +/// `--docker` pull the image. +async fn install_postgres(tag: &str, force: bool, docker: bool, json: bool) -> Result<()> { postgres::validate_pg_tag(tag)?; + if docker { + return install_postgres_image(tag, force, json).await; + } + let Some(request) = pg_bundle::PgVersionRequest::parse(tag) else { + return Err(Error::usage( + clap::error::ErrorKind::ArgumentConflict, + format!( + "postgres@{tag} is a Docker image tag; add `--docker` to pull it, or use 17, 18 \ + or . for a native PostgreSQL build" + ), + )); + }; + pg_native::reject_root()?; + let bundle = pg_bundle::ensure_bundle(&request, force, json).await?; + let out = output::InstallOutput { + version: format!("postgres@{}", bundle.spec.postgres_version), + set_as_default: false, + }; + output::print_output(&out, json); + Ok(()) +} + +async fn install_postgres_image(tag: &str, force: bool, json: bool) -> Result<()> { let docker = docker::connect().await?; if !force && docker::image_exists(&docker, tag).await? { let out = output::InstallOutput { @@ -107,11 +135,19 @@ async fn install_postgres(tag: &str, force: bool, json: bool) -> Result<()> { Ok(()) } -async fn install(version: InstallVersionArg, force: bool, json: bool) -> Result<()> { +async fn install(version: InstallVersionArg, force: bool, docker: bool, json: bool) -> Result<()> { let spec = match version { InstallVersionArg::ClickHouse(spec) => spec, - InstallVersionArg::Postgres(tag) => return install_postgres(&tag, force, json).await, + InstallVersionArg::Postgres(tag) => { + return install_postgres(&tag, force, docker, json).await; + } }; + if docker { + return Err(Error::usage( + clap::error::ErrorKind::ArgumentConflict, + "--docker applies only to a Postgres selector such as postgres@18", + )); + } let platform = version_manager::platform::Platform::detect()?; let version = @@ -1306,7 +1342,8 @@ pub(crate) fn list_project_servers(list: output::ProjectList, json: bool) -> Res match e.info { Some(info) => { let is_ch = info.engine == server::Engine::Clickhouse; - let pid = if is_ch && running { + let native_pg = info.pg_runtime() == Some(server::PgRuntime::Native); + let pid = if (is_ch || native_pg) && running { Some(info.pid) } else { None diff --git a/crates/clickhousectl/src/local/output.rs b/crates/clickhousectl/src/local/output.rs index 5a9c13932..4fc00bc93 100644 --- a/crates/clickhousectl/src/local/output.rs +++ b/crates/clickhousectl/src/local/output.rs @@ -94,6 +94,11 @@ pub(crate) enum LocalErrorCode { /// A Postgres validation or state error whose text (and recovery /// guidance) clickhousectl composes itself, rendered verbatim. PostgresError, + /// No Postgres bundle can be used for the native runtime: the manifest + /// is unreadable by this version or has nothing for the request. + PostgresBundleUnavailable, + /// A downloaded Postgres bundle did not match its manifest sha256. + ChecksumMismatch, SqlInputOpenFailed, SqlInputReadFailed, /// A managed server metadata file contains invalid JSON. The structured @@ -153,6 +158,8 @@ impl LocalErrorCode { Self::DockerError => "docker_error", Self::ContainerNameConflict => "container_name_conflict", Self::PostgresError => "postgres_error", + Self::PostgresBundleUnavailable => "postgres_bundle_unavailable", + Self::ChecksumMismatch => "checksum_mismatch", Self::SqlInputOpenFailed => "sql_input_open_failed", Self::SqlInputReadFailed => "sql_input_read_failed", Self::ServerMetadataInvalid => "server_metadata_invalid", @@ -761,6 +768,15 @@ impl LocalErrorBody { // Self-composed validation and state guidance; the foreign-text // sibling `Error::Postgres` stays in the fallback below. Error::PostgresUsage(_) => Mapping::parity(LocalErrorCode::PostgresError), + // Self-composed; `--docker` is the way around a missing bundle. + Error::PostgresBundleUnavailable(_) => { + Mapping::parity(LocalErrorCode::PostgresBundleUnavailable) + .command("clickhousectl local postgres start --help") + } + // Bundle name and digests only, all from the manifest and file. + Error::PostgresBundleChecksum { .. } => { + Mapping::parity(LocalErrorCode::ChecksumMismatch) + } // The OS cause goes in `details`; the path stays out. Error::SqlInputOpen { source, .. } => Mapping::redacted( LocalErrorCode::SqlInputOpenFailed, @@ -1778,17 +1794,15 @@ impl fmt::Display for ServerListOutput { }); Table::new(rows) } - // Lists that can hold Postgres combine the ClickHouse PID and the - // Postgres container short ID into one "ID" column. + // Lists that can hold Postgres combine the PID of a process and + // the short ID of a Postgres container into one "ID" column. ServerList::Project(ProjectList::Postgres | ProjectList::Status) => { let rows = self.servers.iter().map(|e| { - let id = if e.engine == "postgres" { - e.container_id - .as_deref() - .map(|s| s.chars().take(12).collect::()) - .unwrap_or_else(|| ABSENT.to_string()) - } else { - or_absent(e.pid) + // A Docker instance has a container; a ClickHouse server + // and a native Postgres instance have a PID. + let id = match e.container_id.as_deref() { + Some(container) => container.chars().take(12).collect::(), + None => or_absent(e.pid), }; ServerListRowWithEngine { name: e.name.clone(), @@ -1817,11 +1831,29 @@ impl fmt::Display for ServerListOutput { // ── postgres start ────────────────────────────────────────────────────────── +/// How a Postgres instance is run. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "lowercase")] +pub enum PostgresRuntime { + Native, + Docker, +} + #[derive(Debug, Clone, Serialize)] pub struct PostgresStartOutput { pub name: String, - pub container_id: String, + pub runtime: PostgresRuntime, + /// The container, for the Docker runtime. + #[serde(skip_serializing_if = "Option::is_none")] + pub container_id: Option, + /// The postmaster, for the native runtime. + #[serde(skip_serializing_if = "Option::is_none")] + pub pid: Option, + /// `postgres:` for Docker, `postgres:` for native. pub image: String, + /// Extensions the native bundle ships, by name and version. + #[serde(skip_serializing_if = "std::collections::BTreeMap::is_empty")] + pub extensions: std::collections::BTreeMap, pub port: u16, pub user: String, pub password: String, @@ -1830,9 +1862,25 @@ pub struct PostgresStartOutput { impl fmt::Display for PostgresStartOutput { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let short = self.container_id.chars().take(12).collect::(); - writeln!(f, "Postgres '{}' running (container: {})", self.name, short)?; - writeln!(f, " Image: {}", self.image)?; + match (&self.container_id, self.pid) { + (Some(container_id), _) => { + let short = container_id.chars().take(12).collect::(); + writeln!(f, "Postgres '{}' running (container: {})", self.name, short)?; + writeln!(f, " Image: {}", self.image)?; + } + (None, pid) => { + match pid { + Some(pid) => writeln!(f, "Postgres '{}' running (PID: {})", self.name, pid)?, + None => writeln!(f, "Postgres '{}' running", self.name)?, + } + let version = self.image.strip_prefix("postgres:").unwrap_or(&self.image); + write!(f, " Version: {version}")?; + for (name, version) in &self.extensions { + write!(f, ", {name} {version}")?; + } + writeln!(f)?; + } + } writeln!(f, " Port: {}", self.port)?; writeln!(f, " User: {}", self.user)?; writeln!(f, " Password: {}", self.password)?; @@ -3873,6 +3921,7 @@ mod tests { )), binary: None, force: false, + docker: false, } ), "{argv:?}" diff --git a/crates/clickhousectl/src/local/pg_bundle.rs b/crates/clickhousectl/src/local/pg_bundle.rs new file mode 100644 index 000000000..421faf951 --- /dev/null +++ b/crates/clickhousectl/src/local/pg_bundle.rs @@ -0,0 +1,773 @@ +//! Portable PostgreSQL bundles for the native `local postgres` runtime. +//! +//! A bundle is a prebuilt PostgreSQL plus pg_clickhouse for one target, +//! published as a tarball next to a `manifest.json` that names its sha256. +//! This module resolves a requested version to a bundle, downloads and +//! verifies it, and keeps extracted bundles in `~/.clickhouse/postgres/`. +//! Running them is `local::pg_native`'s job. + +use crate::error::{Error, NetworkStage, Result}; +use crate::paths; +use crate::version_manager::network; +use crate::version_manager::platform::{Arch, Os, Platform}; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeMap; +use std::io::Read; +use std::path::{Path, PathBuf}; + +/// Replaces the bundle source: an `https://` base URL or a `file:///abs/dir` +/// holding `manifest.json` and the tarballs (see `docs/development.md`). +pub(crate) const BUNDLES_URL_ENV: &str = "CLICKHOUSECTL_POSTGRES_BUNDLES_URL"; +/// Where `manifest.json` and the tarballs it names are published. No request +/// to it, or to anything it redirects to, carries credentials. +const DEFAULT_BUNDLES_URL: &str = "https://github.com/sdairs/pg-bundles/releases/latest/download"; +const MANIFEST_FILE: &str = "manifest.json"; +const SUPPORTED_SCHEMA: u64 = 1; +const ARCHIVE_SUFFIX: &str = ".tar.gz"; +/// Written into an extracted bundle before it is renamed into the cache, so a +/// directory that has it is complete. +const MARKER_FILE: &str = "clickhousectl-bundle.json"; +const KEY_SHA_PREFIX_LEN: usize = 12; +const STAGING_PREFIX: &str = ".staging-"; + +/// Majors the native runtime and the Docker image tags both accept. +pub(crate) const SUPPORTED_MAJORS: [&str; 2] = ["17", "18"]; + +/// One bundle as the manifest describes it. Also the cache marker's content. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub(crate) struct BundleSpec { + pub postgres_version: String, + pub postgres_major: String, + #[serde(default)] + pub extensions: BTreeMap, + pub target: String, + pub file: String, + pub sha256: String, +} + +impl BundleSpec { + /// The bundle's name: its file name without the archive suffix, which is + /// also the tarball's single top-level directory. + pub(crate) fn name(&self) -> &str { + self.file.strip_suffix(ARCHIVE_SUFFIX).unwrap_or(&self.file) + } + + /// The cache directory name. The sha256 prefix keeps a rebuilt bundle + /// published under the same name apart from the one already extracted. + fn cache_key(&self) -> String { + format!("{}-{}", self.name(), &self.sha256[..KEY_SHA_PREFIX_LEN]) + } + + fn version_key(&self) -> Vec { + version_key(&self.postgres_version) + } + + /// Reject a manifest entry this CLI would not install safely. + fn validate(&self) -> std::result::Result<(), String> { + let name = self + .file + .strip_suffix(ARCHIVE_SUFFIX) + .ok_or_else(|| format!("bundle file '{}' is not a {ARCHIVE_SUFFIX}", self.file))?; + let name_ok = !name.is_empty() + && !name.starts_with('.') + && name + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-')); + if !name_ok { + return Err(format!( + "bundle file '{}' is not a plain file name", + self.file + )); + } + if self.sha256.len() != 64 || !self.sha256.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(format!( + "bundle '{}' has no valid sha256 in the manifest", + self.file + )); + } + Ok(()) + } +} + +fn version_key(version: &str) -> Vec { + version + .split('.') + .map(|part| part.parse().unwrap_or(0)) + .collect() +} + +/// A Postgres version the native runtime can serve: a major, or `major.minor`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct PgVersionRequest { + pub major: String, + /// The full `major.minor` when the user pinned one. + pub exact: Option, +} + +impl PgVersionRequest { + pub(crate) fn major(major: &str) -> Self { + Self { + major: major.to_string(), + exact: None, + } + } + + /// `17`, `18` or `.`. `None` for anything else, such as a + /// Docker image tag with a variant (`18-bookworm`). + pub(crate) fn parse(tag: &str) -> Option { + let (major, minor) = match tag.split_once('.') { + Some((major, minor)) => (major, Some(minor)), + None => (tag, None), + }; + if !SUPPORTED_MAJORS.contains(&major) { + return None; + } + match minor { + None => Some(Self::major(major)), + Some(minor) if !minor.is_empty() && minor.chars().all(|c| c.is_ascii_digit()) => { + Some(Self { + major: major.to_string(), + exact: Some(tag.to_string()), + }) + } + Some(_) => None, + } + } + + fn matches(&self, spec: &BundleSpec) -> bool { + spec.postgres_major == self.major + && self + .exact + .as_deref() + .is_none_or(|exact| version_key(exact) == spec.version_key()) + } + + fn label(&self) -> &str { + self.exact.as_deref().unwrap_or(&self.major) + } +} + +/// An extracted bundle in the cache. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct InstalledBundle { + pub dir: PathBuf, + pub spec: BundleSpec, +} + +impl InstalledBundle { + pub(crate) fn bin(&self, program: &str) -> PathBuf { + self.dir.join("bin").join(program) + } +} + +/// The bundle target for a platform. Linux is always musl: the bundle ships +/// its own loader, so one build serves every distribution. +pub(crate) fn target_triple(platform: Platform) -> &'static str { + match (platform.os, platform.arch) { + (Os::MacOS, Arch::Aarch64) => "aarch64-apple-darwin", + (Os::MacOS, Arch::X86_64) => "x86_64-apple-darwin", + (Os::Linux, Arch::Aarch64) => "aarch64-unknown-linux-musl", + (Os::Linux, Arch::X86_64) => "x86_64-unknown-linux-musl", + } +} + +fn cache_root() -> Result { + Ok(paths::base_dir()?.join("postgres")) +} + +/// Parse a manifest and return its bundles. An unknown `schema` is rejected +/// before anything else is read, since its fields may mean something else. +fn parse_manifest(bytes: &[u8]) -> Result> { + #[derive(Deserialize)] + struct Schema { + schema: u64, + } + #[derive(Deserialize)] + struct Manifest { + #[serde(default)] + bundles: Vec, + } + let invalid = || Error::PostgresBundleUnavailable("the bundle manifest is not valid".into()); + let schema: Schema = serde_json::from_slice(bytes).map_err(|_| invalid())?; + if schema.schema != SUPPORTED_SCHEMA { + return Err(Error::PostgresBundleUnavailable(format!( + "the bundle manifest has schema {}, and this clickhousectl reads schema \ + {SUPPORTED_SCHEMA}; run `clickhousectl update`", + schema.schema + ))); + } + let manifest: Manifest = serde_json::from_slice(bytes).map_err(|_| invalid())?; + Ok(manifest.bundles) +} + +/// The newest bundle for `target` that satisfies `request`. +fn select_newest<'a>( + bundles: impl IntoIterator, + target: &str, + request: &PgVersionRequest, +) -> Option<&'a BundleSpec> { + bundles + .into_iter() + .filter(|spec| spec.target == target && request.matches(spec)) + .max_by_key(|spec| spec.version_key()) +} + +/// Every complete bundle in `root`. Unreadable or foreign entries are skipped: +/// the cache is a cache, and a start can always install again. +fn installed_in(root: &Path) -> Vec { + let Ok(entries) = std::fs::read_dir(root) else { + return Vec::new(); + }; + entries + .filter_map(|entry| { + let dir = entry.ok()?.path(); + if dir.file_name()?.to_str()?.starts_with('.') { + return None; + } + let marker = std::fs::read(dir.join(MARKER_FILE)).ok()?; + let spec: BundleSpec = serde_json::from_slice(&marker).ok()?; + Some(InstalledBundle { dir, spec }) + }) + .collect() +} + +fn newest_installed_in( + root: &Path, + target: &str, + request: &PgVersionRequest, +) -> Option { + let installed = installed_in(root); + let newest = select_newest(installed.iter().map(|b| &b.spec), target, request)?.clone(); + installed.into_iter().find(|bundle| bundle.spec == newest) +} + +/// The newest cached bundle for `request` on this machine. Never uses the +/// network, so resuming an instance works offline. +pub(crate) fn newest_installed(request: &PgVersionRequest) -> Result> { + let target = target_triple(Platform::detect()?); + Ok(newest_installed_in(&cache_root()?, target, request)) +} + +/// Where bundles come from. +#[derive(Debug, Clone, PartialEq, Eq)] +enum BundleSource { + Https(url::Url), + Directory(PathBuf), +} + +impl BundleSource { + fn from_env() -> Result { + Self::parse(std::env::var(BUNDLES_URL_ENV).ok().as_deref()) + } + + fn parse(override_url: Option<&str>) -> Result { + let raw = override_url + .map(str::trim) + .filter(|value| !value.is_empty()) + .unwrap_or(DEFAULT_BUNDLES_URL); + let invalid = || { + Error::PostgresBundleUnavailable(format!( + "{BUNDLES_URL_ENV} must be an https:// URL or a file:///absolute/directory" + )) + }; + // A trailing slash makes `join` resolve files inside the base rather + // than beside its last segment. + let base = if raw.ends_with('/') { + raw.to_string() + } else { + format!("{raw}/") + }; + let url = url::Url::parse(&base).map_err(|_| invalid())?; + match url.scheme() { + "https" => Ok(Self::Https(url)), + "file" => url + .to_file_path() + .map(Self::Directory) + .map_err(|_| invalid()), + _ => Err(invalid()), + } + } + + async fn manifest(&self) -> Result> { + match self { + Self::Directory(dir) => Ok(std::fs::read(dir.join(MANIFEST_FILE))?), + Self::Https(base) => { + let url = base + .join(MANIFEST_FILE) + .expect("a file name joins onto a base URL") + .to_string(); + let stage = NetworkStage::Download; + let client = network::client(network::METADATA_POLICY, stage, &url)?; + let fetch = async { + let response = network::send(client.get(&url), stage, &url).await?; + let response = network::ensure_success(response, stage, &url)?; + response + .bytes() + .await + .map(|bytes| bytes.to_vec()) + .map_err(|error| network::failure_from_reqwest(stage, &url, &error)) + }; + Ok(network::with_operation_timeout( + network::RESOLUTION_OPERATION_TIMEOUT, + stage, + &url, + fetch, + ) + .await??) + } + } + } + + /// Fetch `spec`'s tarball to `dest`. `spec.file` was validated as a plain + /// file name, so it cannot point outside the source. + async fn fetch(&self, spec: &BundleSpec, dest: &Path, json: bool) -> Result<()> { + match self { + Self::Directory(dir) => { + std::fs::copy(dir.join(&spec.file), dest)?; + Ok(()) + } + Self::Https(base) => { + let url = base + .join(&spec.file) + .expect("a file name joins onto a base URL"); + crate::version_manager::download::download_file(url.as_str(), dest, json).await + } + } + } +} + +fn sha256_file(path: &Path) -> Result { + use sha2::{Digest, Sha256}; + let mut file = std::fs::File::open(path)?; + let mut hasher = Sha256::new(); + let mut buffer = vec![0_u8; 1024 * 1024]; + loop { + let read = file.read(&mut buffer)?; + if read == 0 { + break; + } + hasher.update(&buffer[..read]); + } + Ok(hasher + .finalize() + .iter() + .map(|byte| format!("{byte:02x}")) + .collect()) +} + +/// Check a downloaded tarball against the manifest's sha256 before anything +/// reads its contents. +fn verify_sha256(archive: &Path, spec: &BundleSpec) -> Result<()> { + let actual = sha256_file(archive)?; + if actual.eq_ignore_ascii_case(&spec.sha256) { + Ok(()) + } else { + Err(Error::PostgresBundleChecksum { + file: spec.file.clone(), + expected: spec.sha256.to_ascii_lowercase(), + actual, + }) + } +} + +/// A staging directory under the cache root, removed when dropped. +struct Staging(PathBuf); + +impl Staging { + fn create(root: &Path) -> Result { + paths::ensure_dir(root)?; + let path = root.join(format!("{STAGING_PREFIX}{}", uuid::Uuid::new_v4())); + std::fs::create_dir(&path)?; + Ok(Self(path)) + } +} + +impl Drop for Staging { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// Unpack a verified tarball into `staging` and return its bundle directory. +fn extract(archive: &Path, staging: &Path, spec: &BundleSpec) -> Result { + let extraction_error = |source| Error::ExtractArchive { + archive: archive.to_path_buf(), + destination: staging.to_path_buf(), + source, + }; + let file = std::fs::File::open(archive).map_err(extraction_error)?; + let mut tar = tar::Archive::new(flate2::read::GzDecoder::new(file)); + // `unpack` refuses entries that would land outside `staging`. + tar.unpack(staging).map_err(extraction_error)?; + // tar stops at its end-of-archive blocks; reading on validates the gzip + // trailer. + std::io::copy(&mut tar.into_inner(), &mut std::io::sink()).map_err(extraction_error)?; + + let dir = staging.join(spec.name()); + if !dir.join("bin").join("postgres").is_file() { + return Err(Error::Extract(format!( + "bundle '{}' does not contain {}/bin/postgres", + spec.file, + spec.name() + ))); + } + Ok(dir) +} + +/// Download, verify and extract `spec` into `root`, returning the cached +/// bundle. The extracted directory is renamed into place in one step, so a +/// concurrent installer of the same bundle either wins or is used. +async fn install_into( + root: &Path, + source: &BundleSource, + spec: &BundleSpec, + force: bool, + json: bool, +) -> Result { + let staging = Staging::create(root)?; + let archive = staging.0.join(&spec.file); + if !json { + eprintln!( + "Downloading PostgreSQL {} for {}...", + spec.postgres_version, spec.target + ); + } + source.fetch(spec, &archive, json).await?; + verify_sha256(&archive, spec)?; + + let unpack_dir = staging.0.join("unpack"); + std::fs::create_dir(&unpack_dir)?; + let extracted = extract(&archive, &unpack_dir, spec)?; + std::fs::write( + extracted.join(MARKER_FILE), + serde_json::to_vec_pretty(spec)?, + )?; + + let dir = root.join(spec.cache_key()); + if force && dir.exists() { + // Move the old copy aside first: a running postmaster keeps its open + // files, and the staging guard deletes the directory afterwards. + std::fs::rename(&dir, staging.0.join("replaced"))?; + } + match std::fs::rename(&extracted, &dir) { + Ok(()) => {} + // Another installer finished first; its copy passed the same check. + Err(_) if dir.join(MARKER_FILE).is_file() => {} + Err(error) => return Err(error.into()), + } + Ok(InstalledBundle { + dir, + spec: spec.clone(), + }) +} + +/// Make the newest bundle for `request` available and return it. +/// +/// Reads the manifest, then uses the cached copy of the bundle it names or +/// installs it. When the manifest cannot be fetched, a cached bundle for the +/// request is used instead, so a start works offline. `force` installs again +/// even when cached, and then needs the manifest. +pub(crate) async fn ensure_bundle( + request: &PgVersionRequest, + force: bool, + json: bool, +) -> Result { + let target = target_triple(Platform::detect()?); + let root = cache_root()?; + let source = BundleSource::from_env()?; + ensure_bundle_in(&root, &source, target, request, force, json).await +} + +async fn ensure_bundle_in( + root: &Path, + source: &BundleSource, + target: &str, + request: &PgVersionRequest, + force: bool, + json: bool, +) -> Result { + let manifest = match source.manifest().await { + Ok(bytes) => bytes, + Err(error) => { + let cached = (!force) + .then(|| newest_installed_in(root, target, request)) + .flatten(); + let Some(cached) = cached else { + return Err(error); + }; + if !json { + eprintln!( + "Note: could not check for a newer PostgreSQL bundle; using installed {}", + cached.spec.postgres_version + ); + } + return Ok(cached); + } + }; + let bundles = parse_manifest(&manifest)?; + let spec = select_newest(&bundles, target, request).ok_or_else(|| { + Error::PostgresBundleUnavailable(format!( + "no PostgreSQL {} bundle is published for {target}; use `--docker` to run a \ + Postgres image instead", + request.label() + )) + })?; + spec.validate().map_err(Error::PostgresBundleUnavailable)?; + + if !force + && let Some(cached) = installed_in(root) + .into_iter() + .find(|bundle| bundle.spec == *spec) + { + return Ok(cached); + } + install_into(root, source, spec, force, json).await +} + +/// The bundle an existing instance of `major` starts with: the newest cached +/// one, since data directories are compatible across minors of a major. Only +/// an empty cache reaches the network. +pub(crate) async fn bundle_for_existing(major: &str, json: bool) -> Result { + let request = PgVersionRequest::major(major); + match newest_installed(&request)? { + Some(bundle) => Ok(bundle), + None => ensure_bundle(&request, false, json).await, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const SHA_A: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; + + fn spec(version: &str, target: &str, sha256: &str) -> BundleSpec { + BundleSpec { + postgres_version: version.to_string(), + postgres_major: version.split('.').next().unwrap().to_string(), + extensions: BTreeMap::from([("pg_clickhouse".to_string(), "0.11.1".to_string())]), + target: target.to_string(), + file: format!("pg-{version}-pgch-0.11.1-{target}.tar.gz"), + sha256: sha256.to_string(), + } + } + + fn manifest(schema: u64, bundles: &[BundleSpec]) -> Vec { + serde_json::to_vec(&serde_json::json!({ + "schema": schema, + "release": "v0.3.0", + "built_at": "2026-11-16T00:00:00Z", + "source": { "repo": "sdairs/pg-bundles", "commit": "abc" }, + "bundles": bundles, + })) + .unwrap() + } + + #[test] + fn every_supported_platform_maps_to_its_bundle_target() { + for (os, arch, target) in [ + (Os::MacOS, Arch::Aarch64, "aarch64-apple-darwin"), + (Os::MacOS, Arch::X86_64, "x86_64-apple-darwin"), + (Os::Linux, Arch::Aarch64, "aarch64-unknown-linux-musl"), + (Os::Linux, Arch::X86_64, "x86_64-unknown-linux-musl"), + ] { + assert_eq!(target_triple(Platform { os, arch }), target); + } + } + + #[test] + fn native_versions_are_a_supported_major_with_an_optional_numeric_minor() { + assert_eq!( + PgVersionRequest::parse("18"), + Some(PgVersionRequest::major("18")) + ); + let pinned = PgVersionRequest::parse("17.11").unwrap(); + assert_eq!(pinned.major, "17"); + assert_eq!(pinned.exact.as_deref(), Some("17.11")); + for tag in ["16", "19", "18-bookworm", "18.1-alpine", "18.", "18.x", ""] { + assert_eq!(PgVersionRequest::parse(tag), None, "{tag}"); + } + } + + #[test] + fn manifest_parsing_reads_extra_fields_and_rejects_an_unknown_schema() { + let bundles = [spec("18.7", "aarch64-apple-darwin", SHA_A)]; + let mut value: serde_json::Value = serde_json::from_slice(&manifest(1, &bundles)).unwrap(); + value["bundles"][0]["size"] = 11370169.into(); + value["bundles"][0]["future_field"] = true.into(); + assert_eq!( + parse_manifest(&serde_json::to_vec(&value).unwrap()).unwrap(), + bundles + ); + + for bytes in [manifest(2, &bundles), b"{}".to_vec(), b"not json".to_vec()] { + assert!(matches!( + parse_manifest(&bytes), + Err(Error::PostgresBundleUnavailable(_)) + )); + } + } + + #[test] + fn selection_takes_the_newest_minor_for_the_target_and_honours_a_pin() { + let bundles = [ + spec("18.6", "aarch64-apple-darwin", SHA_A), + spec("18.10", "aarch64-apple-darwin", SHA_A), + spec("18.11", "x86_64-apple-darwin", SHA_A), + spec("17.11", "aarch64-apple-darwin", SHA_A), + ]; + let select = |tag: &str| { + select_newest( + &bundles, + "aarch64-apple-darwin", + &PgVersionRequest::parse(tag).unwrap(), + ) + .map(|spec| spec.postgres_version.as_str()) + }; + // Numeric, not lexical: 18.10 is newer than 18.6. + assert_eq!(select("18"), Some("18.10")); + assert_eq!(select("18.6"), Some("18.6")); + assert_eq!(select("17"), Some("17.11")); + assert_eq!(select("18.7"), None); + assert_eq!( + select_newest( + &bundles, + "aarch64-unknown-linux-musl", + &PgVersionRequest::major("18") + ), + None + ); + } + + #[test] + fn cache_key_is_the_bundle_name_and_a_sha256_prefix() { + let first = spec("18.7", "aarch64-apple-darwin", SHA_A); + let rebuilt = BundleSpec { + sha256: SHA_A.replace('a', "b"), + ..first.clone() + }; + assert_eq!( + first.cache_key(), + "pg-18.7-pgch-0.11.1-aarch64-apple-darwin-aaaaaaaaaaaa" + ); + assert_ne!(first.cache_key(), rebuilt.cache_key()); + } + + #[test] + fn manifest_entries_need_a_plain_archive_name_and_a_full_sha256() { + let valid = spec("18.7", "aarch64-apple-darwin", SHA_A); + assert_eq!(valid.validate(), Ok(())); + for file in [ + "../evil.tar.gz", + "dir/pg.tar.gz", + ".hidden.tar.gz", + "pg.zip", + ".tar.gz", + "https://example.com/pg.tar.gz", + ] { + let spec = BundleSpec { + file: file.to_string(), + ..valid.clone() + }; + assert!(spec.validate().is_err(), "{file}"); + } + for sha256 in ["", "abc", &SHA_A.replace('a', "g"), &format!("{SHA_A}a")] { + let spec = BundleSpec { + sha256: sha256.to_string(), + ..valid.clone() + }; + assert!(spec.validate().is_err(), "{sha256}"); + } + } + + #[test] + fn checksum_verification_compares_the_file_with_the_manifest() { + let dir = tempfile::tempdir().unwrap(); + let archive = dir.path().join("bundle.tar.gz"); + std::fs::write(&archive, b"abc").unwrap(); + // sha256("abc") + let digest = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"; + let matching = spec("18.7", "aarch64-apple-darwin", &digest.to_uppercase()); + verify_sha256(&archive, &matching).unwrap(); + + let mismatch = spec("18.7", "aarch64-apple-darwin", SHA_A); + match verify_sha256(&archive, &mismatch) { + Err(Error::PostgresBundleChecksum { + expected, actual, .. + }) => { + assert_eq!(expected, SHA_A); + assert_eq!(actual, digest); + } + other => panic!("expected a checksum error, got {other:?}"), + } + } + + #[test] + fn bundle_source_accepts_https_and_file_urls_only() { + assert_eq!( + BundleSource::parse(None).unwrap(), + BundleSource::Https(url::Url::parse(&format!("{DEFAULT_BUNDLES_URL}/")).unwrap()) + ); + let BundleSource::Https(base) = + BundleSource::parse(Some("https://example.com/bundles/v1")).unwrap() + else { + panic!("expected an https source"); + }; + assert_eq!( + base.join(MANIFEST_FILE).unwrap().as_str(), + "https://example.com/bundles/v1/manifest.json" + ); + assert_eq!( + BundleSource::parse(Some("file:///tmp/bundles")).unwrap(), + BundleSource::Directory(PathBuf::from("/tmp/bundles/")) + ); + for url in ["http://example.com", "ftp://example.com", "/tmp/bundles"] { + assert!( + matches!( + BundleSource::parse(Some(url)), + Err(Error::PostgresBundleUnavailable(_)) + ), + "{url}" + ); + } + } + + #[test] + fn only_complete_cache_entries_count_as_installed() { + let root = tempfile::tempdir().unwrap(); + let old = spec("18.6", "aarch64-apple-darwin", SHA_A); + let new = spec("18.7", "aarch64-apple-darwin", SHA_A); + for spec in [&old, &new] { + let dir = root.path().join(spec.cache_key()); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join(MARKER_FILE), serde_json::to_vec(spec).unwrap()).unwrap(); + } + // An interrupted extraction and a staging directory have no marker + // where a bundle keeps it. + std::fs::create_dir_all(root.path().join("pg-18.9-partial")).unwrap(); + let staging = root.path().join(".staging-1"); + std::fs::create_dir_all(&staging).unwrap(); + std::fs::write( + staging.join(MARKER_FILE), + serde_json::to_vec(&spec("18.9", "aarch64-apple-darwin", SHA_A)).unwrap(), + ) + .unwrap(); + + let newest = newest_installed_in( + root.path(), + "aarch64-apple-darwin", + &PgVersionRequest::major("18"), + ) + .unwrap(); + assert_eq!(newest.spec, new); + assert_eq!(newest.dir, root.path().join(new.cache_key())); + assert_eq!( + newest_installed_in( + root.path(), + "aarch64-apple-darwin", + &PgVersionRequest::major("17") + ), + None + ); + } +} diff --git a/crates/clickhousectl/src/local/pg_native.rs b/crates/clickhousectl/src/local/pg_native.rs new file mode 100644 index 000000000..9bd6f1213 --- /dev/null +++ b/crates/clickhousectl/src/local/pg_native.rs @@ -0,0 +1,498 @@ +//! The native runtime for `local postgres`: a postmaster from a cached +//! bundle (`local::pg_bundle`), run as a child process. +//! +//! Everything an instance owns lives in its directory under +//! `.clickhouse/servers/-pg/`: `data/` (PGDATA), `postgres.log`, +//! `run/` (the Unix socket) and `native.json` (credentials and the bundle +//! last used). This module owns those files and the processes; choosing an +//! instance and recording it in the project metadata is `local::postgres`. + +use crate::error::{Error, Result, StartupKind}; +use crate::local::pg_bundle::InstalledBundle; +use crate::local::server; +use serde::{Deserialize, Serialize}; +use std::io::{Read, Seek, SeekFrom, Write}; +use std::os::unix::fs::OpenOptionsExt; +use std::os::unix::process::CommandExt; +use std::path::{Path, PathBuf}; +use std::process::{Child, ExitStatus, Stdio}; +use std::time::{Duration, Instant}; + +const STATE_FILE: &str = "native.json"; +const LOG_FILE: &str = "postgres.log"; +const SOCKET_DIR: &str = "run"; +const LISTEN_ADDRESS: &str = "127.0.0.1"; + +const READINESS_POLL_INTERVAL: Duration = Duration::from_millis(200); +/// Bounds one `pg_isready` run, which is told to give up after a second. +const PROBE_TIMEOUT: Duration = Duration::from_secs(5); +/// How long a fast shutdown (SIGINT) is given before an immediate one. +const FAST_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(30); +/// How long an immediate shutdown (SIGQUIT) is given. +const IMMEDIATE_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5); +const LOG_TAIL_LINES: usize = 50; +const LOG_TAIL_BYTES: u64 = 16 * 1024; + +/// The bundle an instance last ran, by identity rather than by path: the +/// cache may be cleared or gain a newer minor between starts. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub(crate) struct BundleIdentity { + pub name: String, + pub sha256: String, + pub postgres_version: String, +} + +impl BundleIdentity { + pub(crate) fn of(bundle: &InstalledBundle) -> Self { + Self { + name: bundle.spec.name().to_string(), + sha256: bundle.spec.sha256.clone(), + postgres_version: bundle.spec.postgres_version.clone(), + } + } +} + +/// What a native instance needs beyond the project metadata. Stored with +/// owner-only permissions because it holds the superuser password. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub(crate) struct NativeState { + pub postgres_major: String, + pub bundle: BundleIdentity, + pub user: String, + pub password: String, + pub database: String, +} + +pub(crate) fn load_state(instance_dir: &Path) -> Result> { + match std::fs::read(instance_dir.join(STATE_FILE)) { + Ok(bytes) => Ok(Some(serde_json::from_slice(&bytes)?)), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None), + Err(error) => Err(error.into()), + } +} + +pub(crate) fn save_state(instance_dir: &Path, state: &NativeState) -> Result<()> { + let path = instance_dir.join(STATE_FILE); + let staged = instance_dir.join(format!(".{STATE_FILE}.{}", std::process::id())); + let _ = std::fs::remove_file(&staged); + let write = || -> std::io::Result<()> { + let mut file = std::fs::OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .open(&staged)?; + file.write_all(&serde_json::to_vec_pretty(state)?)?; + file.sync_all()?; + std::fs::rename(&staged, &path) + }; + write().map_err(|error| { + let _ = std::fs::remove_file(&staged); + error.into() + }) +} + +/// Postgres refuses to run as root, and a bundle downloaded as root would be +/// unusable by the user afterwards, so this fails before any download. +/// Dropping privileges instead is being looked at in issue #1464. +pub(crate) fn reject_root() -> Result<()> { + // SAFETY: `geteuid` takes no arguments and cannot fail. + reject_root_euid(unsafe { libc::geteuid() }) +} + +fn reject_root_euid(euid: u32) -> Result<()> { + if euid != 0 { + return Ok(()); + } + Err(Error::usage( + clap::error::ErrorKind::InvalidValue, + "PostgreSQL cannot run as root. Run `clickhousectl local postgres start` as a \ + regular user, or pass `--docker` to run Postgres in a container.", + )) +} + +fn data_dir(instance_dir: &Path) -> PathBuf { + instance_dir.join("data") +} + +/// Whether `instance_dir` holds an initialized data directory. +pub(crate) fn is_initialized(instance_dir: &Path) -> bool { + data_dir(instance_dir).join("PG_VERSION").is_file() +} + +/// The running postmaster of an instance, if any. +/// +/// `postmaster.pid` survives a crash and its PID can be reused, so the PID +/// counts only while that process still runs from the data directory, which +/// a postmaster makes its working directory. +pub(crate) fn running_pid(instance_dir: &Path) -> Option { + let data = data_dir(instance_dir); + let pid_file = std::fs::read_to_string(data.join("postmaster.pid")).ok()?; + let pid: u32 = pid_file.lines().next()?.trim().parse().ok()?; + server::is_server_process(pid, &data).then_some(pid) +} + +pub(crate) fn is_running(instance_dir: &Path) -> bool { + running_pid(instance_dir).is_some() +} + +/// Ask a postmaster to shut down: fast (SIGINT, which ends sessions and +/// checkpoints), then immediate (SIGQUIT) if that takes too long. `wait` +/// reports whether the process went within the given time. +fn shutdown(pid: u32, mut wait: impl FnMut(Duration) -> bool) -> Result<()> { + server::send_signal(pid, libc::SIGINT)?; + let fast = + crate::timing::duration_override(crate::timing::TERM_TIMEOUT_ENV, FAST_SHUTDOWN_TIMEOUT); + if wait(fast) { + return Ok(()); + } + server::send_signal(pid, libc::SIGQUIT)?; + if wait(IMMEDIATE_SHUTDOWN_TIMEOUT) { + return Ok(()); + } + Err(Error::Postgres(format!( + "postmaster (PID {pid}) did not exit after SIGINT and SIGQUIT" + ))) +} + +/// Stop the instance's postmaster, if it is running. +pub(crate) fn stop(instance_dir: &Path) -> Result<()> { + match running_pid(instance_dir) { + Some(pid) => shutdown(pid, |timeout| server::wait_for_exit(pid, timeout)), + None => Ok(()), + } +} + +/// Stop a postmaster this process spawned. Unlike [`stop`] it reaps the +/// child, which a liveness probe would otherwise keep seeing as a zombie. +pub(crate) fn stop_child(child: &mut Child) -> Result<()> { + let pid = child.id(); + let mut wait = |timeout: Duration| { + let deadline = Instant::now() + timeout; + loop { + if matches!(child.try_wait(), Ok(Some(_))) { + return true; + } + if Instant::now() >= deadline { + return false; + } + std::thread::sleep(Duration::from_millis(10)); + } + }; + if wait(Duration::ZERO) { + return Ok(()); + } + shutdown(pid, wait) +} + +/// The directory for the Unix socket, or `None` when its path would not fit +/// in a socket address (104 bytes on macOS, 108 on Linux). Postgres refuses +/// to start with a longer one, and TCP on loopback is all clients here use. +fn socket_dir(instance_dir: &Path) -> Option { + // SAFETY: `sockaddr_un` is plain data; all-zero is a valid value. + let capacity = unsafe { std::mem::zeroed::() } + .sun_path + .len(); + let dir = instance_dir.join(SOCKET_DIR); + socket_path_fits(&dir, capacity).then_some(dir) +} + +fn socket_path_fits(dir: &Path, capacity: usize) -> bool { + // "/.s.PGSQL." plus its terminating NUL, for any port. + dir.as_os_str().len() + "/.s.PGSQL.65535".len() < capacity +} + +/// The last lines of the instance's log, for a startup failure. +fn log_tail(instance_dir: &Path) -> String { + let path = instance_dir.join(LOG_FILE); + let read = || -> std::io::Result { + let mut file = std::fs::File::open(&path)?; + let len = file.metadata()?.len(); + file.seek(SeekFrom::Start(len.saturating_sub(LOG_TAIL_BYTES)))?; + let mut bytes = Vec::new(); + file.read_to_end(&mut bytes)?; + Ok(String::from_utf8_lossy(&bytes).into_owned()) + }; + let text = read().unwrap_or_default(); + let lines: Vec<&str> = text.lines().collect(); + let tail = lines[lines.len().saturating_sub(LOG_TAIL_LINES)..].join("\n"); + if tail.trim().is_empty() { + format!("(no output in {})", path.display()) + } else { + format!("--- last lines of {} ---\n{tail}", path.display()) + } +} + +/// What a fresh instance is created with. +pub(crate) struct InitOptions<'a> { + pub bundle: &'a InstalledBundle, + pub instance_dir: &'a Path, + /// The user-facing instance name, for error messages. + pub name: &'a str, + pub user: &'a str, + pub password: &'a str, +} + +/// Initialize the data directory. The password reaches `initdb` through a +/// file only this user can read, never through argv or the environment. +/// +/// The locale is the builtin `C.UTF-8` provider with `C` for the libc +/// categories, so sorting and case mapping do not depend on the platform's +/// locale database or on this process's environment. +pub(crate) async fn initdb(options: &InitOptions<'_>) -> Result<()> { + let mut pwfile = tempfile::Builder::new() + .prefix(".pwfile") + .tempfile_in(options.instance_dir)?; + writeln!(pwfile, "{}", options.password)?; + pwfile.flush()?; + + let mut pwfile_arg = std::ffi::OsString::from("--pwfile="); + pwfile_arg.push(pwfile.path()); + let output = tokio::process::Command::new(options.bundle.bin("initdb")) + .arg("-D") + .arg(data_dir(options.instance_dir)) + .arg("-U") + .arg(options.user) + .arg(pwfile_arg) + .args([ + "--auth=scram-sha-256", + "-E", + "UTF8", + "--locale-provider=builtin", + "--builtin-locale=C.UTF-8", + "--no-locale", + "--no-instructions", + ]) + .stdin(Stdio::null()) + .output() + .await + .map_err(|error| Error::Postgres(format!("could not run initdb: {error}")))?; + if output.status.success() { + return Ok(()); + } + Err(Error::StartupExit { + kind: StartupKind::Postgres, + name: options.name.to_string(), + details: format!( + "initdb failed for Postgres server '{}' ({}).\n{}", + options.name, + output.status, + String::from_utf8_lossy(&output.stderr).trim_end() + ), + }) +} + +/// Start the postmaster for an initialized instance, listening on loopback +/// only. It gets its own process group, so a Ctrl-C aimed at this CLI (or a +/// later one) does not reach it, and it outlives this process. +pub(crate) fn spawn_postmaster( + bundle: &InstalledBundle, + instance_dir: &Path, + port: u16, +) -> Result { + let log = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(instance_dir.join(LOG_FILE))?; + let socket_dir = socket_dir(instance_dir); + if let Some(dir) = &socket_dir { + std::fs::create_dir_all(dir)?; + } + let mut socket_setting = std::ffi::OsString::from("unix_socket_directories="); + if let Some(dir) = &socket_dir { + socket_setting.push(dir); + } + std::process::Command::new(bundle.bin("postgres")) + .arg("-D") + .arg(data_dir(instance_dir)) + .arg("-p") + .arg(port.to_string()) + .arg("-c") + .arg(format!("listen_addresses={LISTEN_ADDRESS}")) + .arg("-c") + .arg(socket_setting) + .stdin(Stdio::null()) + .stdout(log.try_clone()?) + .stderr(log) + .process_group(0) + .spawn() + .map_err(|error| Error::Postgres(format!("could not start postgres: {error}"))) +} + +enum Readiness { + Ready, + Exited(ExitStatus), + TimedOut, +} + +async fn poll_ready( + child: &mut Child, + bundle: &InstalledBundle, + port: u16, + timeout: Duration, +) -> Result { + let deadline = Instant::now() + timeout; + loop { + if let Some(status) = child.try_wait()? { + return Ok(Readiness::Exited(status)); + } + let probe = tokio::process::Command::new(bundle.bin("pg_isready")) + .args(["-h", LISTEN_ADDRESS, "-p", &port.to_string(), "-t", "1"]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .kill_on_drop(true) + .status(); + if let Ok(Ok(status)) = tokio::time::timeout(PROBE_TIMEOUT, probe).await + && status.success() + { + // Something answered on the port; it is this postmaster only if + // this postmaster is still running. + return Ok(match child.try_wait()? { + Some(status) => Readiness::Exited(status), + None => Readiness::Ready, + }); + } + if Instant::now() >= deadline { + return Ok(Readiness::TimedOut); + } + tokio::time::sleep(READINESS_POLL_INTERVAL).await; + } +} + +/// Wait until the postmaster accepts connections. The caller stops `child` +/// on an error. +pub(crate) async fn wait_ready( + child: &mut Child, + bundle: &InstalledBundle, + instance_dir: &Path, + name: &str, + port: u16, + timeout: Duration, +) -> Result<()> { + match poll_ready(child, bundle, port, timeout).await? { + Readiness::Ready => Ok(()), + Readiness::Exited(status) => Err(Error::StartupExit { + kind: StartupKind::Postgres, + name: name.to_string(), + details: format!( + "Postgres server '{name}' exited before PostgreSQL became ready ({status}).\n{}", + log_tail(instance_dir) + ), + }), + Readiness::TimedOut => Err(Error::StartupTimeout { + kind: StartupKind::Postgres, + name: name.to_string(), + seconds: timeout.as_secs(), + details: format!( + "PostgreSQL in server '{name}' did not become ready within {} seconds.\n{}", + timeout.as_secs(), + log_tail(instance_dir) + ), + }), + } +} + +/// Create `database` on a ready instance. The password goes to this +/// short-lived client through its environment, as `psql` takes it. +pub(crate) async fn create_database( + bundle: &InstalledBundle, + port: u16, + user: &str, + password: &str, + database: &str, +) -> Result<()> { + let output = tokio::process::Command::new(bundle.bin("createdb")) + .args(["-h", LISTEN_ADDRESS, "-p", &port.to_string(), "-U", user]) + .arg("--no-password") + .arg("--") + .arg(database) + .env("PGPASSWORD", password) + .stdin(Stdio::null()) + .output() + .await + .map_err(|error| Error::Postgres(format!("could not run createdb: {error}")))?; + if output.status.success() { + return Ok(()); + } + Err(Error::Postgres(format!( + "could not create database '{database}': {}", + String::from_utf8_lossy(&output.stderr).trim_end() + ))) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::os::unix::fs::PermissionsExt; + + #[test] + fn root_is_refused_as_a_usage_error_and_other_users_pass() { + assert!(reject_root_euid(501).is_ok()); + let error = reject_root_euid(0).unwrap_err(); + assert!(matches!(error, Error::Usage(_))); + assert_eq!(error.exit_code(), 2); + // The way out is the Docker runtime. + assert!(error.to_string().contains("--docker")); + } + + #[test] + fn state_round_trips_through_an_owner_only_file() { + let dir = tempfile::tempdir().unwrap(); + assert_eq!(load_state(dir.path()).unwrap(), None); + let state = NativeState { + postgres_major: "18".into(), + bundle: BundleIdentity { + name: "pg-18.7-pgch-0.11.1-aarch64-apple-darwin".into(), + sha256: "ab".repeat(32), + postgres_version: "18.7".into(), + }, + user: "postgres".into(), + password: "example-password".into(), + database: "app".into(), + }; + save_state(dir.path(), &state).unwrap(); + // Saving again replaces the file rather than failing on it. + save_state(dir.path(), &state).unwrap(); + + assert_eq!(load_state(dir.path()).unwrap(), Some(state)); + let mode = std::fs::metadata(dir.path().join(STATE_FILE)) + .unwrap() + .permissions() + .mode(); + assert_eq!(mode & 0o777, 0o600); + // No path to a bundle is stored: the cache may move or be cleared. + let stored = std::fs::read_to_string(dir.path().join(STATE_FILE)).unwrap(); + assert!(!stored.contains('/'), "{stored}"); + } + + #[test] + fn a_socket_directory_is_used_only_when_its_path_fits_the_address() { + let short = Path::new("/p/.clickhouse/servers/default-pg18/run"); + assert!(socket_path_fits(short, 104)); + let long = PathBuf::from(format!("/{}/run", "d".repeat(100))); + assert!(!socket_path_fits(&long, 104)); + // The boundary: path + "/.s.PGSQL.65535" + NUL must fit exactly. + let exact = PathBuf::from(format!("/{}", "d".repeat(104 - 15 - 2))); + assert!(socket_path_fits(&exact, 104)); + let over = PathBuf::from(format!("/{}", "d".repeat(104 - 15 - 1))); + assert!(!socket_path_fits(&over, 104)); + } + + #[test] + fn a_stale_pid_file_does_not_make_an_instance_running() { + let dir = tempfile::tempdir().unwrap(); + let data = dir.path().join("data"); + std::fs::create_dir_all(&data).unwrap(); + assert!(!is_running(dir.path())); + // This test process is alive, but it does not run from the data + // directory, as a process that reused a postmaster's PID would not. + std::fs::write( + data.join("postmaster.pid"), + format!("{}\n{}\n", std::process::id(), data.display()), + ) + .unwrap(); + assert!(!is_running(dir.path())); + std::fs::write(data.join("postmaster.pid"), "not a pid\n").unwrap(); + assert!(!is_running(dir.path())); + } +} diff --git a/crates/clickhousectl/src/local/postgres.rs b/crates/clickhousectl/src/local/postgres.rs index 45c81e8db..6ea21ea7e 100644 --- a/crates/clickhousectl/src/local/postgres.rs +++ b/crates/clickhousectl/src/local/postgres.rs @@ -1,27 +1,33 @@ //! Handlers for `clickhousectl local postgres ...` subcommands. //! -//! All Docker work goes through `local::docker`. State is reused from -//! `local::server` — Postgres entries land in the same metadata directory and -//! show up alongside ClickHouse in `local status`. +//! An instance runs in one of two runtimes ([`PgRuntime`]) and keeps the one +//! it was created with: native, a postmaster from a downloaded bundle +//! (`local::pg_bundle`, `local::pg_native`), or Docker (`local::docker`). +//! `start` chooses for a new instance in [`select_start_runtime`]; every other +//! command reads the choice back with `ServerInfo::pg_runtime`. State is +//! reused from `local::server` — Postgres entries land in the same metadata +//! directory and show up alongside ClickHouse in `local status`. use crate::error::{Error, PortKind, Result, StartupKind}; use crate::local::cli::PostgresCommands; use crate::local::docker::{self, PostgresRunOpts}; use crate::local::output; -use crate::local::server::{self, Engine, ServerInfo}; +use crate::local::pg_bundle::{self, InstalledBundle, PgVersionRequest}; +use crate::local::pg_native::{self, BundleIdentity, NativeState}; +use crate::local::server::{self, Engine, PgRuntime, ServerInfo}; use rand::distr::{Alphanumeric, SampleString}; use std::collections::HashSet; use std::future::Future; use std::io::IsTerminal; use std::path::Path; -use std::process::Command; +use std::process::{Child, Command}; use std::time::Duration; const DEFAULT_PG_PORT: u16 = 5432; const DEFAULT_USER: &str = "postgres"; const DEFAULT_DATABASE: &str = "postgres"; -/// Default image tag when `--version` is not given. Within the supported -/// range; users can override with any 17/18 tag (`17`, `17.0`, `18-bookworm`, etc). +/// Default version when `--version` is not given: a major both runtimes +/// serve. Docker also takes any 17/18 image tag (`17.0`, `18-bookworm`, etc). pub const DEFAULT_PG_TAG: &str = "18"; const READINESS_POLL_INTERVAL: Duration = Duration::from_millis(200); const READINESS_LOG_LINES: usize = 50; @@ -181,17 +187,21 @@ pub async fn run(cmd: PostgresCommands, json: bool) -> Result<()> { password, database, env, + docker, wait_timeout, } => { start( - name.or(name_flag), - version, - port, - user, - password, - database, - env, - Duration::from_secs(wait_timeout.into()), + StartArgs { + name: name.or(name_flag), + version, + port, + user, + password, + database, + extra_env: env, + docker, + wait_timeout: Duration::from_secs(wait_timeout.into()), + }, json, ) .await @@ -247,8 +257,7 @@ pub async fn run(cmd: PostgresCommands, json: bool) -> Result<()> { } } -#[allow(clippy::too_many_arguments)] -async fn start( +struct StartArgs { name: Option, version: Option, port: Option, @@ -256,9 +265,110 @@ async fn start( password: Option, database: Option, extra_env: Vec, + docker: bool, wait_timeout: Duration, - json: bool, -) -> Result<()> { +} + +/// What a start asks for that only the Docker runtime provides. +#[derive(Debug, Clone, PartialEq, Eq)] +enum DockerOnlyFeature { + /// `--env`: container environment variables. + Env, + /// A `--version` that is an image tag rather than `17`, `18` or + /// `.`. + ImageTag(String), +} + +impl DockerOnlyFeature { + fn of(version: Option<&str>, has_extra_env: bool) -> Option { + if has_extra_env { + return Some(Self::Env); + } + version + .filter(|tag| PgVersionRequest::parse(tag).is_none()) + .map(|tag| Self::ImageTag(tag.to_string())) + } + + fn describe(&self) -> String { + match self { + Self::Env => "`--env` sets container environment variables".to_string(), + Self::ImageTag(tag) => format!( + "`--version {tag}` is a Docker image tag (the native runtime takes 17, 18 or \ + .)" + ), + } + } +} + +/// The one decision between runtimes for `start`. +/// +/// An existing instance keeps the runtime it was created with, so a Docker +/// instance from before the native runtime existed resumes without the flag. +/// A new instance is native unless `--docker` is given. Asking for the other +/// runtime, or for a Docker-only feature without it, is a usage error that +/// names the fix. +fn select_start_runtime( + prior: Option, + docker: bool, + docker_only: Option<&DockerOnlyFeature>, + name: &str, + major: &str, +) -> Result { + use clap::error::ErrorKind; + let recreate = format!( + "remove it first with `clickhousectl local postgres remove {name} --version {major}` \ + (this deletes its data) to recreate it with `--docker`" + ); + match (prior, docker, docker_only) { + (Some(PgRuntime::Docker), _, _) | (None, true, _) => Ok(PgRuntime::Docker), + (Some(PgRuntime::Native), true, _) => Err(Error::usage( + ErrorKind::ArgumentConflict, + format!( + "Postgres instance '{name}' (major {major}) runs natively, and `--docker` cannot \ + change an existing instance. Start it without `--docker`, or {recreate}" + ), + )), + (Some(PgRuntime::Native), false, Some(feature)) => Err(Error::usage( + ErrorKind::ArgumentConflict, + format!( + "{}, which needs the Docker runtime, and Postgres instance '{name}' (major \ + {major}) runs natively. Drop the option, or {recreate}", + feature.describe() + ), + )), + (None, false, Some(feature)) => Err(Error::usage( + ErrorKind::ArgumentConflict, + format!( + "{}, which needs the Docker runtime; add `--docker`", + feature.describe() + ), + )), + (Some(PgRuntime::Native) | None, false, None) => Ok(PgRuntime::Native), + } +} + +/// The error for an instance whose runtime changed between choosing a +/// runtime and acting on it: another command removed and recreated it. +fn runtime_changed(name: &str) -> Error { + Error::PostgresUsage(format!( + "Postgres instance '{name}' was changed by another command while this one was starting \ + it; run the command again" + )) +} + +async fn start(args: StartArgs, json: bool) -> Result<()> { + let StartArgs { + name, + version, + port, + user, + password, + database, + extra_env, + docker, + wait_timeout, + } = args; + let docker_only = DockerOnlyFeature::of(version.as_deref(), !extra_env.is_empty()); let has_extra_env = !extra_env.is_empty(); let preflight = validate_start_options( name.as_deref(), @@ -267,6 +377,85 @@ async fn start( password.as_deref(), extra_env, )?; + + // Look at what exists under the project lock, then release it: both + // runtimes resolve their target again before changing anything. + let (user_name, major, prior) = { + let metadata_lock = server::lock_metadata()?; + server::recover_current_project_servers_locked(&metadata_lock)?; + let user_name = match name { + Some(name) => name, + None => default_pg_name_locked(&metadata_lock)?, + }; + let (_, major) = + resolve_pg_start_version_locked(&user_name, version.as_deref(), &metadata_lock)?; + let key = server::pg_instance_key(&user_name, &major); + let prior = server::load_info_locked(&key, &metadata_lock)?; + (user_name, major, prior) + }; + let prior_runtime = prior.as_ref().and_then(ServerInfo::pg_runtime); + let runtime = select_start_runtime( + prior_runtime, + docker, + docker_only.as_ref(), + &user_name, + &major, + )?; + + let request = StartRequest { + name: user_name, + version, + port, + user, + password, + database, + preflight, + has_extra_env, + wait_timeout, + }; + match runtime { + PgRuntime::Docker => { + if !docker && !json { + eprintln!( + "Note: postgres '{}' (major {major}) is a Docker instance; resuming it in \ + Docker.", + request.name + ); + } + start_docker(request, json).await + } + PgRuntime::Native => start_native(request, json).await, + } +} + +/// A validated start, for the runtime [`select_start_runtime`] chose. +struct StartRequest { + /// The instance name, already defaulted. + name: String, + version: Option, + /// The port the user asked for, if any; `preflight.host_port` is the + /// same port once checked. + port: Option, + user: Option, + password: Option, + database: Option, + preflight: StartPreflight, + has_extra_env: bool, + wait_timeout: Duration, +} + +async fn start_docker(request: StartRequest, json: bool) -> Result<()> { + let StartRequest { + name: user_name, + version, + port, + user, + password, + database, + preflight, + has_extra_env, + wait_timeout, + } = request; let host_port = preflight.host_port; let extra_env = preflight.extra_env; let password_from_env = preflight.password_from_env; @@ -279,15 +468,17 @@ async fn start( // before potentially slow fresh-image inspection and pulling. let metadata_lock = server::lock_metadata()?; server::recover_current_project_servers_locked(&metadata_lock)?; - let user_name = match name.as_deref() { - Some(name) => name.to_string(), - None => default_pg_name_locked(&metadata_lock)?, - }; let (tag, major) = resolve_pg_start_version_locked(&user_name, version.as_deref(), &metadata_lock)?; let key = server::pg_instance_key(&user_name, &major); let prior = server::load_info_locked(&key, &metadata_lock)?; drop(metadata_lock); + if prior + .as_ref() + .is_some_and(|prior| prior.pg_runtime() != Some(PgRuntime::Docker)) + { + return Err(runtime_changed(&user_name)); + } if prior.is_none() { if !docker::image_exists(&docker, &tag).await? { @@ -427,8 +618,11 @@ async fn start( let out = output::PostgresStartOutput { name: user_name, - container_id, + runtime: output::PostgresRuntime::Docker, + container_id: Some(container_id), + pid: None, image: format!("postgres:{tag}"), + extensions: Default::default(), port: host_port, user, password, @@ -439,6 +633,379 @@ async fn start( } } +/// A password `initdb --pwfile` can carry: one non-empty line. +fn validate_native_password(password: &str) -> Result<()> { + if password.is_empty() || password.contains(['\n', '\r']) { + return Err(Error::usage( + clap::error::ErrorKind::InvalidValue, + "--password must be a single non-empty line", + )); + } + Ok(()) +} + +async fn start_native(request: StartRequest, json: bool) -> Result<()> { + let StartRequest { + name: user_name, + version, + port, + user, + password, + database, + preflight, + wait_timeout, + .. + } = request; + pg_native::reject_root()?; + if let Some(password) = &password { + validate_native_password(password)?; + } + let project_cwd = crate::init::project_root()?.dir.display().to_string(); + + loop { + // Resolve an optimistic target, then release the project-wide lock + // before a possible bundle download. + let metadata_lock = server::lock_metadata()?; + let (tag, major) = + resolve_pg_start_version_locked(&user_name, version.as_deref(), &metadata_lock)?; + let key = server::pg_instance_key(&user_name, &major); + let prior = server::load_info_locked(&key, &metadata_lock)?; + drop(metadata_lock); + if prior + .as_ref() + .is_some_and(|prior| prior.pg_runtime() != Some(PgRuntime::Native)) + { + return Err(runtime_changed(&user_name)); + } + + let bundle = match &prior { + // Data directories work across minors of a major, so an existing + // instance takes the newest installed bundle and needs no network. + Some(_) => pg_bundle::bundle_for_existing(&major, json).await?, + None => { + let request = PgVersionRequest::parse(&tag).ok_or_else(|| { + Error::PostgresUsage(format!( + "'{tag}' is not a version the native runtime serves; use 17, 18 or \ + ., or add `--docker`" + )) + })?; + pg_bundle::ensure_bundle(&request, false, json).await? + } + }; + + let metadata_lock = server::lock_metadata()?; + let (current_tag, current_major) = + resolve_pg_start_version_locked(&user_name, version.as_deref(), &metadata_lock)?; + let current_key = server::pg_instance_key(&user_name, ¤t_major); + let current = server::load_info_locked(¤t_key, &metadata_lock)?; + if current_tag != tag || current_key != key || current != prior { + drop(metadata_lock); + continue; + } + crate::init::ensure_runtime_gitignore()?; + + let started = match prior { + Some(prior) => { + if !json + && (port.is_some() + || user.is_some() + || password.is_some() + || database.is_some()) + { + eprintln!( + "Note: postgres '{user_name}' (major {major}) already exists; resuming \ + with stored settings. Run `local postgres remove {user_name}` to start \ + over." + ); + } + resume_native(prior, &bundle, wait_timeout, metadata_lock).await? + } + None => { + let host_port = match preflight.host_port { + Some(port) => port, + None => resolve_port(None)?, + }; + let state = NativeState { + postgres_major: major.clone(), + bundle: BundleIdentity::of(&bundle), + user: user.unwrap_or_else(|| DEFAULT_USER.to_string()), + password: password.unwrap_or_else(generate_password), + database: database.unwrap_or_else(|| DEFAULT_DATABASE.to_string()), + }; + let info = ServerInfo { + name: key, + pid: 0, + version: format!("postgres:{}", bundle.spec.postgres_version), + last_version: None, + http_port: 0, + tcp_port: host_port, + started_at: server::now_timestamp(), + cwd: project_cwd, + engine: Engine::Postgres, + container_id: None, + }; + create_native(info, state, &bundle, wait_timeout, metadata_lock).await? + } + }; + + let NativeStarted { info, state } = started; + let out = output::PostgresStartOutput { + name: user_name, + runtime: output::PostgresRuntime::Native, + container_id: None, + pid: Some(info.pid), + image: info.version, + extensions: bundle.spec.extensions.clone(), + port: info.tcp_port, + user: state.user, + password: state.password, + database: state.database, + }; + output::print_output(&out, json); + return Ok(()); + } +} + +/// A native instance that is running and ready. +struct NativeStarted { + info: ServerInfo, + state: NativeState, +} + +/// Initialize and start a new native instance. `info` describes it with no +/// PID yet. Any failure stops the postmaster and removes what this attempt +/// created, so a retry starts clean. +async fn create_native( + mut info: ServerInfo, + state: NativeState, + bundle: &InstalledBundle, + wait_timeout: Duration, + metadata_lock: server::MetadataLock, +) -> Result { + let instance_dir = metadata_lock.servers_dir().join(&info.name); + let display_name = user_name_from_key(&info.name).to_string(); + if !fresh_instance_dir_is_disposable(&instance_dir) { + // Data without metadata has no known credentials to resume with. + return Err(Error::PostgresUsage(format!( + "'{}' already holds files, but no Postgres instance is recorded for it. Move or \ + delete that directory, then start again.", + instance_dir.display() + ))); + } + std::fs::create_dir_all(instance_dir.join("data"))?; + + let spawned = async { + pg_native::initdb(&pg_native::InitOptions { + bundle, + instance_dir: &instance_dir, + name: &display_name, + user: &state.user, + password: &state.password, + }) + .await?; + pg_native::save_state(&instance_dir, &state)?; + pg_native::spawn_postmaster(bundle, &instance_dir, info.tcp_port) + } + .await; + let mut child = match spawned { + Ok(child) => child, + Err(primary) => { + return Err(rollback_native_create( + None, + &info.name, + primary, + &metadata_lock, + )); + } + }; + info.pid = child.id(); + if let Err(primary) = server::save_server_info_locked(&info, &metadata_lock) { + return Err(rollback_native_create( + Some(&mut child), + &info.name, + primary, + &metadata_lock, + )); + } + drop(metadata_lock); + + let ready = async { + pg_native::wait_ready( + &mut child, + bundle, + &instance_dir, + &display_name, + info.tcp_port, + wait_timeout, + ) + .await?; + if state.database != DEFAULT_DATABASE { + pg_native::create_database( + bundle, + info.tcp_port, + &state.user, + &state.password, + &state.database, + ) + .await?; + } + Ok(()) + } + .await; + if let Err(primary) = ready { + // Stop the postmaster before anything that can fail, such as taking + // the lock again. + let stopped = pg_native::stop_child(&mut child); + let metadata_lock = server::lock_metadata()?; + let primary = match stopped { + Ok(()) => primary, + Err(cleanup) => { + return Err(Error::PostgresStartupRollback { + primary: Box::new(primary), + cleanup: format!( + "could not stop the postmaster (PID {}): {cleanup}; its data and \ + metadata were kept, run `clickhousectl local postgres remove {}` to \ + clean up", + info.pid, display_name + ), + }); + } + }; + return Err(rollback_native_create( + None, + &info.name, + primary, + &metadata_lock, + )); + } + Ok(NativeStarted { info, state }) +} + +/// Undo a failed [`create_native`]: stop the postmaster if it was spawned, +/// then delete the instance directory and metadata this attempt created. +/// When the postmaster cannot be stopped, both are kept so `remove` can +/// finish the job. +fn rollback_native_create( + child: Option<&mut Child>, + key: &str, + primary: Error, + metadata_lock: &server::MetadataLock, +) -> Error { + let instance_dir = metadata_lock.servers_dir().join(key); + let cleanup = || -> std::result::Result<(), String> { + if let Some(child) = child { + pg_native::stop_child(child).map_err(|error| { + format!( + "could not stop the postmaster: {error}; run `clickhousectl local postgres \ + remove {}` to clean up", + user_name_from_key(key) + ) + })?; + } + match std::fs::remove_dir_all(&instance_dir) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => { + return Err(format!( + "failed to remove '{}': {error}", + instance_dir.display() + )); + } + } + server::try_remove_server_info_locked(key, metadata_lock) + .map_err(|error| format!("failed to remove metadata: {error}")) + }; + match cleanup() { + Ok(()) => primary, + Err(cleanup) => Error::PostgresStartupRollback { + primary: Box::new(primary), + cleanup, + }, + } +} + +/// Start an existing, stopped native instance on its stored port with its +/// stored credentials. A failure after the postmaster is spawned stops it +/// and leaves the instance recorded as stopped. +async fn resume_native( + prior: ServerInfo, + bundle: &InstalledBundle, + wait_timeout: Duration, + metadata_lock: server::MetadataLock, +) -> Result { + let instance_dir = metadata_lock.servers_dir().join(&prior.name); + let display_name = user_name_from_key(&prior.name).to_string(); + if pg_native::is_running(&instance_dir) { + return Err(Error::ServerAlreadyRunning(display_name)); + } + let state = pg_native::load_state(&instance_dir)? + .filter(|_| pg_native::is_initialized(&instance_dir)) + .ok_or_else(|| { + Error::PostgresUsage(format!( + "server '{display_name}' ({}) has metadata but its data directory is gone or \ + incomplete. Run `clickhousectl local postgres remove {display_name}` to clear \ + it and start fresh.", + prior.version + )) + })?; + ensure_resume_port_free(&display_name, prior.tcp_port)?; + + let mut child = pg_native::spawn_postmaster(bundle, &instance_dir, prior.tcp_port)?; + let stopped = ServerInfo { + pid: 0, + ..prior.clone() + }; + let info = ServerInfo { + pid: child.id(), + version: format!("postgres:{}", bundle.spec.postgres_version), + started_at: server::now_timestamp(), + ..prior + }; + let state = NativeState { + bundle: BundleIdentity::of(bundle), + ..state + }; + let recorded = server::save_server_info_locked(&info, &metadata_lock) + .and_then(|()| pg_native::save_state(&instance_dir, &state)); + let ready = match recorded { + Ok(()) => { + drop(metadata_lock); + pg_native::wait_ready( + &mut child, + bundle, + &instance_dir, + &display_name, + info.tcp_port, + wait_timeout, + ) + .await + } + Err(error) => { + drop(metadata_lock); + Err(error) + } + }; + if let Err(primary) = ready { + let stopped_child = pg_native::stop_child(&mut child); + // Best effort: liveness comes from the postmaster's own PID file, so + // a PID left behind here is display-only. + if let Ok(lock) = server::lock_metadata() { + let _ = server::save_server_info_locked(&stopped, &lock); + } + return Err(match stopped_child { + Ok(()) => primary, + Err(cleanup) => Error::PostgresStartupRollback { + primary: Box::new(primary), + cleanup: format!( + "could not stop the resumed postmaster (PID {}): {cleanup}", + info.pid + ), + }, + }); + } + Ok(NativeStarted { info, state }) +} + /// A fresh attempt owns an absent or empty instance directory, including one /// containing only an empty `data/` from an earlier pre-container step. fn fresh_instance_dir_is_disposable(path: &Path) -> bool { @@ -558,9 +1125,11 @@ fn default_pg_name_locked_with( is_container_running: impl Fn(&str) -> Result, ) -> Result { for info in server::find_pg_instances_locked("default", metadata_lock)? { - if let Some(id) = info.container_id.as_deref() - && is_container_running(id)? - { + let running = match info.container_id.as_deref() { + Some(id) => is_container_running(id)?, + None => pg_native::is_running(&metadata_lock.servers_dir().join(&info.name)), + }; + if running { return server::generate_random_name_locked(metadata_lock); } } @@ -764,8 +1333,11 @@ async fn resume_existing( let out = output::PostgresStartOutput { name: display_name, - container_id, + runtime: output::PostgresRuntime::Docker, + container_id: Some(container_id), + pid: None, image: info.version, + extensions: Default::default(), port: info.tcp_port, user, password, @@ -1186,6 +1758,25 @@ fn remove(name: &str, version: Option<&str>, json: bool) -> Result<()> { server::validate_server_name(name)?; let (target, metadata_lock) = lock_and_resolve_pg_target(name, version)?; let key = target.name.clone(); + if target.pg_runtime() == Some(PgRuntime::Native) { + // Everything a native instance owns is in its directory, so stopping + // the postmaster and deleting the directory leaves nothing behind. + if server::is_server_running_locked(&key, &metadata_lock)? { + server::kill_server_locked(&key, &metadata_lock)?; + } + match std::fs::remove_dir_all(server::servers_dir_join(&key)?) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(error.into()), + } + server::try_remove_server_info_locked(&key, &metadata_lock)?; + let out = output::ServerRemoveOutput { + name: name.to_string(), + selection: None, + }; + output::print_output(&out, json); + return Ok(()); + } if server::is_server_running_locked(&key, &metadata_lock)? { let tag = target .version @@ -1243,7 +1834,8 @@ async fn client( } let h = host.unwrap_or_else(|| "127.0.0.1".to_string()); let p = port.unwrap_or(DEFAULT_PG_PORT); - return exec_host_psql( + return exec_psql( + Path::new("psql"), &h, p, DEFAULT_USER, @@ -1270,6 +1862,22 @@ async fn client( } drop(metadata_lock); + if info.pg_runtime() == Some(PgRuntime::Native) { + let state = native_state(&info)?; + let bundle = installed_bundle_for(&state)?; + return exec_psql( + &bundle.bin("psql"), + "127.0.0.1", + info.tcp_port, + &state.user, + Some(&state.password), + &state.database, + query, + queries_file, + extra_args, + ); + } + let docker = docker::connect().await?; let container_id = info .container_id @@ -1279,7 +1887,8 @@ async fn client( // Prefer host psql; fall back to docker exec. if host_has_psql() { - return exec_host_psql( + return exec_psql( + Path::new("psql"), "127.0.0.1", info.tcp_port, &user, @@ -1369,8 +1978,33 @@ fn host_has_psql() -> bool { .unwrap_or(false) } +/// The stored credentials of a native instance. +fn native_state(info: &ServerInfo) -> Result { + let name = user_name_from_key(&info.name); + pg_native::load_state(&server::servers_dir_join(&info.name)?)?.ok_or_else(|| { + Error::PostgresUsage(format!( + "server '{name}' ({}) has no stored connection details. Run `clickhousectl local \ + postgres remove {name}` to clear it and start fresh.", + info.version + )) + }) +} + +/// The installed bundle whose client tools match a native instance's major. +fn installed_bundle_for(state: &NativeState) -> Result { + let major = &state.postgres_major; + pg_bundle::newest_installed(&PgVersionRequest::major(major))?.ok_or_else(|| { + Error::PostgresBundleUnavailable(format!( + "no PostgreSQL {major} bundle is installed; run `clickhousectl local install \ + postgres@{major}`" + )) + }) +} + +/// Hand this process over to `program`, a `psql`: the host's, or a bundle's. #[allow(clippy::too_many_arguments)] -fn exec_host_psql( +fn exec_psql( + program: &Path, host: &str, port: u16, user: &str, @@ -1384,7 +2018,7 @@ fn exec_host_psql( // psql reads a non-terminal stdin as a script unless -c supplies input. let script_input = queries_file.is_some() || (query.is_none() && !std::io::stdin().is_terminal()); - let mut cmd = Command::new("psql"); + let mut cmd = Command::new(program); cmd.arg("-h") .arg(host) .arg("-p") @@ -1435,10 +2069,17 @@ fn dotenv(name: Option<&str>, version: Option<&str>, use_local: bool, json: bool } drop(metadata_lock); - // Read user/password/db from the container env so we always emit accurate creds. - let (user, password, database) = docker::block_on(read_pg_env_for_dotenv( - info.container_id.as_deref().unwrap_or_default(), - )); + let (user, password, database) = match info.pg_runtime() { + Some(PgRuntime::Native) => { + let state = native_state(&info)?; + (state.user, state.password, state.database) + } + // Read user/password/db from the container env so we always emit + // accurate creds. + _ => docker::block_on(read_pg_env_for_dotenv( + info.container_id.as_deref().unwrap_or_default(), + )), + }; let vars: Vec<(&str, String)> = vec![ ("POSTGRES_HOST", "127.0.0.1".to_string()), @@ -1517,6 +2158,106 @@ mod tests { } } + #[test] + fn docker_only_features_are_env_and_image_tags() { + for version in [None, Some("17"), Some("18"), Some("18.6")] { + assert_eq!(DockerOnlyFeature::of(version, false), None, "{version:?}"); + } + assert_eq!( + DockerOnlyFeature::of(Some("18-bookworm"), false), + Some(DockerOnlyFeature::ImageTag("18-bookworm".into())) + ); + assert_eq!( + DockerOnlyFeature::of(Some("17.2-alpine"), false), + Some(DockerOnlyFeature::ImageTag("17.2-alpine".into())) + ); + assert_eq!( + DockerOnlyFeature::of(Some("18"), true), + Some(DockerOnlyFeature::Env) + ); + } + + #[test] + fn start_runtime_is_native_unless_docker_is_asked_for_or_already_in_use() { + let select = |prior, docker, feature: Option| { + select_start_runtime(prior, docker, feature.as_ref(), "dev", "18") + }; + let env = || Some(DockerOnlyFeature::Env); + let tag = || Some(DockerOnlyFeature::ImageTag("18-bookworm".into())); + + // New instances. + assert_eq!(select(None, false, None).unwrap(), PgRuntime::Native); + assert_eq!(select(None, true, None).unwrap(), PgRuntime::Docker); + assert_eq!(select(None, true, env()).unwrap(), PgRuntime::Docker); + assert_eq!(select(None, true, tag()).unwrap(), PgRuntime::Docker); + // An instance keeps its runtime: Docker ones from older versions + // resume without the flag, with or without Docker-only options. + for docker in [false, true] { + for feature in [None, env(), tag()] { + assert_eq!( + select(Some(PgRuntime::Docker), docker, feature).unwrap(), + PgRuntime::Docker + ); + } + } + assert_eq!( + select(Some(PgRuntime::Native), false, None).unwrap(), + PgRuntime::Native + ); + + // Usage errors (exit 2) that name the flag and the instance. + for (prior, docker, feature) in [ + (None, false, env()), + (None, false, tag()), + (Some(PgRuntime::Native), true, None), + (Some(PgRuntime::Native), true, env()), + (Some(PgRuntime::Native), false, env()), + (Some(PgRuntime::Native), false, tag()), + ] { + let error = select(prior, docker, feature.clone()).unwrap_err(); + assert_eq!(error.exit_code(), 2, "{prior:?} {docker} {feature:?}"); + let message = error.to_string(); + assert!(message.contains("--docker"), "{message}"); + if prior.is_some() { + assert!( + message.contains("clickhousectl local postgres remove dev --version 18"), + "{message}" + ); + } + } + } + + #[test] + fn native_passwords_are_one_non_empty_line() { + assert!(validate_native_password("example-password").is_ok()); + for password in ["", "two\nlines", "carriage\rreturn"] { + let error = validate_native_password(password).unwrap_err(); + assert_eq!(error.exit_code(), 2, "{password:?}"); + } + } + + #[test] + fn runtime_follows_the_recorded_container() { + let mut info = ServerInfo { + name: server::pg_instance_key("dev", "18"), + pid: 0, + version: "postgres:18.7".into(), + last_version: None, + http_port: 0, + tcp_port: 5432, + started_at: "1700000000".into(), + cwd: "/tmp/project".into(), + engine: Engine::Postgres, + container_id: None, + }; + assert_eq!(info.pg_runtime(), Some(PgRuntime::Native)); + // What every Docker start has written, before and since. + info.container_id = Some("abc123".into()); + assert_eq!(info.pg_runtime(), Some(PgRuntime::Docker)); + info.engine = Engine::Clickhouse; + assert_eq!(info.pg_runtime(), None); + } + #[test] fn unnamed_start_after_running_default_selects_fresh_name() { let directory = tempfile::tempdir().unwrap(); diff --git a/crates/clickhousectl/src/local/server.rs b/crates/clickhousectl/src/local/server.rs index 13d2ac0c9..b30ca7379 100644 --- a/crates/clickhousectl/src/local/server.rs +++ b/crates/clickhousectl/src/local/server.rs @@ -29,7 +29,8 @@ const NOUNS: &[&str] = &[ ]; /// Engine driving a server instance. ClickHouse is a managed binary process; -/// Postgres is a managed Docker container. +/// Postgres is a managed postmaster process or Docker container +/// ([`PgRuntime`]). #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "lowercase")] pub enum Engine { @@ -54,6 +55,16 @@ impl Engine { } } +/// How a Postgres instance is run. An instance keeps the runtime it was +/// created with. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum PgRuntime { + /// A postmaster from a downloaded bundle, run as a child process. + Native, + /// A container from a `postgres` image. + Docker, +} + fn default_engine() -> Engine { Engine::Clickhouse } @@ -66,10 +77,12 @@ fn default_engine() -> Engine { #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct ServerInfo { pub name: String, - /// Active ClickHouse process PID; 0 when stopped or for Postgres. + /// Active ClickHouse process PID, or the postmaster's for native + /// Postgres; 0 when stopped or for Docker Postgres. pub pid: u32, /// Running ClickHouse version like "25.12.5.44", empty when stopped, or - /// "postgres:" for Postgres. + /// "postgres:" for Docker Postgres and "postgres:" for + /// native Postgres. pub version: String, /// ClickHouse version this server was last seen ready on, so a restart /// without `--version` keeps its data dir on that version (issue #1230). @@ -93,6 +106,19 @@ pub struct ServerInfo { } impl ServerInfo { + /// The runtime of a Postgres instance; `None` for ClickHouse. + /// + /// This is the one place that tells the runtimes apart: a Docker instance + /// always records its container, including ones created before the native + /// runtime existed, and a native instance never has one. + pub(crate) fn pg_runtime(&self) -> Option { + match (self.engine, &self.container_id) { + (Engine::Clickhouse, _) => None, + (Engine::Postgres, Some(_)) => Some(PgRuntime::Docker), + (Engine::Postgres, None) => Some(PgRuntime::Native), + } + } + /// The ClickHouse version this server's data dir is known to run on: the /// one it was last seen ready on. A version whose start has not been seen /// ready is ignored, including a dead start whose metadata was not yet @@ -534,7 +560,7 @@ fn is_alive(info: &ServerInfo, lock: &MetadataLock) -> Result { )), Engine::Postgres => match info.container_id.as_deref() { Some(id) => docker::is_container_running_blocking(id), - None => Ok(false), + None => Ok(super::pg_native::is_running(&lock.dir.join(&info.name))), }, } } @@ -878,7 +904,7 @@ pub(crate) fn is_server_running_locked(name: &str, lock: &MetadataLock) -> Resul /// A process whose working directory cannot be read, such as one owned by /// another user, is not treated as ours: it is never signalled, and the server /// is reported as not running. -fn is_server_process(pid: u32, data_dir: &Path) -> bool { +pub(crate) fn is_server_process(pid: u32, data_dir: &Path) -> bool { if !is_process_alive(pid) { return false; } @@ -897,7 +923,7 @@ fn is_process_alive(pid: u32) -> bool { /// Send a signal to a process and return an error if the signal could not be delivered /// (e.g. EPERM from a process owned by another user). -fn send_signal(pid: u32, signal: i32) -> Result<()> { +pub(crate) fn send_signal(pid: u32, signal: i32) -> Result<()> { // A PID beyond `i32` would wrap to a negative value, which `kill` reads as // a process group, or as every process for -1. let target = i32::try_from(pid).map_err(|_| { @@ -926,7 +952,7 @@ const TERM_TIMEOUT: Duration = Duration::from_millis(2500); const KILL_TIMEOUT: Duration = Duration::from_millis(500); /// Poll until `pid` is gone, returning whether it went within `timeout`. -fn wait_for_exit(pid: u32, timeout: Duration) -> bool { +pub(crate) fn wait_for_exit(pid: u32, timeout: Duration) -> bool { let deadline = std::time::Instant::now() + timeout; loop { if !is_process_alive(pid) { @@ -1019,9 +1045,10 @@ fn kill_escalated(pid: u32, supervised: std::io::Result>) -> Result<()> /// /// * ClickHouse: SIGTERM (then SIGKILL on timeout); metadata is retained with /// PID 0 so the stopped instance remains discoverable. -/// * Postgres: stops the container only — does **not** remove it, and keeps -/// the metadata file so a subsequent `start` resumes the same container -/// (preserving the password and any other PGDATA-encoded settings). +/// * Postgres: stops the postmaster or the container only — the data, the +/// container and the metadata file stay, so a subsequent `start` resumes +/// the same instance (preserving the password and any other +/// PGDATA-encoded settings). pub fn kill_server(name: &str) -> Result<()> { let Some(lock) = lock_existing_metadata()? else { validate_server_name(name)?; @@ -1040,16 +1067,16 @@ pub(crate) fn kill_server_locked(name: &str, lock: &MetadataLock) -> Result<()> kill_process(info.pid)?; mark_server_stopped_locked(name, info.pid, lock)?; } - Engine::Postgres => { - let id = info.container_id.as_deref().ok_or_else(|| { - Error::DockerError(format!( - "Postgres server '{}' has no container_id in metadata", - name - )) - })?; - docker::stop_blocking(id)?; + Engine::Postgres => match info.container_id.as_deref() { // Metadata + container preserved so `start` can resume. - } + Some(id) => docker::stop_blocking(id)?, + None => { + super::pg_native::stop(&lock.dir.join(name))?; + // The stored port stays: a resume starts on it again. + info.pid = 0; + save_server_info_locked(&info, lock)?; + } + }, } Ok(()) } diff --git a/crates/clickhousectl/src/version_manager/download.rs b/crates/clickhousectl/src/version_manager/download.rs index b092becfc..14ddf1823 100644 --- a/crates/clickhousectl/src/version_manager/download.rs +++ b/crates/clickhousectl/src/version_manager/download.rs @@ -64,6 +64,18 @@ pub async fn download_from_source( download_url_with_output(&url, dest_path, structured_output, etag).await } +/// Downloads `url` to `dest_path` with the install retry policy and progress +/// output. The request carries nothing but the `User-Agent`. +pub(crate) async fn download_file( + url: &str, + dest_path: &Path, + structured_output: bool, +) -> Result<()> { + download_url_with_output(url, dest_path, structured_output, None) + .await + .map(drop) +} + async fn download_url_with_output( url: &str, dest_path: &Path, diff --git a/scripts/classify-install-integration.py b/scripts/classify-install-integration.py index 306a9077e..a06297873 100644 --- a/scripts/classify-install-integration.py +++ b/scripts/classify-install-integration.py @@ -76,6 +76,8 @@ "crates/clickhousectl/src/feedback.rs", "crates/clickhousectl/src/local/config.rs", "crates/clickhousectl/src/local/docker.rs", + "crates/clickhousectl/src/local/pg_bundle.rs", + "crates/clickhousectl/src/local/pg_native.rs", "crates/clickhousectl/src/local/postgres.rs", "crates/clickhousectl/src/local/udf.rs", "crates/clickhousectl/src/search.rs", @@ -115,6 +117,7 @@ "crates/clickhousectl/tests/local_engine_lists_test.rs", "crates/clickhousectl/tests/local_init_json_test.rs", "crates/clickhousectl/tests/local_postgres_client_input_test.rs", + "crates/clickhousectl/tests/local_postgres_native_test.rs", "crates/clickhousectl/tests/local_postgres_readiness_test.rs", "crates/clickhousectl/tests/local_postgres_start_validation_test.rs", "crates/clickhousectl/tests/local_readonly_no_project_state_test.rs", diff --git a/scripts/tests/test_classify_install_integration.py b/scripts/tests/test_classify_install_integration.py index f37e48192..0700ec721 100644 --- a/scripts/tests/test_classify_install_integration.py +++ b/scripts/tests/test_classify_install_integration.py @@ -157,6 +157,8 @@ def test_exact_path_mappings(self): "crates/clickhousectl/src/feedback.rs", "crates/clickhousectl/src/local/config.rs", "crates/clickhousectl/src/local/docker.rs", + "crates/clickhousectl/src/local/pg_bundle.rs", + "crates/clickhousectl/src/local/pg_native.rs", "crates/clickhousectl/src/local/postgres.rs", "crates/clickhousectl/src/local/udf.rs", "crates/clickhousectl/src/search.rs", @@ -196,6 +198,7 @@ def test_exact_path_mappings(self): "crates/clickhousectl/tests/local_engine_lists_test.rs", "crates/clickhousectl/tests/local_init_json_test.rs", "crates/clickhousectl/tests/local_postgres_client_input_test.rs", + "crates/clickhousectl/tests/local_postgres_native_test.rs", "crates/clickhousectl/tests/local_postgres_readiness_test.rs", "crates/clickhousectl/tests/local_postgres_start_validation_test.rs", "crates/clickhousectl/tests/local_readonly_no_project_state_test.rs", From 3cf31c66bbd05cda3a7c04e71379319fddad7c11 Mon Sep 17 00:00:00 2001 From: sdairs Date: Mon, 16 Nov 2026 16:53:31 +0000 Subject: [PATCH 2/5] test(local): cover the native Postgres lifecycle and pin Docker tests to --docker (#1464) local_postgres_native_test drives install, checksum and manifest failures, start/stop/resume/remove and rollback against a file:// bundle source whose programs are shell scripts, with no network or real PostgreSQL. Tests and the integration battery that exercise the Docker runtime now ask for it. Co-Authored-By: Claude Fable 5.2 --- .../tests/local_docker_diagnostics_test.rs | 4 +- .../tests/local_docker_pull_progress_test.rs | 8 +- .../tests/local_postgres_native_test.rs | 461 ++++++++++++++++++ .../tests/local_postgres_readiness_test.rs | 2 + .../tests/local_structured_errors_test.rs | 4 +- scripts/test-postgres-integration.sh | 47 +- 6 files changed, 498 insertions(+), 28 deletions(-) create mode 100644 crates/clickhousectl/tests/local_postgres_native_test.rs diff --git a/crates/clickhousectl/tests/local_docker_diagnostics_test.rs b/crates/clickhousectl/tests/local_docker_diagnostics_test.rs index 8c086d890..8e5bdd1e1 100644 --- a/crates/clickhousectl/tests/local_docker_diagnostics_test.rs +++ b/crates/clickhousectl/tests/local_docker_diagnostics_test.rs @@ -12,9 +12,9 @@ fn clickhousectl_binary() -> PathBuf { fn run_postgres_start(home: &Path, project: &Path, docker_host: &str, json: bool) -> Output { let args: &[&str] = if json { - &["local", "--json", "postgres", "start"] + &["local", "--json", "postgres", "start", "--docker"] } else { - &["local", "postgres", "start"] + &["local", "postgres", "start", "--docker"] }; Command::new(clickhousectl_binary()) .env_clear() diff --git a/crates/clickhousectl/tests/local_docker_pull_progress_test.rs b/crates/clickhousectl/tests/local_docker_pull_progress_test.rs index f55d39bba..1fbf519d5 100644 --- a/crates/clickhousectl/tests/local_docker_pull_progress_test.rs +++ b/crates/clickhousectl/tests/local_docker_pull_progress_test.rs @@ -88,7 +88,13 @@ fn run_install(tag: &str, pull_response: &str) -> Output { .env("HOME", tempdir.path()) .current_dir(tempdir.path()) .env("DOCKER_HOST", format!("unix://{}", socket_path.display())) - .args(["local", "install", &format!("postgres@{tag}"), "--force"]) + .args([ + "local", + "install", + &format!("postgres@{tag}"), + "--force", + "--docker", + ]) .stdout(Stdio::piped()) .stderr(Stdio::piped()); let mut child = command.spawn().expect("run clickhousectl"); diff --git a/crates/clickhousectl/tests/local_postgres_native_test.rs b/crates/clickhousectl/tests/local_postgres_native_test.rs new file mode 100644 index 000000000..a8f1a0666 --- /dev/null +++ b/crates/clickhousectl/tests/local_postgres_native_test.rs @@ -0,0 +1,461 @@ +//! Subprocess coverage for the native `local postgres` runtime, without the +//! network or a real PostgreSQL: the bundle source is a `file://` directory +//! holding a manifest and a tiny bundle whose programs are shell scripts. + +use serde_json::{Value, json}; +use sha2::{Digest, Sha256}; +use std::os::unix::fs::PermissionsExt; +use std::path::PathBuf; +use std::process::{Command, Output}; + +const PG_VERSION: &str = "18.7"; + +fn clickhousectl_binary() -> PathBuf { + PathBuf::from(env!("CARGO_BIN_EXE_clickhousectl")) +} + +fn target() -> &'static str { + match (std::env::consts::OS, std::env::consts::ARCH) { + ("macos", "aarch64") => "aarch64-apple-darwin", + ("macos", "x86_64") => "x86_64-apple-darwin", + ("linux", "aarch64") => "aarch64-unknown-linux-musl", + ("linux", "x86_64") => "x86_64-unknown-linux-musl", + other => panic!("no bundle target for {other:?}"), + } +} + +fn bundle_name() -> String { + format!("pg-{PG_VERSION}-pgch-0.11.1-{}", target()) +} + +/// The fake programs. `postgres` behaves like a postmaster as far as the CLI +/// can tell: it runs from the data directory, records its PID there and +/// exits on SIGINT. `FAKE_*` variables reach them through the CLI's +/// environment and select a failure. +const PROGRAMS: [(&str, &str); 5] = [ + ( + "initdb", + r#"#!/bin/sh +data="" +while [ $# -gt 0 ]; do + [ "$1" = "-D" ] && data="$2" + printf '%s\n' "$1" >> "$FAKE_RECORD_DIR/initdb.args" + case "$1" in --pwfile=*) cp "${1#--pwfile=}" "$FAKE_RECORD_DIR/pwfile" ;; esac + shift +done +mkdir -p "$data" && echo 18 > "$data/PG_VERSION" +"#, + ), + ( + "postgres", + r#"#!/bin/sh +[ -n "$FAKE_POSTGRES_EXIT" ] && { echo "FATAL: fake postmaster failure" >&2; exit "$FAKE_POSTGRES_EXIT"; } +while [ $# -gt 0 ]; do + [ "$1" = "-D" ] && data="$2" + shift +done +cd "$data" || exit 1 +echo $$ > postmaster.pid +echo $$ > "$FAKE_RECORD_DIR/postmaster.pid" +exec sleep 600 +"#, + ), + // Ready while the recorded postmaster is alive. + ( + "pg_isready", + "#!/bin/sh\nkill -0 \"$(cat \"$FAKE_RECORD_DIR/postmaster.pid\" 2>/dev/null)\" 2>/dev/null\n", + ), + ( + "createdb", + "#!/bin/sh\n[ -n \"$FAKE_CREATEDB_EXIT\" ] && { echo 'fake createdb failure' >&2; exit \"$FAKE_CREATEDB_EXIT\"; }\nexit 0\n", + ), + ( + "psql", + "#!/bin/sh\nprintf 'fake-psql'; printf ' %s' \"$@\"; printf '\\n'\n", + ), +]; + +/// A bundle tarball laid out as the real ones are: one top-level directory +/// holding `bin/`. +fn bundle_tarball() -> Vec { + let encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast()); + let mut archive = tar::Builder::new(encoder); + for (program, script) in PROGRAMS { + let mut header = tar::Header::new_gnu(); + header.set_size(script.len() as u64); + header.set_mode(0o755); + header.set_cksum(); + archive + .append_data( + &mut header, + format!("{}/bin/{program}", bundle_name()), + script.as_bytes(), + ) + .expect("append fake program"); + } + archive + .into_inner() + .expect("finish tar") + .finish() + .expect("finish gzip") +} + +fn sha256(bytes: &[u8]) -> String { + Sha256::digest(bytes) + .iter() + .map(|byte| format!("{byte:02x}")) + .collect() +} + +struct Fixture { + _root: tempfile::TempDir, + home: PathBuf, + project: PathBuf, + source: PathBuf, + record: PathBuf, + sha256: String, +} + +impl Fixture { + /// A project, a home and a bundle source whose manifest is `manifest` + /// applied to the true description of the one bundle. + fn with_manifest(manifest: impl FnOnce(&mut Value)) -> Self { + let root = tempfile::tempdir().expect("create fixture root"); + // Canonical, as the CLI records it (`/var` is a symlink on macOS). + let base = root.path().canonicalize().expect("canonical fixture root"); + let [home, project, source, record] = + ["home", "project", "source", "record"].map(|dir| base.join(dir)); + for dir in [&home, &project, &source, &record] { + std::fs::create_dir(dir).expect("create fixture dir"); + } + std::fs::create_dir(project.join(".clickhouse")).expect("mark project"); + + let tarball = bundle_tarball(); + let sha256 = sha256(&tarball); + let file = format!("{}.tar.gz", bundle_name()); + std::fs::write(source.join(&file), &tarball).expect("write bundle"); + let mut document = json!({ + "schema": 1, + "release": "v0.3.0", + "built_at": "2026-11-16T00:00:00Z", + "source": { "repo": "sdairs/pg-bundles", "commit": "0000000" }, + "bundles": [{ + "postgres_version": PG_VERSION, + "postgres_major": "18", + "extensions": { "pg_clickhouse": "0.11.1" }, + "target": target(), + "file": file, + "sha256": sha256, + "size": tarball.len(), + }], + }); + manifest(&mut document); + std::fs::write( + source.join("manifest.json"), + serde_json::to_vec(&document).unwrap(), + ) + .expect("write manifest"); + Self { + _root: root, + home, + project, + source, + record, + sha256, + } + } + + fn new() -> Self { + Self::with_manifest(|_| {}) + } + + fn command(&self, args: &[&str]) -> Command { + let mut command = Command::new(clickhousectl_binary()); + command + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("CHCTL_UPDATE_CHECK_TIMEOUT_MS", "0") + .env("HOME", &self.home) + .env("PATH", "/usr/bin:/bin") + // No Docker: nothing here may need it. + .env("DOCKER_HOST", "unix:///nonexistent/docker.sock") + .env( + "CLICKHOUSECTL_POSTGRES_BUNDLES_URL", + format!("file://{}", self.source.display()), + ) + .env("FAKE_RECORD_DIR", &self.record) + .current_dir(&self.project) + .args(["local", "--json", "postgres"]) + .args(args); + command + } + + fn run(&self, args: &[&str]) -> Output { + self.command(args).output().expect("run clickhousectl") + } + + fn ok(&self, args: &[&str]) -> Value { + let output = self.run(args); + assert!( + output.status.success(), + "{args:?} failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + serde_json::from_slice(&output.stdout).expect("parse JSON stdout") + } + + fn instance_dir(&self) -> PathBuf { + self.project.join(".clickhouse/servers/default-pg18") + } + + fn cache_dir(&self) -> PathBuf { + self.home.join(".clickhouse/postgres") + } + + fn cached_bundles(&self) -> Vec { + match std::fs::read_dir(self.cache_dir()) { + Ok(entries) => entries + .map(|entry| entry.unwrap().file_name().into_string().unwrap()) + .collect(), + Err(_) => Vec::new(), + } + } + + /// The PID of the last fake postmaster this fixture's CLI spawned. + fn postmaster_pid(&self) -> i32 { + std::fs::read_to_string(self.record.join("postmaster.pid")) + .expect("fake postmaster recorded its PID") + .trim() + .parse() + .expect("PID is a number") + } +} + +impl Drop for Fixture { + fn drop(&mut self) { + // A failed assertion must not leave a fake postmaster behind. + if let Ok(pid) = std::fs::read_to_string(self.record.join("postmaster.pid")) + && let Ok(pid) = pid.trim().parse::() + { + // SAFETY: `kill` takes plain integers and touches no memory. + unsafe { libc::kill(pid, libc::SIGKILL) }; + } + } +} + +fn process_is_gone(pid: i32) -> bool { + for _ in 0..200 { + // SAFETY: `kill` takes plain integers and touches no memory. + if unsafe { libc::kill(pid, 0) } != 0 { + return true; + } + std::thread::sleep(std::time::Duration::from_millis(10)); + } + false +} + +fn error_of(output: &Output) -> Value { + let stderr = String::from_utf8_lossy(&output.stderr); + let start = stderr + .find("{\n \"error\"") + .unwrap_or_else(|| panic!("no JSON error on stderr: {stderr}")); + serde_json::from_str::(&stderr[start..]).expect("parse JSON error")["error"].clone() +} + +#[test] +fn native_instance_installs_once_then_starts_stops_resumes_offline_and_is_removed() { + let fixture = Fixture::new(); + let password = "example-password"; + + let started = fixture.ok(&["start", "--password", password, "--database", "app"]); + assert_eq!(started["name"], "default"); + assert_eq!(started["runtime"], "native"); + assert_eq!(started["image"], format!("postgres:{PG_VERSION}")); + assert_eq!(started["extensions"]["pg_clickhouse"], "0.11.1"); + assert_eq!(started["password"], password); + assert_eq!(started["database"], "app"); + assert!(started.get("container_id").is_none()); + let pid = fixture.postmaster_pid(); + assert_eq!(started["pid"], pid); + let port = started["port"].as_u64().expect("port"); + + // The cache directory is keyed on the bundle name and its sha256. + assert_eq!( + fixture.cached_bundles(), + [format!("{}-{}", bundle_name(), &fixture.sha256[..12])] + ); + // The password reached initdb through a file, never its arguments. + let initdb_args = std::fs::read_to_string(fixture.record.join("initdb.args")).unwrap(); + assert!(!initdb_args.contains(password), "{initdb_args}"); + assert_eq!( + std::fs::read_to_string(fixture.record.join("pwfile")) + .unwrap() + .trim_end(), + password + ); + // Credentials are stored for this user only, with no bundle path. + let state_path = fixture.instance_dir().join("native.json"); + let mode = std::fs::metadata(&state_path).unwrap().permissions().mode(); + assert_eq!(mode & 0o777, 0o600); + let state: Value = serde_json::from_slice(&std::fs::read(&state_path).unwrap()).unwrap(); + assert_eq!(state["postgres_major"], "18"); + assert_eq!(state["bundle"]["sha256"], fixture.sha256); + + // Listed where a Docker instance is: its own list and `local status`. + let listed = fixture.ok(&["list"]); + assert_eq!(listed["total_running_servers"], 1); + let entry = &listed["servers"][0]; + assert_eq!(entry["name"], "default"); + assert_eq!(entry["engine"], "postgres"); + assert_eq!(entry["running"], true); + assert_eq!(entry["pid"], pid); + assert_eq!(entry["tcp_port"], port); + assert!(entry.get("container_id").is_none()); + + let dotenv = fixture.ok(&["dotenv", "--local"]); + let var = |key: &str| { + dotenv["vars"] + .as_array() + .unwrap() + .iter() + .find(|var| var["key"] == key) + .unwrap_or_else(|| panic!("{key} missing"))["value"] + .clone() + }; + assert_eq!(var("POSTGRES_PORT"), port.to_string()); + assert_eq!(var("POSTGRES_PASSWORD"), password); + assert_eq!(var("POSTGRES_DATABASE"), "app"); + + // `client` runs the bundle's psql against the instance. + let client = fixture.run(&["client", "--query", "SELECT 1"]); + assert!(client.status.success()); + let psql = String::from_utf8_lossy(&client.stdout); + assert!(psql.starts_with("fake-psql "), "{psql}"); + assert!(psql.contains(&format!("-p {port} ")), "{psql}"); + + let stopped = fixture.ok(&["stop"]); + assert_eq!(stopped["already_stopped"], false); + assert!(process_is_gone(pid)); + assert_eq!(fixture.ok(&["list"])["total_running_servers"], 0); + + // A resume needs neither the bundle source nor a new install, and keeps + // the stored port and credentials whatever is passed. + let resumed = fixture + .command(&["start", "--password", "ignored-on-resume"]) + .env( + "CLICKHOUSECTL_POSTGRES_BUNDLES_URL", + "file:///nonexistent/bundles", + ) + .output() + .expect("resume"); + assert!( + resumed.status.success(), + "{}", + String::from_utf8_lossy(&resumed.stderr) + ); + let resumed: Value = serde_json::from_slice(&resumed.stdout).unwrap(); + assert_eq!(resumed["port"], port); + assert_eq!(resumed["password"], password); + let resumed_pid = fixture.postmaster_pid(); + assert_ne!(resumed_pid, pid); + assert_eq!(fixture.cached_bundles().len(), 1); + + // `remove` stops a running native instance and leaves nothing behind. + fixture.ok(&["remove"]); + assert!(process_is_gone(resumed_pid)); + assert!(!fixture.instance_dir().exists()); + assert_eq!(fixture.ok(&["list"])["total_servers"], 0); +} + +#[test] +fn checksum_mismatch_installs_nothing_and_starts_nothing() { + let fixture = Fixture::with_manifest(|manifest| { + manifest["bundles"][0]["sha256"] = "0".repeat(64).into(); + }); + + let output = fixture.run(&["start"]); + + assert_eq!(output.status.code(), Some(1)); + assert_eq!(error_of(&output)["code"], "checksum_mismatch"); + assert!(fixture.cached_bundles().is_empty()); + assert!(!fixture.instance_dir().exists()); + assert!(!fixture.record.join("initdb.args").exists()); +} + +#[test] +fn unusable_manifests_fail_with_a_bundle_error_before_any_install() { + for edit in [ + (|manifest: &mut Value| manifest["schema"] = 2.into()) as fn(&mut Value), + // Nothing published for this machine. + |manifest| manifest["bundles"][0]["target"] = "riscv64-unknown-none".into(), + // A manifest entry without a digest is never installed. + |manifest| manifest["bundles"][0]["sha256"] = "".into(), + ] { + let fixture = Fixture::with_manifest(edit); + + let output = fixture.run(&["start"]); + + assert_eq!(output.status.code(), Some(1)); + assert_eq!(error_of(&output)["code"], "postgres_bundle_unavailable"); + assert!(fixture.cached_bundles().is_empty()); + assert!(!fixture.instance_dir().exists()); + } +} + +#[test] +fn postmaster_that_exits_before_ready_rolls_the_fresh_instance_back() { + let fixture = Fixture::new(); + + let output = fixture + .command(&["start"]) + .env("FAKE_POSTGRES_EXIT", "1") + .output() + .expect("run start"); + + assert_eq!(output.status.code(), Some(1)); + let error = error_of(&output); + assert_eq!(error["code"], "startup_exit"); + // The postmaster's own output is carried for diagnosis. + assert!( + error["details"] + .as_str() + .is_some_and(|details| details.contains("fake postmaster failure")), + "{error}" + ); + assert!(!fixture.instance_dir().exists()); + assert_eq!(fixture.ok(&["list"])["total_servers"], 0); + // The bundle stays installed for the retry, which then succeeds. + assert_eq!(fixture.cached_bundles().len(), 1); + fixture.ok(&["start"]); + fixture.ok(&["remove"]); +} + +#[test] +fn createdb_failure_stops_the_postmaster_and_leaves_no_instance() { + let fixture = Fixture::new(); + + let output = fixture + .command(&["start", "--database", "app"]) + .env("FAKE_CREATEDB_EXIT", "1") + .output() + .expect("run start"); + + assert_eq!(output.status.code(), Some(1)); + assert!(process_is_gone(fixture.postmaster_pid())); + assert!(!fixture.instance_dir().exists()); + assert_eq!(fixture.ok(&["list"])["total_servers"], 0); +} + +#[test] +fn docker_flag_on_a_native_instance_is_a_usage_error_that_changes_nothing() { + let fixture = Fixture::new(); + fixture.ok(&["start"]); + let pid = fixture.postmaster_pid(); + + let output = fixture.run(&["start", "default", "--docker"]); + + assert_eq!(output.status.code(), Some(2)); + assert!(String::from_utf8_lossy(&output.stderr).contains("--docker")); + assert_eq!(fixture.ok(&["list"])["servers"][0]["pid"], pid); + fixture.ok(&["remove"]); +} diff --git a/crates/clickhousectl/tests/local_postgres_readiness_test.rs b/crates/clickhousectl/tests/local_postgres_readiness_test.rs index d6288aca2..1d14626d5 100644 --- a/crates/clickhousectl/tests/local_postgres_readiness_test.rs +++ b/crates/clickhousectl/tests/local_postgres_readiness_test.rs @@ -537,6 +537,7 @@ fn run_start_command( "--json", "postgres", "start", + "--docker", "--wait-timeout", &wait_timeout, ]); @@ -754,6 +755,7 @@ fn postgres_start_revalidates_metadata_after_image_inspection() { "local", "postgres", "start", + "--docker", "--name", "default", "--version", diff --git a/crates/clickhousectl/tests/local_structured_errors_test.rs b/crates/clickhousectl/tests/local_structured_errors_test.rs index b4c4321bb..67d79271e 100644 --- a/crates/clickhousectl/tests/local_structured_errors_test.rs +++ b/crates/clickhousectl/tests/local_structured_errors_test.rs @@ -325,7 +325,7 @@ fn io_and_docker_errors_keep_paths_and_secrets_out_of_json() { let docker_secret = home.join("docker-secret-token.sock"); let unavailable = command(&project, &home) .env("DOCKER_HOST", format!("unix://{}", docker_secret.display())) - .args(["local", "--json", "postgres", "start"]) + .args(["local", "--json", "postgres", "start", "--docker"]) .output() .expect("run Docker unavailable failure"); assert_eq!(unavailable.status.code(), Some(1)); @@ -335,7 +335,7 @@ fn io_and_docker_errors_keep_paths_and_secrets_out_of_json() { let message = error["error"]["message"].as_str().expect("message"); let human = command(&project, &home) .env("DOCKER_HOST", format!("unix://{}", docker_secret.display())) - .args(["local", "postgres", "start"]) + .args(["local", "postgres", "start", "--docker"]) .output() .expect("run human Docker unavailable failure"); assert_eq!( diff --git a/scripts/test-postgres-integration.sh b/scripts/test-postgres-integration.sh index cc54ca5fb..46154c315 100755 --- a/scripts/test-postgres-integration.sh +++ b/scripts/test-postgres-integration.sh @@ -1,5 +1,6 @@ #!/usr/bin/env bash -# Edge-case battery for `clickhousectl local postgres`. Runs each test in +# Edge-case battery for the Docker runtime of `clickhousectl local postgres` +# (`start --docker`). Runs each test in # isolation in a temp directory, prints PASS/FAIL, and continues on # failure so we get a full picture in one run. # @@ -73,7 +74,7 @@ die() { echo " -> $*"; return 1; } # ── 1. Reuses existing container after stop/delete-metadata via discovery ── case_orphan_recovery() { - "$CTL" local postgres start --name a --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name a --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } local meta=.clickhouse/servers/a-pg18.json local cid_before; cid_before=$(jq -r .container_id "$meta") "$CTL" local postgres stop a >/dev/null 2>&1 || { die "stop"; return 1; } @@ -88,25 +89,25 @@ case_orphan_recovery() { # ── 2. start with externally-removed container errors with recovery guidance ── case_externally_removed_container() { - "$CTL" local postgres start --name b --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name b --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } local cid; cid=$(jq -r .container_id .clickhouse/servers/b-pg18.json) docker rm -f "$cid" >/dev/null 2>&1 || { die "docker rm failed"; return 1; } # Metadata still references the dead id. Should error with explicit # recovery guidance, not silently recreate against potentially-corrupt PGDATA. - local out; out=$("$CTL" local postgres start --name b --version 18-alpine 2>&1) || true + local out; out=$("$CTL" local postgres start --docker --name b --version 18-alpine 2>&1) || true echo "$out" | grep -q "container is gone" || { die "no recovery message: $out"; return 1; } # `local postgres remove` should clean it up. "$CTL" local postgres remove b >/dev/null 2>&1 || { die "remove after orphan failed"; return 1; } # Now start fresh should work. - "$CTL" local postgres start --name b --version 18-alpine >/dev/null 2>&1 || { die "fresh start after remove failed"; return 1; } + "$CTL" local postgres start --docker --name b --version 18-alpine >/dev/null 2>&1 || { die "fresh start after remove failed"; return 1; } "$CTL" local postgres stop b >/dev/null 2>&1 "$CTL" local postgres remove b >/dev/null 2>&1 } # ── 3. Two named postgres servers coexist on different ports ── case_two_concurrent_servers() { - "$CTL" local postgres start --name c1 --version 18-alpine >/dev/null 2>&1 || { die "start c1"; return 1; } - "$CTL" local postgres start --name c2 --version 18-alpine >/dev/null 2>&1 || { die "start c2"; return 1; } + "$CTL" local postgres start --docker --name c1 --version 18-alpine >/dev/null 2>&1 || { die "start c1"; return 1; } + "$CTL" local postgres start --docker --name c2 --version 18-alpine >/dev/null 2>&1 || { die "start c2"; return 1; } local p1 p2 p1=$(jq -r .tcp_port .clickhouse/servers/c1-pg18.json) p2=$(jq -r .tcp_port .clickhouse/servers/c2-pg18.json) @@ -120,9 +121,9 @@ case_two_concurrent_servers() { # ── 4. Same name, two majors → two isolated instances ── case_per_version_isolation() { - "$CTL" local postgres start --name d --version 17-alpine >/dev/null 2>&1 || { die "start 17"; return 1; } + "$CTL" local postgres start --docker --name d --version 17-alpine >/dev/null 2>&1 || { die "start 17"; return 1; } "$CTL" local postgres stop d >/dev/null 2>&1 - "$CTL" local postgres start --name d --version 18-alpine >/dev/null 2>&1 || { die "start 18"; return 1; } + "$CTL" local postgres start --docker --name d --version 18-alpine >/dev/null 2>&1 || { die "start 18"; return 1; } [[ -f .clickhouse/servers/d-pg17.json ]] || { die "17 metadata vanished"; return 1; } [[ -f .clickhouse/servers/d-pg18.json ]] || { die "18 metadata not created"; return 1; } [[ -d .clickhouse/servers/d-pg17/data ]] || { die "17 data dir vanished"; return 1; } @@ -137,12 +138,12 @@ case_per_version_isolation() { # ── 5. dotenv reflects the actual container password (post-restart) ── case_dotenv_password_consistency() { - "$CTL" local postgres start --name e --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name e --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } local pw_meta; pw_meta=$("$CTL" local postgres dotenv --name e 2>/dev/null \ | grep POSTGRES_PASSWORD= | cut -d= -f2) [[ -n "$pw_meta" ]] || { die "no password emitted"; return 1; } "$CTL" local postgres stop e >/dev/null 2>&1 - "$CTL" local postgres start --name e >/dev/null 2>&1 || { die "restart"; return 1; } + "$CTL" local postgres start --docker --name e >/dev/null 2>&1 || { die "restart"; return 1; } local pw_after; pw_after=$("$CTL" local postgres dotenv --name e 2>/dev/null \ | grep POSTGRES_PASSWORD= | cut -d= -f2) [[ "$pw_meta" == "$pw_after" ]] || { die "password drifted: $pw_meta -> $pw_after"; return 1; } @@ -152,7 +153,7 @@ case_dotenv_password_consistency() { # ── 6. Path-traversal server name rejected ── case_path_traversal_name() { - local out; out=$("$CTL" local postgres start --name "../etc" 2>&1) || true + local out; out=$("$CTL" local postgres start --docker --name "../etc" 2>&1) || true echo "$out" | grep -qiE "invalid|name" || { die "no rejection: $out"; return 1; } } @@ -170,7 +171,7 @@ case_cross_engine_coexist() { {"name":"shared","pid":99999,"version":"25.12.5.44","http_port":8123,"tcp_port":9000,"started_at":"0","cwd":"$PWD","engine":"clickhouse"} EOF # Starting Postgres "shared" should succeed — CH and PG live in different files. - "$CTL" local postgres start --name shared --version 18-alpine >/dev/null 2>&1 \ + "$CTL" local postgres start --docker --name shared --version 18-alpine >/dev/null 2>&1 \ || { die "postgres start with same name failed"; return 1; } [[ -f .clickhouse/servers/shared.json ]] || { die "CH metadata clobbered"; return 1; } [[ -f .clickhouse/servers/shared-pg18.json ]] || { die "PG metadata not created"; return 1; } @@ -192,7 +193,7 @@ case_stop_all_engine_scopes() ( cat > .clickhouse/servers/c.json </dev/null 2>&1 || { die "start postgres"; return 1; } + "$CTL" local postgres start --docker --name p --version 18-alpine >/dev/null 2>&1 || { die "start postgres"; return 1; } "$CTL" local postgres stop-all >/dev/null 2>&1 || { die "postgres stop-all"; return 1; } local list; list=$("$CTL" local --json status 2>&1) || { die "status after postgres stop-all: $list"; return 1; } @@ -201,7 +202,7 @@ EOF jq -e '.servers | any(.name == "p" and .engine == "postgres" and .running == false)' <<<"$list" >/dev/null \ || { die "postgres stop-all did not stop Postgres: $list"; return 1; } - "$CTL" local postgres start --name p --version 18-alpine >/dev/null 2>&1 || { die "restart postgres"; return 1; } + "$CTL" local postgres start --docker --name p --version 18-alpine >/dev/null 2>&1 || { die "restart postgres"; return 1; } local out; out=$("$CTL" local --json clickhouse stop-all 2>&1) || { die "clickhouse stop-all: $out"; return 1; } jq -e '.servers | any(.name == "c" and .engine == "clickhouse" and .stopped == true)' <<<"$out" >/dev/null \ || { die "clickhouse stop-all did not report ClickHouse: $out"; return 1; } @@ -223,14 +224,14 @@ EOF # ── 11. --port 0 rejected ── case_port_zero_rejected() { # Assert the usage exit code and the offending flag, not the sentence. - local out rc=0; out=$("$CTL" local postgres start --name z --port 0 2>&1) || rc=$? + local out rc=0; out=$("$CTL" local postgres start --docker --name z --port 0 2>&1) || rc=$? [[ $rc -eq 2 ]] || { die "expected exit 2, got $rc: $out"; return 1; } echo "$out" | grep -Fq -- "--port" || { die "rejection does not name --port: $out"; return 1; } } # ── 12. Non-TTY query path returns query result ── case_non_tty_query() { - "$CTL" local postgres start --name q --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name q --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } # Wait for pg to be query-ready (up to ~5s); the first start already waits # for the container, but pg itself takes a moment to accept queries. local cid; cid=$(jq -r .container_id .clickhouse/servers/q-pg18.json) @@ -249,7 +250,7 @@ case_non_tty_query() { # ── 13. dotenv preserves unmanaged vars and replaces in-place ── case_dotenv_preserves_other_vars() { - "$CTL" local postgres start --name r --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name r --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } cat > .env </dev/null 2>&1 || { die "start"; return 1; } + "$CTL" local postgres start --docker --name s --version 18-alpine >/dev/null 2>&1 || { die "start"; return 1; } local out; out=$("$CTL" local postgres remove s 2>&1) || true echo "$out" | grep -qE "already running|running" || { die "no rejection: $out"; return 1; } "$CTL" local postgres stop s >/dev/null 2>&1 @@ -276,7 +277,7 @@ case_majors_start_and_serve() { local tag fail=0 for tag in 17 18; do local n="m$tag" - if ! "$CTL" local postgres start --name "$n" --version "$tag" >/dev/null 2>&1; then + if ! "$CTL" local postgres start --docker --name "$n" --version "$tag" >/dev/null 2>&1; then die "start postgres:$tag failed" fail=1 continue @@ -303,9 +304,9 @@ case_majors_start_and_serve() { # ── 16. validate_pg_tag rejects 14, 16, and 19 ── case_unsupported_majors() { local o14 o16 o19 - o14=$("$CTL" local postgres start --name t --version 14-alpine 2>&1) || true - o16=$("$CTL" local postgres start --name t --version 16-alpine 2>&1) || true - o19=$("$CTL" local postgres start --name t --version 19 2>&1) || true + o14=$("$CTL" local postgres start --docker --name t --version 14-alpine 2>&1) || true + o16=$("$CTL" local postgres start --docker --name t --version 16-alpine 2>&1) || true + o19=$("$CTL" local postgres start --docker --name t --version 19 2>&1) || true echo "$o14" | grep -q "invalid or unsupported postgres version" || { die "14 not rejected: $o14"; return 1; } echo "$o16" | grep -q "invalid or unsupported postgres version" || { die "16 not rejected: $o16"; return 1; } echo "$o19" | grep -q "invalid or unsupported postgres version" || { die "19 not rejected: $o19"; return 1; } From 40955c1aec1535d4f694b5b33ca688e22c8adbd4 Mon Sep 17 00:00:00 2001 From: sdairs Date: Mon, 16 Nov 2026 16:53:31 +0000 Subject: [PATCH 3/5] docs(local): describe native local Postgres, pg_clickhouse and --docker (#1464) Co-Authored-By: Claude Fable 5.2 --- AGENTS.md | 3 ++- README.md | 4 ++-- docs/development.md | 7 +++++-- docs/guides/local-development.md | 36 ++++++++++++++++++++++++++------ docs/reference/automation.md | 4 +++- 5 files changed, 42 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 79b966943..6800b8903 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,8 @@ work on a branch, with an associated issue and a PR. (`.agents/skills/openapi-drift-remediation/SKILL.md`). - Update the API library on its own; add CLI exposure separately. The CLI need not cover 100% of the library's endpoints — be intentional. -- Project-local data lives in `.clickhouse/`; globally installed ClickHouse binaries in `~/.clickhouse/`. OAuth +- Project-local data lives in `.clickhouse/`; globally installed ClickHouse binaries and PostgreSQL bundles + (`postgres/`) in `~/.clickhouse/`. OAuth tokens (`~/.clickhouse/tokens.json`) are the exception — global user identity, not project-scoped. The project root is found git-style, once per run (`init::project_root`): the nearest ancestor with a `.clickhouse/` directory owned by the user, stopping at home, whose `.clickhouse/` is global; `local init` uses the cwd. diff --git a/README.md b/README.md index 5756d41fd..0a1043c17 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ - **[ClickHouse](https://clickhouse.com/clickhouse)** is the open-source, column-oriented SQL database for analytics. Install and switch local versions, run isolated servers, and execute SQL. - **[ClickHouse Cloud](https://clickhouse.com/cloud)** runs ClickHouse as a managed service on AWS, GCP, and Azure. Create, configure, scale, back up, and query services from the terminal. -- **[ClickHouse Managed Postgres](https://clickhouse.com/cloud/postgres)** runs PostgreSQL for transactional applications, with ClickHouse integration for analytics. Use Docker-backed Postgres locally, then create, monitor, configure, and restore managed services in Cloud. +- **[ClickHouse Managed Postgres](https://clickhouse.com/cloud/postgres)** runs PostgreSQL for transactional applications, with ClickHouse integration for analytics. Run Postgres with the pg_clickhouse extension locally, then create, monitor, configure, and restore managed services in Cloud. - **[ClickPipes](https://clickhouse.com/cloud/clickpipes)** ingests data into ClickHouse Cloud from object storage, streams, and databases through change data capture. Create, inspect, update, scale, and troubleshoot pipelines. - **[ClickStack](https://clickhouse.com/clickstack)** combines ClickHouse, OpenTelemetry, and the HyperDX UI for observability. Manage sources, roles, saved searches, dashboards, alerts, and webhooks for an existing [Managed ClickStack](https://clickhouse.com/cloud/clickstack) service. @@ -85,7 +85,7 @@ clickhousectl local clickhouse stop dev `local init` marks the directory as a project; later commands work from it or any subdirectory, as Git does. Each named server has isolated data under the project's `.clickhouse/`; stopping preserves it for the next start. -For local Postgres, start Docker first: +Local Postgres needs no Docker: the first start downloads a PostgreSQL build that includes the pg_clickhouse extension. ```bash clickhousectl local postgres start dev diff --git a/docs/development.md b/docs/development.md index d3b4a7b6f..e0f87778e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -7,7 +7,7 @@ | Path | Responsibility | | --- | --- | | `crates/clickhousectl/src/main.rs`, `cli.rs` | Entrypoint, common CLI options, output mode | -| `crates/clickhousectl/src/local/` | Local command definitions, dispatch, servers, Docker/Postgres, output | +| `crates/clickhousectl/src/local/` | Local command definitions, dispatch, servers, Postgres (`postgres.rs` chooses the runtime; `pg_bundle.rs` and `pg_native.rs` are the native one, `docker.rs` the Docker one), output | | `crates/clickhousectl/src/cloud/.rs` | Cloud domain definitions, handlers, builders, wrappers, tests | | `crates/clickhousectl/src/cloud//` | A large Cloud domain: `PERMISSIONS` and dispatch in `mod.rs`, command enums and shared arg groups in `cli.rs` (a source-specific arg struct may sit with its builder, as in `clickpipes/sources/.rs`), `CloudClient` wrappers in `client.rs`, one file per command family, tests beside the code they test | | `crates/clickhousectl/src/cloud/client.rs` | Credential resolution and shared Cloud client/error handling | @@ -24,7 +24,8 @@ Run the standard CLI gates from [Contributing](../CONTRIBUTING.md#build-and-test - Clap parsing and request builders have tests beside command definitions. - `crates/clickhousectl/tests/cloud/` (one test binary, one module per Cloud domain, shared helpers in `support.rs`) spawns the binary against wiremock for Cloud handler behaviour that the unit tests can't reach: multi-call flows, error paths, auth wiring, and output contracts. [AGENTS.md](../AGENTS.md#tests) holds the rule for what belongs there. - Local subprocess tests use separate `local_*` binaries for each concern. -- `scripts/test-postgres-integration.sh` is an edge-case battery for `local postgres` against a real Docker daemon; `.github/workflows/test-postgres-integration.yml` runs it on PRs that touch `crates/clickhousectl/src/local/**`, and it can be run by hand with a built binary. +- `local_postgres_native_test` covers the native `local postgres` runtime with neither the network nor a real PostgreSQL: it points `CLICKHOUSECTL_POSTGRES_BUNDLES_URL` at a `file://` directory holding a manifest and a small bundle whose programs are shell scripts. +- `scripts/test-postgres-integration.sh` is an edge-case battery for the Docker runtime of `local postgres` (`start --docker`) against a real Docker daemon; `.github/workflows/test-postgres-integration.yml` runs it on PRs that touch `crates/clickhousectl/src/local/**`, and it can be run by hand with a built binary. - Pure version/auth/output logic uses inline tests. - Three local tests are `#[ignore]`d because they need a real server, and no workflow runs them; run one with `cargo test -p clickhousectl --test -- --ignored`: `local_postgres_client_input_test` needs a running Docker daemon, `local_client_output_contract_test` needs `CHCTL_TEST_NATIVE_BINARY` and `CHCTL_TEST_NATIVE_PORT` for a disposable server, and `local_server_managed_config_test` needs `CLICKHOUSECTL_LIVE_CLICKHOUSE_VERSION` set to an installed version. @@ -48,6 +49,8 @@ Subprocess tests must not wait out production timeouts. `crates/clickhousectl/sr Add a new override to that module rather than parsing an environment variable at the call site. Every subprocess test clears the inherited environment and sets `HOME` to a directory the test owns, so a developer's credentials, proxies and coding-agent variables never change the result. In `tests/cloud/`, use `isolated_env()` from `support.rs` in place of `env_clear()`: it clears the environment and turns the update check off. +The native `local postgres` runtime fetches PostgreSQL builds from one base URL: `manifest.json` and, next to it, the tarballs it names by file, each with a `sha256` that is checked before extraction. `CLICKHOUSECTL_POSTGRES_BUNDLES_URL` replaces that base with another `https://` URL or with a `file:///absolute/directory`, for tests and for trying a build before it is published. Requests to it carry no credentials. The manifest has `"schema": 1` and a `bundles` array of `{postgres_version, postgres_major, extensions, target, file, sha256}`; targets are `aarch64-apple-darwin`, `x86_64-apple-darwin`, `aarch64-unknown-linux-musl` and `x86_64-unknown-linux-musl`. A tarball holds one top-level directory, named as the file without `.tar.gz`, with `bin/`, `lib/` and `share/`. + Structural help tests check the full command tree, descriptions, shared flags, and agent context limits. CI runs them with default features only, so run the second command yourself when a change depends on telemetry or feedback being compiled out: ```bash diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md index 9c79a70ca..fc1e65ef5 100644 --- a/docs/guides/local-development.md +++ b/docs/guides/local-development.md @@ -163,7 +163,7 @@ Each start copies the files into `.clickhouse/servers//data/config.d/` (as ## Add Postgres -Docker must be running. Postgres 17 and 18, including image sub-tags, are supported; new instances default to 18. A random password is generated unless supplied. +`local postgres` runs PostgreSQL natively, without Docker. The first start of a version downloads a prebuilt PostgreSQL that includes the [pg_clickhouse](https://github.com/ClickHouse/pg_clickhouse) extension, verifies its SHA-256 checksum, and keeps it in `~/.clickhouse/postgres/`; later starts reuse it and work offline. Builds exist for macOS and Linux on x86_64 and arm64. Postgres 17 and 18 are supported, as a major (`18`) or a `.` version; new instances default to 18. A random password is generated unless supplied. ```bash clickhousectl local postgres start app --version 18 @@ -178,9 +178,33 @@ Each engine's `list` and `stop-all` cover only that engine. `local status` lists Create `pg-schema.sql` with your Postgres SQL before running the file example. File and piped stdin input stop at the first failed statement and exit 3; pass `-- -v ON_ERROR_STOP=0` to run the remaining statements. -Starts wait for `pg_isready`, by default for 60 seconds; `--wait-timeout` accepts 1–600 seconds. `local postgres client` uses host `psql` or the container's `psql`. File input and stdin work with either, but paths inside SQL (`\i`, `\copy`) refer to the container filesystem in Docker mode. `--json` does not change psql output. When both are supplied, `--query` runs before `--queries-file`. +Starts wait for `pg_isready`, by default for 60 seconds; `--wait-timeout` accepts 1–600 seconds. `local postgres client` runs the `psql` that ships with the instance's PostgreSQL build. `--json` does not change psql output. When both are supplied, `--query` runs before `--queries-file`. -An instance is identified by name and major version. The name becomes part of the Docker container name, `clickhousectl-pg---`, so it may use only letters, digits, `_`, `.`, and `-`. The short project hash lets different projects use the same instance name; containers created before it was added keep their old name. Pass `--version` when more than one major shares a name. Resuming an instance reuses its original port, user, password, database, and environment; new creation flags do not reconfigure it. If another process now holds that port, the resume fails with `port_in_use` instead of starting without it; free the port and start again. Every start also confirms Docker published the port, and stops the container if it did not. To recreate, first back up any needed data, then stop and remove the instance before starting again. Direct `--host`/`--port` client selectors cannot combine with managed name/version selectors. +An instance listens on `127.0.0.1` only, with password (SCRAM) authentication, UTF-8 encoding and the builtin `C.UTF-8` locale on every platform. Its data, log (`postgres.log`) and connection details live in `.clickhouse/servers/-pg/`. `local install postgres@18` downloads a build ahead of the first start. PostgreSQL does not run as root, so `local postgres start` refuses to as well; use a regular user, or `--docker`. + +An instance is identified by name and major version; the name may use only letters, digits, `_`, `.`, and `-`. Pass `--version` when more than one major shares a name. Resuming an instance reuses its original port, user, password, and database; new creation flags do not reconfigure it. A resume uses the newest installed build of the instance's major, since a data directory works across minor versions. If another process now holds the stored port, the resume fails with `port_in_use` instead of starting without it; free the port and start again. To recreate, first back up any needed data, then remove the instance before starting again. Direct `--host`/`--port` client selectors cannot combine with managed name/version selectors. + +### Query local ClickHouse from Postgres + +With a local ClickHouse server running (HTTP port 8123 here), pg_clickhouse exposes its tables to Postgres as foreign tables: + +```bash +clickhousectl local clickhouse start dev +clickhousectl local client dev --query "CREATE TABLE default.events (id UInt64, name String) ENGINE = MergeTree ORDER BY id" +clickhousectl local postgres client app --query "CREATE EXTENSION pg_clickhouse" +clickhousectl local postgres client app --query "CREATE SERVER local_ch FOREIGN DATA WRAPPER clickhouse_fdw OPTIONS (driver 'http', host '127.0.0.1', port '8123', dbname 'default')" +clickhousectl local postgres client app --query "CREATE USER MAPPING FOR CURRENT_USER SERVER local_ch OPTIONS (user 'default')" +clickhousectl local postgres client app --query "CREATE FOREIGN TABLE events (id bigint, name text) SERVER local_ch OPTIONS (table_name 'events')" +clickhousectl local postgres client app --query "SELECT count(*) FROM events" +``` + +### Run Postgres in Docker instead + +`local postgres start --docker` runs a `postgres` image in a container instead, and needs Docker running. It accepts any 17 or 18 image tag (`--version 17-alpine`, `18-bookworm`) and container environment variables (`--env KEY=VALUE`); both are usage errors (exit 2) without `--docker`. The image does not include pg_clickhouse. `local install postgres@ --docker` pulls an image ahead of time. + +An instance keeps the runtime it was created with. Instances created by earlier versions of clickhousectl are Docker instances: they resume in Docker without the flag, and every other command works on them unchanged. `--docker` on an existing native instance is a usage error; remove the instance to recreate it in the other runtime. + +For a Docker instance, `local postgres client` uses host `psql` or the container's `psql`. File input and stdin work with either, but paths inside SQL (`\i`, `\copy`) refer to the container filesystem. The instance name becomes part of the container name, `clickhousectl-pg---`. The short project hash lets different projects use the same instance name; containers created before it was added keep their old name. A resume also reuses the container's environment, and every start confirms Docker published the port, stopping the container if it did not. The generated `.env.local` includes the password. Keep it out of version control. Both engines' `dotenv` commands write a file and print an informational preview: use your application's dotenv loader, never `eval` their stdout. @@ -195,16 +219,16 @@ clickhousectl local clickhouse stop dev clickhousectl local postgres stop app --version 18 ``` -Stop preserves data. Stopping a server or instance that exists but is not running succeeds and reports `already_stopped: true`; an unknown name is an error. **The following removals permanently delete the selected server's data**, including Postgres container volumes: +Stop preserves data. Stopping a server or instance that exists but is not running succeeds and reports `already_stopped: true`; an unknown name is an error. **The following removals permanently delete the selected server's data**, including a Postgres instance's data directory and, in Docker, its container: ```bash clickhousectl local clickhouse remove dev clickhousectl local postgres remove app --version 18 ``` -Both require stopped servers. `local clickhouse stop-all` and `local postgres stop-all` each stop one engine's servers in the current project. Global ClickHouse operations (`clickhouse list --global`, `stop --global`, `stop-all --global`) span projects; confirm the project and name before stopping one. `stop --global --project ` disambiguates matching names. +`clickhouse remove` and `postgres remove` of a Docker instance require a stopped server; `postgres remove` stops a running native instance first. `local clickhouse stop-all` and `local postgres stop-all` each stop one engine's servers in the current project. Global ClickHouse operations (`clickhouse list --global`, `stop --global`, `stop-all --global`) span projects; confirm the project and name before stopping one. `stop --global --project ` disambiguates matching names. `local remove ` removes a shared ClickHouse binary, not server data. It refuses a default or a version used by running servers in any project, and refuses when the running processes cannot be read, since then other projects' servers are unknown. Its `--force` stops those servers across projects and removes the version even if it is the default; after a failed process scan it stops only this project's servers. -If metadata is corrupt, follow the reported recovery guidance. Confirm the running process with `clickhouse list --global`, or the Postgres container with Docker, before moving metadata aside. Do not delete state or force-remove an unverified server. A Docker inspection failure is an error, not evidence that Postgres is stopped. +If metadata is corrupt, follow the reported recovery guidance. Confirm the running process with `clickhouse list --global`, or the Postgres container with Docker (for a native instance, the `postgres` process running from its `data/` directory), before moving metadata aside. Do not delete state or force-remove an unverified server. A Docker inspection failure is an error, not evidence that Postgres is stopped. diff --git a/docs/reference/automation.md b/docs/reference/automation.md index 2a750250e..f65dd2ff5 100644 --- a/docs/reference/automation.md +++ b/docs/reference/automation.md @@ -187,11 +187,13 @@ Every command except `update`, `--version` included, checks for a newer release | `version_unavailable` | The requested version could not be resolved or downloaded | | `version_is_default` | The version is the current default and `--force` was not passed | | `unsupported_client_version` | The installed client does not support the requested operation | -| `unsupported_platform` | No ClickHouse build exists for this OS and architecture | +| `unsupported_platform` | No ClickHouse or PostgreSQL build exists for this OS and architecture | | `port_in_use` | A requested or stored port is occupied, Docker did not publish it, or no managed port is available | | `startup_exit` | A managed server exited before it became ready | | `startup_timeout` | A managed server did not become ready before its deadline | | `download_failed` | An artifact or image download or extraction failed | +| `postgres_bundle_unavailable` | No PostgreSQL build can be used for `local postgres`: none is published for the requested version on this platform, none is installed for an instance's major, or the build manifest is not readable by this version | +| `checksum_mismatch` | A downloaded PostgreSQL build did not match its published SHA-256; nothing was installed | | `network_error` | An HTTP request failed | | `docker_unavailable` | Docker could not be reached (the message names the cause and the platform fix) | | `docker_error` | A Docker operation failed | From 8477bad93f69822c6871a7fd2c3a8ca4e5252ff7 Mon Sep 17 00:00:00 2001 From: sdairs Date: Mon, 16 Nov 2026 20:22:50 +0000 Subject: [PATCH 4/5] feat(local): run native Postgres as an unprivileged user under root, sysv shared memory on Linux (#1464) - As root, initdb and the postmaster drop to `postgres`, else `nobody` (chdir /, setgroups, setgid, setuid before exec); no user is created and the instance directory is chowned to that user. Credentials stay root-only. - The server user must be able to enter every directory on the way to the bundle cache and the instance; otherwise the start fails first with postgres_directory_not_searchable, naming the directory. Nothing is chmodded. - An existing instance runs as the owner of its data directory, so root can start a user's instance; rewritten metadata keeps its owner. - Liveness also accepts a postmaster started on the data directory (-D), for root in a container that cannot read another user's cwd. - Linux: dynamic_shared_memory_type=sysv for initdb and the server, so a small /dev/shm does not fail bootstrap or parallel queries. macOS keeps posix. Co-Authored-By: Claude Fable 5.2 --- crates/clickhousectl/src/error.rs | 10 + crates/clickhousectl/src/local/mod.rs | 1 - crates/clickhousectl/src/local/output.rs | 8 + crates/clickhousectl/src/local/pg_bundle.rs | 3 +- crates/clickhousectl/src/local/pg_native.rs | 443 ++++++++++++++++++-- crates/clickhousectl/src/local/postgres.rs | 31 +- crates/clickhousectl/src/local/server.rs | 18 +- 7 files changed, 480 insertions(+), 34 deletions(-) diff --git a/crates/clickhousectl/src/error.rs b/crates/clickhousectl/src/error.rs index f03c0d367..785cb78ec 100644 --- a/crates/clickhousectl/src/error.rs +++ b/crates/clickhousectl/src/error.rs @@ -656,6 +656,16 @@ pub enum Error { actual: String, }, + /// Run as root, native Postgres runs as an unprivileged user, and that + /// user cannot enter `dir`, which lies on the way to the PostgreSQL build + /// or to the instance. Nothing was started or created. + #[error( + "PostgreSQL cannot run as root, so it runs as user '{user}', who cannot enter '{dir}'. \ + Use a project directory and HOME outside '{dir}', run `chmod o+x {dir}`, or pass `--docker`.", + dir = dir.display() + )] + PostgresServerUserAccess { user: String, dir: PathBuf }, + /// A child process whose status must be returned unchanged. This is /// intentionally not printed as a clickhousectl error by `run_parsed`. #[error("child process exited with code {0}")] diff --git a/crates/clickhousectl/src/local/mod.rs b/crates/clickhousectl/src/local/mod.rs index 61645966a..7c7e57bae 100644 --- a/crates/clickhousectl/src/local/mod.rs +++ b/crates/clickhousectl/src/local/mod.rs @@ -101,7 +101,6 @@ async fn install_postgres(tag: &str, force: bool, docker: bool, json: bool) -> R ), )); }; - pg_native::reject_root()?; let bundle = pg_bundle::ensure_bundle(&request, force, json).await?; let out = output::InstallOutput { version: format!("postgres@{}", bundle.spec.postgres_version), diff --git a/crates/clickhousectl/src/local/output.rs b/crates/clickhousectl/src/local/output.rs index 4fc00bc93..8f6533cc3 100644 --- a/crates/clickhousectl/src/local/output.rs +++ b/crates/clickhousectl/src/local/output.rs @@ -99,6 +99,9 @@ pub(crate) enum LocalErrorCode { PostgresBundleUnavailable, /// A downloaded Postgres bundle did not match its manifest sha256. ChecksumMismatch, + /// Run as root, the unprivileged user that runs native Postgres cannot + /// enter a directory on the way to the build or the instance. + PostgresDirectoryNotSearchable, SqlInputOpenFailed, SqlInputReadFailed, /// A managed server metadata file contains invalid JSON. The structured @@ -160,6 +163,7 @@ impl LocalErrorCode { Self::PostgresError => "postgres_error", Self::PostgresBundleUnavailable => "postgres_bundle_unavailable", Self::ChecksumMismatch => "checksum_mismatch", + Self::PostgresDirectoryNotSearchable => "postgres_directory_not_searchable", Self::SqlInputOpenFailed => "sql_input_open_failed", Self::SqlInputReadFailed => "sql_input_read_failed", Self::ServerMetadataInvalid => "server_metadata_invalid", @@ -773,6 +777,10 @@ impl LocalErrorBody { Mapping::parity(LocalErrorCode::PostgresBundleUnavailable) .command("clickhousectl local postgres start --help") } + // Self-composed: the account and the directory it cannot enter. + Error::PostgresServerUserAccess { .. } => { + Mapping::parity(LocalErrorCode::PostgresDirectoryNotSearchable) + } // Bundle name and digests only, all from the manifest and file. Error::PostgresBundleChecksum { .. } => { Mapping::parity(LocalErrorCode::ChecksumMismatch) diff --git a/crates/clickhousectl/src/local/pg_bundle.rs b/crates/clickhousectl/src/local/pg_bundle.rs index 421faf951..bf3613a4b 100644 --- a/crates/clickhousectl/src/local/pg_bundle.rs +++ b/crates/clickhousectl/src/local/pg_bundle.rs @@ -171,7 +171,8 @@ pub(crate) fn target_triple(platform: Platform) -> &'static str { } } -fn cache_root() -> Result { +/// Where extracted bundles are kept. +pub(crate) fn cache_root() -> Result { Ok(paths::base_dir()?.join("postgres")) } diff --git a/crates/clickhousectl/src/local/pg_native.rs b/crates/clickhousectl/src/local/pg_native.rs index 9bd6f1213..cf9eb488f 100644 --- a/crates/clickhousectl/src/local/pg_native.rs +++ b/crates/clickhousectl/src/local/pg_native.rs @@ -23,6 +23,19 @@ const LOG_FILE: &str = "postgres.log"; const SOCKET_DIR: &str = "run"; const LISTEN_ADDRESS: &str = "127.0.0.1"; +/// The server setting for dynamic shared memory, which `initdb`'s bootstrap +/// and parallel queries allocate. On Linux the default, +/// POSIX, puts it in `/dev/shm`, which a container caps at 64 MiB unless told +/// otherwise, and a large parallel query then fails; System V segments have +/// no such mount behind them. macOS keeps its default: it has no `/dev/shm` +/// to run out of, and its System V limits (4 MiB a segment) are the small +/// ones there. +const SHARED_MEMORY_SETTING: Option<&str> = if cfg!(target_os = "linux") { + Some("dynamic_shared_memory_type=sysv") +} else { + None +}; + const READINESS_POLL_INTERVAL: Duration = Duration::from_millis(200); /// Bounds one `pg_isready` run, which is told to give up after a second. const PROBE_TIMEOUT: Duration = Duration::from_secs(5); @@ -83,6 +96,7 @@ pub(crate) fn save_state(instance_dir: &Path, state: &NativeState) -> Result<()> .open(&staged)?; file.write_all(&serde_json::to_vec_pretty(state)?)?; file.sync_all()?; + server::keep_owner(&path, &staged); std::fs::rename(&staged, &path) }; write().map_err(|error| { @@ -91,23 +105,235 @@ pub(crate) fn save_state(instance_dir: &Path, state: &NativeState) -> Result<()> }) } -/// Postgres refuses to run as root, and a bundle downloaded as root would be -/// unusable by the user afterwards, so this fails before any download. -/// Dropping privileges instead is being looked at in issue #1464. -pub(crate) fn reject_root() -> Result<()> { +/// The account `initdb` and the postmaster run as when this CLI is root. +/// +/// PostgreSQL refuses to run as root, so a root invocation drops to an +/// unprivileged account for those two programs (issue #1464). Everything +/// else, the client tools included, keeps running as the caller. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerUser { + pub uid: u32, + pub gid: u32, + pub name: String, +} + +/// Accounts tried for a new instance, in order. Nothing is ever created: +/// `nobody` exists on every system this was tried on. +const SERVER_USER_CANDIDATES: [&str; 2] = ["postgres", "nobody"]; + +fn effective_uid() -> u32 { // SAFETY: `geteuid` takes no arguments and cannot fail. - reject_root_euid(unsafe { libc::geteuid() }) + unsafe { libc::geteuid() } +} + +/// Read one passwd entry with `lookup`, which wraps `getpwnam_r` or +/// `getpwuid_r`. +fn passwd_entry( + lookup: impl Fn( + *mut libc::passwd, + *mut libc::c_char, + libc::size_t, + *mut *mut libc::passwd, + ) -> libc::c_int, +) -> Option { + let mut buffer = vec![0 as libc::c_char; 16 * 1024]; + // SAFETY: `passwd` is plain data; all-zero is a valid value to fill in. + let mut entry: libc::passwd = unsafe { std::mem::zeroed() }; + let mut found: *mut libc::passwd = std::ptr::null_mut(); + if lookup(&mut entry, buffer.as_mut_ptr(), buffer.len(), &mut found) != 0 || found.is_null() { + return None; + } + // SAFETY: on success `pw_name` points at a NUL-terminated string inside + // `buffer`, which is still alive. + let name = unsafe { std::ffi::CStr::from_ptr(entry.pw_name) } + .to_string_lossy() + .into_owned(); + Some(ServerUser { + uid: entry.pw_uid, + gid: entry.pw_gid, + name, + }) +} + +fn passwd_by_name(name: &str) -> Option { + let name = std::ffi::CString::new(name).ok()?; + // SAFETY: every pointer is valid for the call and `name` is NUL-terminated. + passwd_entry(|entry, buffer, len, found| unsafe { + libc::getpwnam_r(name.as_ptr(), entry, buffer, len, found) + }) +} + +fn passwd_by_uid(uid: u32) -> Option { + // SAFETY: every pointer is valid for the call. + passwd_entry(|entry, buffer, len, found| unsafe { + libc::getpwuid_r(uid, entry, buffer, len, found) + }) +} + +/// The first candidate account that exists and is not itself root. +fn select_server_user(lookup: impl Fn(&str) -> Option) -> Option { + SERVER_USER_CANDIDATES + .iter() + .filter_map(|name| lookup(name)) + .find(|user| user.uid != 0) +} + +/// Who runs a new instance: `None` for the caller, or for root the +/// `postgres` account if there is one, else `nobody`. +pub(crate) fn user_for_new_instance() -> Result> { + if effective_uid() != 0 { + return Ok(None); + } + select_server_user(passwd_by_name).map(Some).ok_or_else(|| { + Error::PostgresUsage( + "PostgreSQL cannot run as root, and this system has neither a `postgres` nor a \ + `nobody` user to run it as. Run as a regular user, or pass `--docker`." + .to_string(), + ) + }) } -fn reject_root_euid(euid: u32) -> Result<()> { +/// Who may run an instance whose data directory `owner` owns: PostgreSQL +/// only starts as that owner. A regular user must be the owner; root runs +/// the postmaster as the owner, whoever created the instance. +fn resolve_existing_user( + euid: u32, + owner: u32, + lookup: impl Fn(u32) -> Option, +) -> std::result::Result, String> { if euid != 0 { - return Ok(()); + return if owner == euid { + Ok(None) + } else { + Err(format!( + "its data belongs to another user (uid {owner}); start it as that user or as root" + )) + }; + } + if owner == 0 { + return Err("its data directory is owned by root, which PostgreSQL cannot run as".into()); + } + lookup(owner) + .map(Some) + .ok_or_else(|| format!("its data belongs to uid {owner}, which has no passwd entry")) +} + +/// Who runs an existing instance; see [`resolve_existing_user`]. An instance +/// with no data directory resolves to the caller, and the start then reports +/// the missing data. +pub(crate) fn user_for_existing_instance( + instance_dir: &Path, + name: &str, +) -> Result> { + use std::os::unix::fs::MetadataExt; + let Ok(metadata) = std::fs::metadata(data_dir(instance_dir)) else { + return Ok(None); + }; + resolve_existing_user(effective_uid(), metadata.uid(), passwd_by_uid).map_err(|reason| { + Error::PostgresUsage(format!( + "Postgres server '{name}' cannot be started: {reason}" + )) + }) +} + +/// Owner, group and permission bits of a directory. +struct DirAccess { + uid: u32, + gid: u32, + mode: u32, +} + +fn can_search(access: &DirAccess, user: &ServerUser) -> bool { + let bit = if access.uid == user.uid { + 0o100 + } else if access.gid == user.gid { + 0o010 + } else { + 0o001 + }; + access.mode & bit != 0 +} + +/// The outermost existing directory on the way to `path`, `path` included, +/// that `user` cannot enter. Directories that do not exist yet are skipped: +/// this CLI creates them. +fn first_unsearchable( + path: &Path, + user: &ServerUser, + stat: &impl Fn(&Path) -> Option, +) -> Option { + let mut ancestors: Vec<&Path> = path.ancestors().collect(); + ancestors.reverse(); + ancestors + .into_iter() + .find(|dir| stat(dir).is_some_and(|access| !can_search(&access, user))) + .map(Path::to_path_buf) +} + +/// Fail unless `user` can reach every one of `paths`: the bundle it executes +/// and the instance it writes. Nothing is chmodded to make it so; the +/// directories on the way belong to the caller. +pub(crate) fn ensure_searchable(paths: &[&Path], user: &ServerUser) -> Result<()> { + use std::os::unix::fs::MetadataExt; + let stat = |dir: &Path| { + std::fs::metadata(dir).ok().map(|metadata| DirAccess { + uid: metadata.uid(), + gid: metadata.gid(), + mode: metadata.mode(), + }) + }; + match paths + .iter() + .find_map(|path| first_unsearchable(path, user, &stat)) + { + Some(dir) => Err(Error::PostgresServerUserAccess { + user: user.name.clone(), + dir, + }), + None => Ok(()), + } +} + +/// Hand `paths` to `user`, who must own what the postmaster writes. +fn give_to(user: &ServerUser, paths: &[&Path]) -> Result<()> { + for path in paths { + std::os::unix::fs::chown(path, Some(user.uid), Some(user.gid))?; + } + Ok(()) +} + +/// Create the instance and data directories, owned by `run_as` when set. +pub(crate) fn create_instance_dirs(instance_dir: &Path, run_as: Option<&ServerUser>) -> Result<()> { + let data = data_dir(instance_dir); + std::fs::create_dir_all(&data)?; + match run_as { + Some(user) => give_to(user, &[instance_dir, &data]), + None => Ok(()), + } +} + +/// The step between fork and exec that turns a root child into `user`: leave +/// the caller's working directory, which `user` may not be able to enter, +/// then drop supplementary groups, group and user, in that order. +fn drop_privileges( + user: &ServerUser, +) -> impl FnMut() -> std::io::Result<()> + Send + Sync + 'static { + let (uid, gid) = (user.uid, user.gid); + move || { + // SAFETY: only async-signal-safe calls, on plain integers and a + // static string. + let dropped = unsafe { + libc::chdir(c"/".as_ptr()) == 0 + && libc::setgroups(1, &gid) == 0 + && libc::setgid(gid) == 0 + && libc::setuid(uid) == 0 + }; + if dropped { + Ok(()) + } else { + Err(std::io::Error::last_os_error()) + } } - Err(Error::usage( - clap::error::ErrorKind::InvalidValue, - "PostgreSQL cannot run as root. Run `clickhousectl local postgres start` as a \ - regular user, or pass `--docker` to run Postgres in a container.", - )) } fn data_dir(instance_dir: &Path) -> PathBuf { @@ -122,13 +348,30 @@ pub(crate) fn is_initialized(instance_dir: &Path) -> bool { /// The running postmaster of an instance, if any. /// /// `postmaster.pid` survives a crash and its PID can be reused, so the PID -/// counts only while that process still runs from the data directory, which -/// a postmaster makes its working directory. +/// counts only while that process is still this instance's postmaster: it +/// runs from the data directory, which a postmaster makes its working +/// directory, or it was started on it (`-D `). The second test is for +/// root in a container, which may signal a postmaster running as another +/// user but not read its working directory. pub(crate) fn running_pid(instance_dir: &Path) -> Option { let data = data_dir(instance_dir); let pid_file = std::fs::read_to_string(data.join("postmaster.pid")).ok()?; let pid: u32 = pid_file.lines().next()?.trim().parse().ok()?; - server::is_server_process(pid, &data).then_some(pid) + let ours = server::is_server_process(pid, &data) + || (server::is_process_alive(pid) + && super::procinfo::process_args(pid) + .is_ok_and(|args| started_on_data_dir(&args, &data))); + ours.then_some(pid) +} + +/// Whether `args`, a process's command line, start a server on `data`. +fn started_on_data_dir(args: &[String], data: &Path) -> bool { + let Ok(data) = std::fs::canonicalize(data) else { + return false; + }; + args.windows(2).any(|pair| { + pair[0] == "-D" && std::fs::canonicalize(&pair[1]).is_ok_and(|path| path == data) + }) } pub(crate) fn is_running(instance_dir: &Path) -> bool { @@ -230,6 +473,8 @@ pub(crate) struct InitOptions<'a> { pub name: &'a str, pub user: &'a str, pub password: &'a str, + /// The account to run as, when the caller is root. + pub run_as: Option<&'a ServerUser>, } /// Initialize the data directory. The password reaches `initdb` through a @@ -244,10 +489,19 @@ pub(crate) async fn initdb(options: &InitOptions<'_>) -> Result<()> { .tempfile_in(options.instance_dir)?; writeln!(pwfile, "{}", options.password)?; pwfile.flush()?; + if let Some(user) = options.run_as { + // Still readable by one account only: the one initdb runs as. + give_to(user, &[pwfile.path()])?; + } let mut pwfile_arg = std::ffi::OsString::from("--pwfile="); pwfile_arg.push(pwfile.path()); - let output = tokio::process::Command::new(options.bundle.bin("initdb")) + let mut command = tokio::process::Command::new(options.bundle.bin("initdb")); + if let Some(user) = options.run_as { + // SAFETY: the closure makes only async-signal-safe calls. + unsafe { command.pre_exec(drop_privileges(user)) }; + } + let output = command .arg("-D") .arg(data_dir(options.instance_dir)) .arg("-U") @@ -262,6 +516,13 @@ pub(crate) async fn initdb(options: &InitOptions<'_>) -> Result<()> { "--no-locale", "--no-instructions", ]) + // initdb runs a server to bootstrap, which allocates shared memory + // too, and it records the setting in postgresql.conf. + .args( + SHARED_MEMORY_SETTING + .iter() + .flat_map(|setting| ["-c", setting]), + ) .stdin(Stdio::null()) .output() .await @@ -288,6 +549,7 @@ pub(crate) fn spawn_postmaster( bundle: &InstalledBundle, instance_dir: &Path, port: u16, + run_as: Option<&ServerUser>, ) -> Result { let log = std::fs::OpenOptions::new() .create(true) @@ -296,12 +558,16 @@ pub(crate) fn spawn_postmaster( let socket_dir = socket_dir(instance_dir); if let Some(dir) = &socket_dir { std::fs::create_dir_all(dir)?; + if let Some(user) = run_as { + give_to(user, &[dir])?; + } } let mut socket_setting = std::ffi::OsString::from("unix_socket_directories="); if let Some(dir) = &socket_dir { socket_setting.push(dir); } - std::process::Command::new(bundle.bin("postgres")) + let mut command = std::process::Command::new(bundle.bin("postgres")); + command .arg("-D") .arg(data_dir(instance_dir)) .arg("-p") @@ -309,7 +575,15 @@ pub(crate) fn spawn_postmaster( .arg("-c") .arg(format!("listen_addresses={LISTEN_ADDRESS}")) .arg("-c") - .arg(socket_setting) + .arg(socket_setting); + if let Some(setting) = SHARED_MEMORY_SETTING { + command.arg("-c").arg(setting); + } + if let Some(user) = run_as { + // SAFETY: the closure makes only async-signal-safe calls. + unsafe { command.pre_exec(drop_privileges(user)) }; + } + command .stdin(Stdio::null()) .stdout(log.try_clone()?) .stderr(log) @@ -425,14 +699,104 @@ mod tests { use super::*; use std::os::unix::fs::PermissionsExt; + fn user(name: &str, uid: u32, gid: u32) -> ServerUser { + ServerUser { + uid, + gid, + name: name.to_string(), + } + } + + #[test] + fn root_runs_new_instances_as_postgres_else_nobody_and_never_as_root() { + let nobody = user("nobody", 65534, 65534); + let postgres = user("postgres", 105, 110); + let passwd = |entries: Vec| { + move |name: &str| entries.iter().find(|entry| entry.name == name).cloned() + }; + assert_eq!( + select_server_user(passwd(vec![nobody.clone(), postgres.clone()])), + Some(postgres) + ); + assert_eq!( + select_server_user(passwd(vec![nobody.clone()])), + Some(nobody.clone()) + ); + // An entry that is root under another name is no use. + assert_eq!( + select_server_user(passwd(vec![user("postgres", 0, 0), nobody.clone()])), + Some(nobody) + ); + assert_eq!(select_server_user(passwd(vec![])), None); + } + #[test] - fn root_is_refused_as_a_usage_error_and_other_users_pass() { - assert!(reject_root_euid(501).is_ok()); - let error = reject_root_euid(0).unwrap_err(); - assert!(matches!(error, Error::Usage(_))); - assert_eq!(error.exit_code(), 2); - // The way out is the Docker runtime. - assert!(error.to_string().contains("--docker")); + fn an_existing_instance_runs_as_the_owner_of_its_data() { + let owner = user("al", 501, 20); + let lookup = |uid: u32| (uid == 501).then(|| owner.clone()); + // The owner starts it as themselves; root starts it as the owner. + assert_eq!(resolve_existing_user(501, 501, lookup), Ok(None)); + assert_eq!( + resolve_existing_user(0, 501, lookup), + Ok(Some(owner.clone())) + ); + // Anyone else cannot, and neither can root for data it cannot map to + // an account or that root itself owns. + assert!(resolve_existing_user(502, 501, lookup).is_err()); + assert!(resolve_existing_user(501, 65534, lookup).is_err()); + assert!(resolve_existing_user(0, 4242, lookup).is_err()); + assert!(resolve_existing_user(0, 0, lookup).is_err()); + } + + #[test] + fn the_outermost_directory_the_server_user_cannot_enter_is_reported() { + let nobody = user("nobody", 65534, 65534); + let tree = |entries: &'static [(&'static str, u32, u32, u32)]| { + move |dir: &Path| { + entries + .iter() + .find(|(path, ..)| Path::new(path) == dir) + .map(|&(_, uid, gid, mode)| DirAccess { uid, gid, mode }) + } + }; + let blocked = |path: &str, stat: &dyn Fn(&Path) -> Option| { + first_unsearchable(Path::new(path), &nobody, &|dir| stat(dir)) + }; + + // Root's home is closed to others; a project elsewhere is not. + let home = tree(&[ + ("/", 0, 0, 0o755), + ("/root", 0, 0, 0o700), + ("/root/.clickhouse", 0, 0, 0o755), + ("/srv", 0, 0, 0o755), + ("/srv/app", 0, 0, 0o755), + ]); + assert_eq!( + blocked("/root/.clickhouse/postgres/pg-18", &home), + Some(PathBuf::from("/root")) + ); + // Directories that do not exist yet are not an obstacle. + assert_eq!(blocked("/srv/app/.clickhouse/servers/a-pg18", &home), None); + + // The class that applies decides: owner bits for the owner, group + // bits for the group, other bits for everyone else. + let classes = tree(&[ + ("/", 0, 0, 0o755), + ("/owned", 65534, 0, 0o700), + ("/owned-closed", 65534, 0, 0o077), + ("/grouped", 0, 65534, 0o750), + ("/grouped-closed", 0, 65534, 0o705), + ("/other-closed", 0, 0, 0o770), + ]); + assert_eq!(blocked("/owned/x", &classes), None); + assert_eq!(blocked("/grouped/x", &classes), None); + for dir in ["/owned-closed", "/grouped-closed", "/other-closed"] { + assert_eq!( + blocked(&format!("{dir}/x"), &classes), + Some(PathBuf::from(dir)), + "{dir}" + ); + } } #[test] @@ -478,6 +842,35 @@ mod tests { assert!(!socket_path_fits(&over, 104)); } + #[test] + fn a_command_line_identifies_the_postmaster_of_a_data_directory() { + let dir = tempfile::tempdir().unwrap(); + let data = dir.path().join("data"); + let other = dir.path().join("other"); + std::fs::create_dir_all(&data).unwrap(); + std::fs::create_dir_all(&other).unwrap(); + let args = |data_arg: &Path| -> Vec { + [ + "/bundle/bin/postgres", + "-D", + data_arg.to_str().unwrap(), + "-p", + "5432", + ] + .map(String::from) + .to_vec() + }; + assert!(started_on_data_dir(&args(&data), &data)); + // Another instance's postmaster, or a process that only mentions + // the path, is not this one. + assert!(!started_on_data_dir(&args(&other), &data)); + assert!(!started_on_data_dir( + &["sleep".to_string(), data.display().to_string()], + &data + )); + assert!(!started_on_data_dir(&[], &data)); + } + #[test] fn a_stale_pid_file_does_not_make_an_instance_running() { let dir = tempfile::tempdir().unwrap(); diff --git a/crates/clickhousectl/src/local/postgres.rs b/crates/clickhousectl/src/local/postgres.rs index 6ea21ea7e..e227eb887 100644 --- a/crates/clickhousectl/src/local/postgres.rs +++ b/crates/clickhousectl/src/local/postgres.rs @@ -656,7 +656,6 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { wait_timeout, .. } = request; - pg_native::reject_root()?; if let Some(password) = &password { validate_native_password(password)?; } @@ -678,6 +677,18 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { return Err(runtime_changed(&user_name)); } + // As root, PostgreSQL runs as an unprivileged account. Find out + // which, and that it can reach its files, before anything is + // downloaded or created. + let instance_dir = server::servers_dir_join(&key)?; + let run_as = match &prior { + Some(_) => pg_native::user_for_existing_instance(&instance_dir, &user_name)?, + None => pg_native::user_for_new_instance()?, + }; + if let Some(server_user) = &run_as { + pg_native::ensure_searchable(&[&pg_bundle::cache_root()?, &instance_dir], server_user)?; + } + let bundle = match &prior { // Data directories work across minors of a major, so an existing // instance takes the newest installed bundle and needs no network. @@ -693,6 +704,10 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { } }; + if let Some(server_user) = &run_as { + pg_native::ensure_searchable(&[&bundle.dir], server_user)?; + } + let metadata_lock = server::lock_metadata()?; let (current_tag, current_major) = resolve_pg_start_version_locked(&user_name, version.as_deref(), &metadata_lock)?; @@ -703,6 +718,7 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { continue; } crate::init::ensure_runtime_gitignore()?; + let run_as = run_as.as_ref(); let started = match prior { Some(prior) => { @@ -718,7 +734,7 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { over." ); } - resume_native(prior, &bundle, wait_timeout, metadata_lock).await? + resume_native(prior, &bundle, run_as, wait_timeout, metadata_lock).await? } None => { let host_port = match preflight.host_port { @@ -744,7 +760,7 @@ async fn start_native(request: StartRequest, json: bool) -> Result<()> { engine: Engine::Postgres, container_id: None, }; - create_native(info, state, &bundle, wait_timeout, metadata_lock).await? + create_native(info, state, &bundle, run_as, wait_timeout, metadata_lock).await? } }; @@ -779,6 +795,7 @@ async fn create_native( mut info: ServerInfo, state: NativeState, bundle: &InstalledBundle, + run_as: Option<&pg_native::ServerUser>, wait_timeout: Duration, metadata_lock: server::MetadataLock, ) -> Result { @@ -792,19 +809,20 @@ async fn create_native( instance_dir.display() ))); } - std::fs::create_dir_all(instance_dir.join("data"))?; let spawned = async { + pg_native::create_instance_dirs(&instance_dir, run_as)?; pg_native::initdb(&pg_native::InitOptions { bundle, instance_dir: &instance_dir, name: &display_name, user: &state.user, password: &state.password, + run_as, }) .await?; pg_native::save_state(&instance_dir, &state)?; - pg_native::spawn_postmaster(bundle, &instance_dir, info.tcp_port) + pg_native::spawn_postmaster(bundle, &instance_dir, info.tcp_port, run_as) } .await; let mut child = match spawned { @@ -930,6 +948,7 @@ fn rollback_native_create( async fn resume_native( prior: ServerInfo, bundle: &InstalledBundle, + run_as: Option<&pg_native::ServerUser>, wait_timeout: Duration, metadata_lock: server::MetadataLock, ) -> Result { @@ -950,7 +969,7 @@ async fn resume_native( })?; ensure_resume_port_free(&display_name, prior.tcp_port)?; - let mut child = pg_native::spawn_postmaster(bundle, &instance_dir, prior.tcp_port)?; + let mut child = pg_native::spawn_postmaster(bundle, &instance_dir, prior.tcp_port, run_as)?; let stopped = ServerInfo { pid: 0, ..prior.clone() diff --git a/crates/clickhousectl/src/local/server.rs b/crates/clickhousectl/src/local/server.rs index b30ca7379..10921bec0 100644 --- a/crates/clickhousectl/src/local/server.rs +++ b/crates/clickhousectl/src/local/server.rs @@ -453,6 +453,7 @@ fn save_server_info_at_with_sync( .and_then(|()| temporary.flush()) .and_then(|()| temporary.as_file().sync_all()) .map_err(|error| metadata_write_error(&path, error))?; + keep_owner(&path, temporary.path()); temporary .persist(&path) .map_err(|error| metadata_write_error(&path, error.error))?; @@ -462,6 +463,21 @@ fn save_server_info_at_with_sync( Ok(()) } +/// Give `replacement` the owner of `existing`, the file it is about to +/// replace. Only root can and needs to: without this, root acting on a +/// user's project (`sudo clickhousectl ...`) would leave its owner-only +/// files unreadable to that user. Best effort, and a no-op for a new file or +/// one this user already owns. +pub(crate) fn keep_owner(existing: &Path, replacement: &Path) { + use std::os::unix::fs::MetadataExt; + if let (Ok(existing), Ok(replacement_meta)) = + (std::fs::metadata(existing), std::fs::metadata(replacement)) + && (existing.uid(), existing.gid()) != (replacement_meta.uid(), replacement_meta.gid()) + { + let _ = std::os::unix::fs::chown(replacement, Some(existing.uid()), Some(existing.gid())); + } +} + pub(crate) fn save_server_info_locked(info: &ServerInfo, lock: &MetadataLock) -> Result<()> { validate_server_name(&info.name)?; save_server_info_at(&lock.dir, info) @@ -917,7 +933,7 @@ pub(crate) fn is_server_process(pid: u32, data_dir: &Path) -> bool { std::fs::canonicalize(cwd).is_ok_and(|cwd| cwd == data_dir) } -fn is_process_alive(pid: u32) -> bool { +pub(crate) fn is_process_alive(pid: u32) -> bool { pid != 0 && i32::try_from(pid).is_ok_and(|pid| unsafe { libc::kill(pid, 0) == 0 }) } From b5d4dee837ffcf91a18f93182fd3a9becc55c8a2 Mon Sep 17 00:00:00 2001 From: sdairs Date: Mon, 16 Nov 2026 20:22:50 +0000 Subject: [PATCH 5/5] docs(local): running local Postgres as root and the Linux shared-memory setting (#1464) Co-Authored-By: Claude Fable 5.2 --- docs/guides/local-development.md | 10 +++++++++- docs/reference/automation.md | 1 + 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md index fc1e65ef5..c5c076477 100644 --- a/docs/guides/local-development.md +++ b/docs/guides/local-development.md @@ -180,10 +180,18 @@ Create `pg-schema.sql` with your Postgres SQL before running the file example. F Starts wait for `pg_isready`, by default for 60 seconds; `--wait-timeout` accepts 1–600 seconds. `local postgres client` runs the `psql` that ships with the instance's PostgreSQL build. `--json` does not change psql output. When both are supplied, `--query` runs before `--queries-file`. -An instance listens on `127.0.0.1` only, with password (SCRAM) authentication, UTF-8 encoding and the builtin `C.UTF-8` locale on every platform. Its data, log (`postgres.log`) and connection details live in `.clickhouse/servers/-pg/`. `local install postgres@18` downloads a build ahead of the first start. PostgreSQL does not run as root, so `local postgres start` refuses to as well; use a regular user, or `--docker`. +An instance listens on `127.0.0.1` only, with password (SCRAM) authentication, UTF-8 encoding and the builtin `C.UTF-8` locale on every platform. Its data, log (`postgres.log`) and connection details live in `.clickhouse/servers/-pg/`. `local install postgres@18` downloads a build ahead of the first start. On Linux the server uses System V shared memory (`dynamic_shared_memory_type=sysv`), so parallel queries are not limited by a container's small `/dev/shm`. An instance is identified by name and major version; the name may use only letters, digits, `_`, `.`, and `-`. Pass `--version` when more than one major shares a name. Resuming an instance reuses its original port, user, password, and database; new creation flags do not reconfigure it. A resume uses the newest installed build of the instance's major, since a data directory works across minor versions. If another process now holds the stored port, the resume fails with `port_in_use` instead of starting without it; free the port and start again. To recreate, first back up any needed data, then remove the instance before starting again. Direct `--host`/`--port` client selectors cannot combine with managed name/version selectors. +### Run as root + +PostgreSQL refuses to run as root, so when clickhousectl runs as root (in a container, or under `sudo`) it starts the server as an unprivileged user: `postgres` if that user exists, otherwise `nobody`. It creates no users. The instance's data directory belongs to that user, while the stored connection details stay readable by root only; `client`, `dotenv`, `stop`, `remove` and `list` work as root as usual. + +That user must be able to enter every directory on the way to the project and to `~/.clickhouse/postgres/`. Root's home directory is normally closed to other users, so with `HOME=/root` the start fails with `postgres_directory_not_searchable`, naming the directory, before anything is downloaded or started. Use a project directory and `HOME` outside it (for example `HOME=/srv/home` and a project in `/srv/app`), make the named directory searchable yourself with `chmod o+x`, or use `--docker`. clickhousectl does not change permissions on directories it did not create. + +An existing instance always runs as the owner of its data directory. Root can start, stop and remove an instance a regular user created, and it keeps running as, and belonging to, that user. An instance created as root is root's: other users cannot read its project metadata. + ### Query local ClickHouse from Postgres With a local ClickHouse server running (HTTP port 8123 here), pg_clickhouse exposes its tables to Postgres as foreign tables: diff --git a/docs/reference/automation.md b/docs/reference/automation.md index f65dd2ff5..bb203eadf 100644 --- a/docs/reference/automation.md +++ b/docs/reference/automation.md @@ -193,6 +193,7 @@ Every command except `update`, `--version` included, checks for a newer release | `startup_timeout` | A managed server did not become ready before its deadline | | `download_failed` | An artifact or image download or extraction failed | | `postgres_bundle_unavailable` | No PostgreSQL build can be used for `local postgres`: none is published for the requested version on this platform, none is installed for an instance's major, or the build manifest is not readable by this version | +| `postgres_directory_not_searchable` | Run as root, `local postgres` runs PostgreSQL as an unprivileged user, who cannot enter the directory the message names; nothing was started | | `checksum_mismatch` | A downloaded PostgreSQL build did not match its published SHA-256; nothing was installed | | `network_error` | An HTTP request failed | | `docker_unavailable` | Docker could not be reached (the message names the cause and the platform fix) |