diff --git a/crates/clickhousectl/src/cloud/postgres/cli.rs b/crates/clickhousectl/src/cloud/postgres/cli.rs index 8e4c0667..9ca15ea5 100644 --- a/crates/clickhousectl/src/cloud/postgres/cli.rs +++ b/crates/clickhousectl/src/cloud/postgres/cli.rs @@ -136,6 +136,12 @@ CONTEXT FOR AGENTS: /// High-availability type #[arg(long, value_parser = clap::builder::PossibleValuesParser::new(PgHaType::VALUES))] ha_type: Option, + /// Number of hot standbys; the default depends on --ha-type + /// + /// HA type none takes 0, async takes 1, and sync takes 1 or 2; the + /// default is the highest count the HA type takes. + #[arg(long, value_parser = clap::value_parser!(i64).range(0..=2))] + standby_count: Option, /// Resource tag (repeatable), e.g. --tag env=prod #[arg(long)] tag: Vec, @@ -163,8 +169,8 @@ CONTEXT FOR AGENTS: /// Update a Postgres service's settings, tags or access rules #[command(after_help = "\ CONTEXT FOR AGENTS: - --size/--ha-type: exit 0 means accepted; both take minutes. Poll `cloud postgres get --json` - until `size` changes; `haType` flips at once, so check `pg_stat_replication` on the primary (psql). + --size/--ha-type/--standby-count: exit 0 means accepted; each takes minutes. Poll `cloud postgres + get --json` until `size` changes; HA fields flip at once, so check the primary's `pg_stat_replication`. --new-name changes the service hostname; re-read `cloud postgres get` and update connection strings. --remove-ip-allow takes rule IDs from `cloud postgres get`; removals apply before additions. Access rule changes can partially succeed: after a failure, read the rules with @@ -185,6 +191,12 @@ CONTEXT FOR AGENTS: /// New high-availability type #[arg(long, value_parser = clap::builder::PossibleValuesParser::new(PgHaType::VALUES))] ha_type: Option, + /// New number of hot standbys + /// + /// HA type none takes 0, async takes 1, and sync takes 1 or 2. A new + /// --ha-type without this flag gets that type's default count. + #[arg(long, value_parser = clap::value_parser!(i64).range(0..=2))] + standby_count: Option, /// Turn deletion protection on or off /// /// Only for organizations with deletion protection enabled. @@ -1450,6 +1462,53 @@ mod tests { "m7i.2xlarge", ]; + #[test] + fn parses_postgres_standby_count_from_zero_to_two() { + const UPDATE_ARGS: [&str; 5] = ["clickhousectl", "cloud", "postgres", "update", "pg-1"]; + let PostgresCommands::Create { standby_count, .. } = parse_postgres(&CREATE_ARGS) else { + panic!("expected create"); + }; + assert_eq!(standby_count, None); + let PostgresCommands::Update { standby_count, .. } = parse_postgres(&UPDATE_ARGS) else { + panic!("expected update"); + }; + assert_eq!(standby_count, None); + + for count in ["0", "1", "2"] { + let create: Vec<&str> = CREATE_ARGS + .into_iter() + .chain(["--standby-count", count]) + .collect(); + let PostgresCommands::Create { standby_count, .. } = parse_postgres(&create) else { + panic!("expected create"); + }; + assert_eq!(standby_count, Some(count.parse().unwrap())); + + let update: Vec<&str> = UPDATE_ARGS + .into_iter() + .chain(["--standby-count", count]) + .collect(); + let PostgresCommands::Update { standby_count, .. } = parse_postgres(&update) else { + panic!("expected update"); + }; + assert_eq!(standby_count, Some(count.parse().unwrap())); + } + + for base in [&CREATE_ARGS[..], &UPDATE_ARGS[..]] { + for count in ["-1", "3", "one"] { + let args: Vec<&str> = base + .iter() + .copied() + .chain(["--standby-count", count]) + .collect(); + let error = Cli::try_parse_from(args) + .err() + .expect("out-of-range standby count must be rejected by clap"); + assert_eq!(error.exit_code(), 2, "{count}"); + } + } + } + #[test] fn parses_postgres_create_access_rule_flags() { let PostgresCommands::Create { diff --git a/crates/clickhousectl/src/cloud/postgres/lifecycle.rs b/crates/clickhousectl/src/cloud/postgres/lifecycle.rs index 111d5915..22694041 100644 --- a/crates/clickhousectl/src/cloud/postgres/lifecycle.rs +++ b/crates/clickhousectl/src/cloud/postgres/lifecycle.rs @@ -5,11 +5,11 @@ use crate::cloud::output::{ }; use crate::cloud::shared::{parse_ip_or_cidr, parse_serde_enum, parse_tags, resolve_org_id}; use clickhouse_cloud_api::models::{ - PgBouncerConfig, PgHaType, PgIdProperty, PgProvider, PgSize, PgStateProperty, PgVersion, - PostgresIpAccessListEntry, PostgresIpAccessListPatch, PostgresIpAccessListRuleReference, - PostgresService, PostgresServiceListItem, PostgresServicePatchRequest, - PostgresServicePostRequest, PostgresServiceSetPassword, PostgresServiceSetStateCommand, - ResourceTagsV1, ResourceTagsV1Response, + PgBouncerConfig, PgHaType, PgIdProperty, PgProvider, PgSize, PgStandbyCount, PgStateProperty, + PgVersion, PostgresIpAccessListEntry, PostgresIpAccessListPatch, + PostgresIpAccessListRuleReference, PostgresService, PostgresServiceListItem, + PostgresServicePatchRequest, PostgresServicePostRequest, PostgresServiceSetPassword, + PostgresServiceSetStateCommand, ResourceTagsV1, ResourceTagsV1Response, }; use std::path::Path; use tabled::{Table, Tabled, settings::Style}; @@ -268,6 +268,7 @@ pub(super) fn render_postgres_service(svc: &PostgresService) { enum_label(svc.postgres_version.as_ref()) ); println!(" HA type: {}", enum_label(svc.ha_type.as_ref())); + println!(" Standby count: {}", or_absent(svc.standby_count)); println!(" Primary: {}", or_absent(svc.is_primary)); println!( " Deletion protection: {}", @@ -409,6 +410,7 @@ pub struct PostgresCreateOptions<'a> { pub provider: &'a str, pub pg_version: Option<&'a str>, pub ha_type: Option<&'a str>, + pub standby_count: Option, pub tags: &'a [String], pub pg_config_file: Option<&'a Path>, pub pg_bouncer_config_file: Option<&'a Path>, @@ -420,6 +422,7 @@ pub struct PostgresUpdateOptions<'a> { pub name: Option<&'a str>, pub size: Option<&'a str>, pub ha_type: Option<&'a str>, + pub standby_count: Option, pub deletion_protection: Option, pub add_tag: &'a [String], pub remove_tag: &'a [String], @@ -468,6 +471,8 @@ pub async fn postgres_list( pg: String, #[tabled(rename = "HA")] ha: String, + #[tabled(rename = "Standbys")] + standbys: String, #[tabled(rename = "Primary")] primary: String, #[tabled(rename = "Deletion protection")] @@ -485,6 +490,7 @@ pub async fn postgres_list( size: enum_label(i.size.as_ref()), pg: enum_label(i.postgres_version.as_ref()), ha: enum_label(i.ha_type.as_ref()), + standbys: or_absent(i.standby_count), primary: yes_no(i.is_primary), deletion_protection: yes_no(i.deletion_protection), }) @@ -518,17 +524,18 @@ pub(super) fn postgres_promote_next(org_id: &str, postgres_id: &str) -> NextStep /// `next` for `postgres update --size`, whose resize applies in the /// background while `size` still shows the old value. `None` whenever -/// `--ha-type` is given: `haType` shows the new value as soon as the change is -/// accepted, long before the standby exists, so no field confirms it. `None` -/// for any other update, which applies at once. +/// `--ha-type` or `--standby-count` is given (`changes_standbys`): `haType` +/// and `standbyCount` show the new value as soon as the change is accepted, +/// long before the standbys exist, so no field confirms it. `None` for any +/// other update, which applies at once. fn postgres_update_next( org_id: &str, postgres_id: &str, size: Option<&PgSize>, - ha_type: Option<&PgHaType>, + changes_standbys: bool, ) -> Option { - match (size, ha_type) { - (Some(size), None) => Some( + match (size, changes_standbys) { + (Some(size), false) => Some( postgres_poll(org_id, postgres_id, "size") .until(std::slice::from_ref(size)) .every(30), @@ -595,6 +602,36 @@ fn postgres_credentials_block( } } +/// Checks `--standby-count` against `--ha-type` when both are given and +/// converts it to the API type. The API accepts 0 for `none`, 1 for `async` +/// and 1 or 2 for `sync`; an HA type this CLI does not know is left to the +/// server. Without `--ha-type` the server checks the count against the +/// service's HA type. +fn parse_standby_count( + standby_count: Option, + ha_type: Option<&PgHaType>, +) -> CloudResult> { + let Some(count) = standby_count else { + return Ok(None); + }; + let accepted: &[i64] = match ha_type { + Some(PgHaType::None) => &[0], + Some(PgHaType::Async) => &[1], + Some(PgHaType::Sync) => &[1, 2], + Some(PgHaType::Unknown(_)) | None => &[], + }; + if let Some(ha_type) = ha_type.filter(|_| !accepted.is_empty()) + && !accepted.contains(&count) + { + let accepted: Vec = accepted.iter().map(i64::to_string).collect(); + return Err(CloudError::usage(format!( + "--standby-count {count} is not valid with --ha-type {ha_type}, which takes {}", + accepted.join(" or ") + ))); + } + Ok(Some(PgStandbyCount::from(count))) +} + /// Builds the `postgres create` POST body, reading any config files. fn build_postgres_create_request( opts: &PostgresCreateOptions<'_>, @@ -609,6 +646,7 @@ fn build_postgres_create_request( .ha_type .map(|v| parse_serde_enum(v, "ha-type", PgHaType::VALUES)) .transpose()?; + let standby_count = parse_standby_count(opts.standby_count, ha_type.as_ref())?; let tags = parse_tags(opts.tags)?; let pg_config = opts.pg_config_file.map(load_pg_config_file).transpose()?; let pg_bouncer_config = opts @@ -627,8 +665,7 @@ fn build_postgres_create_request( pg_config, pg_bouncer_config, ip_access_list: postgres_create_ip_access_list(opts.ip_allow, opts.block_public_access), - // Not exposed by `cloud postgres create` yet: never sent. - standby_count: None, + standby_count, }) } @@ -671,13 +708,15 @@ pub async fn postgres_create( } /// Builds the `postgres update` PATCH body from the already-parsed pieces -/// (name, size, HA type, deletion protection, merged tags, access-rule patch). +/// (name, size, HA type, standby count, deletion protection, merged tags, +/// access-rule patch). /// Kept separate from `postgres_update` so the shape sent on the wire is /// unit-testable without a mock server. pub(super) fn build_postgres_update_request( name: Option<&str>, size: Option, ha_type: Option, + standby_count: Option, deletion_protection: Option, tags: Option>, ip_access_list: Option, @@ -689,8 +728,7 @@ pub(super) fn build_postgres_update_request( ha_type, tags, ip_access_list, - // Not exposed by `cloud postgres update` yet: never sent. - standby_count: None, + standby_count, } } @@ -700,13 +738,14 @@ pub async fn postgres_update( opts: PostgresUpdateOptions<'_>, json: bool, ) -> CloudResult<()> { - let org_id = resolve_org_id(client).await?; - let size = opts.size.map(parse_pg_size).transpose()?; let ha_type = opts .ha_type .map(|v| parse_serde_enum::(v, "ha-type", PgHaType::VALUES)) .transpose()?; + let standby_count = parse_standby_count(opts.standby_count, ha_type.as_ref())?; + + let org_id = resolve_org_id(client).await?; // Clearing is already a complete replacement, so it never needs a GET. // The API clears tags when PATCH omits them, even for a rename or resize. @@ -719,14 +758,16 @@ pub async fn postgres_update( Some(merge_response_tags(current.tags, &add, opts.remove_tag)?) }; - let next = postgres_update_next(&org_id, postgres_id, size.as_ref(), ha_type.as_ref()); - let (resizes, changes_ha) = (size.is_some(), ha_type.is_some()); + let (resizes, changes_standbys) = + (size.is_some(), ha_type.is_some() || standby_count.is_some()); + let next = postgres_update_next(&org_id, postgres_id, size.as_ref(), changes_standbys); let ip_access_list = build_postgres_ip_access_list_patch(opts.add_ip_allow, opts.remove_ip_allow); let req = build_postgres_update_request( opts.name, size, ha_type, + standby_count, opts.deletion_protection, tags, ip_access_list, @@ -738,7 +779,7 @@ pub async fn postgres_update( if json { println!("{}", json_with_next(&svc, next)?); - } else if resizes || changes_ha { + } else if resizes || changes_standbys { println!("Postgres service update accepted"); println!(); render_postgres_service(&svc); @@ -748,7 +789,7 @@ pub async fn postgres_update( &cloud_command(&["postgres", "get", postgres_id], &org_id), ); } - if changes_ha { + if changes_standbys { eprintln!("{HA_CHANGE_NOTE}"); } } else { @@ -759,11 +800,13 @@ pub async fn postgres_update( Ok(()) } -/// Human-mode note for an accepted `--ha-type` change (#1241). Unlike a -/// resize, `haType` shows the new value at once, so no `get` confirms it. -const HA_CHANGE_NOTE: &str = "The HA type already shows the new value, but the standby is still \ - being added or removed in the background, which can take several minutes. Check \ - `pg_stat_replication` on the primary through psql: an added standby is ready once it is listed."; +/// Human-mode note for an accepted `--ha-type` or `--standby-count` change +/// (#1241). Unlike a resize, `haType` and `standbyCount` show the new value at +/// once, so no `get` confirms it. +const HA_CHANGE_NOTE: &str = "The HA type and standby count already show the new values, but \ + standbys are still being added or removed in the background, which can take several minutes. \ + Check `pg_stat_replication` on the primary through psql: an added standby is ready once it is \ + listed."; pub async fn postgres_delete( client: &CloudClient, @@ -907,30 +950,87 @@ pub(super) mod tests { use super::*; /// A resize is confirmed by `size`, the field name `postgres get --json` - /// prints. An HA change, alone or with a resize, gets no hint because - /// `haType` flips on acceptance; neither does an update changing neither. + /// prints. An HA or standby-count change, alone or with a resize, gets no + /// hint because `haType` and `standbyCount` flip on acceptance; neither + /// does an update changing neither. #[test] fn postgres_update_next_polls_size_only() { let size = parse_pg_size("c6gd.large").unwrap(); - let ha_type = PgHaType::Async; let svc = serde_json::to_value(PostgresService { size: Some(size.clone()), ..PostgresService::default() }) .unwrap(); - let next = postgres_update_next("org-1", "pg-1", Some(&size), None).unwrap(); + let next = postgres_update_next("org-1", "pg-1", Some(&size), false).unwrap(); assert_eq!( next.command, "clickhousectl cloud postgres get pg-1 --org-id org-1 --json" ); assert_eq!(next.field, "size"); assert_eq!(next.until, [svc[next.field].clone()]); - for (size, ha_type) in [ - (None, Some(&ha_type)), - (Some(&size), Some(&ha_type)), - (None, None), + for (size, changes_standbys) in [(None, true), (Some(&size), true), (None, false)] { + assert_eq!( + postgres_update_next("org-1", "pg-1", size, changes_standbys), + None + ); + } + } + + #[test] + fn parse_standby_count_accepts_each_count_its_ha_type_takes() { + assert_eq!( + parse_standby_count(None, Some(&PgHaType::Sync)).unwrap(), + None + ); + for (ha_type, count, expected) in [ + (PgHaType::None, 0, PgStandbyCount::Zero), + (PgHaType::Async, 1, PgStandbyCount::One), + (PgHaType::Sync, 1, PgStandbyCount::One), + (PgHaType::Sync, 2, PgStandbyCount::Two), + ] { + assert_eq!( + parse_standby_count(Some(count), Some(&ha_type)).unwrap(), + Some(expected) + ); + } + } + + #[test] + fn parse_standby_count_rejects_a_count_its_ha_type_does_not_take() { + for (ha_type, count) in [ + (PgHaType::None, 1), + (PgHaType::None, 2), + (PgHaType::Async, 0), + (PgHaType::Async, 2), + (PgHaType::Sync, 0), ] { - assert_eq!(postgres_update_next("org-1", "pg-1", size, ha_type), None); + let error = parse_standby_count(Some(count), Some(&ha_type)).unwrap_err(); + assert_eq!(error.kind, crate::cloud::client::CloudErrorKind::Usage); + assert!( + error.message.contains("--standby-count"), + "{}", + error.message + ); + assert!(error.message.contains("--ha-type"), "{}", error.message); + assert!( + error.message.contains(&ha_type.to_string()), + "{}", + error.message + ); + } + } + + /// Without `--ha-type`, or with one this CLI does not know, the server + /// checks the count against the HA type it applies. + #[test] + fn parse_standby_count_leaves_other_ha_types_to_the_server() { + for ha_type in [None, Some(PgHaType::Unknown("quorum".into()))] { + for count in 0..=2 { + assert_eq!( + parse_standby_count(Some(count), ha_type.as_ref()).unwrap(), + Some(PgStandbyCount::from(count)) + ); + } } } @@ -1063,7 +1163,7 @@ pub(super) mod tests { #[test] fn build_postgres_update_request_omits_name_when_not_given() { - let req = build_postgres_update_request(None, None, None, None, None, None); + let req = build_postgres_update_request(None, None, None, None, None, None, None); assert!(req.name.is_none()); assert!(req.size.is_none()); assert!(req.ha_type.is_none()); @@ -1076,7 +1176,8 @@ pub(super) mod tests { #[test] fn build_postgres_update_request_clears_tags_explicitly() { - let req = build_postgres_update_request(None, None, None, None, Some(Vec::new()), None); + let req = + build_postgres_update_request(None, None, None, None, None, Some(Vec::new()), None); assert_eq!(req.tags, Some(Vec::new())); assert_eq!( @@ -1091,6 +1192,7 @@ pub(super) mod tests { Some("renamed-pg"), Some(PgSize::C6gd_large), Some(PgHaType::Sync), + Some(PgStandbyCount::One), Some(true), Some(vec![ResourceTagsV1 { key: "env".into(), @@ -1104,6 +1206,8 @@ pub(super) mod tests { assert_eq!(req.name.as_deref(), Some("renamed-pg")); assert!(req.size.is_some()); assert_eq!(req.ha_type, Some(PgHaType::Sync)); + assert_eq!(req.standby_count, Some(PgStandbyCount::One)); + assert_eq!(serde_json::to_value(&req).unwrap()["standbyCount"], 1); assert_eq!(req.deletion_protection, Some(true)); assert_eq!(req.tags.as_ref().unwrap().len(), 1); assert_eq!( @@ -1117,7 +1221,7 @@ pub(super) mod tests { #[test] fn build_postgres_update_request_sends_deletion_protection_off() { - let req = build_postgres_update_request(None, None, None, Some(false), None, None); + let req = build_postgres_update_request(None, None, None, None, Some(false), None, None); assert_eq!( serde_json::to_value(req).unwrap(), @@ -1223,6 +1327,7 @@ pub(super) mod tests { provider: "aws", pg_version: None, ha_type: None, + standby_count: None, tags: &[], pg_config_file: None, pg_bouncer_config_file: None, @@ -1253,6 +1358,17 @@ pub(super) mod tests { ); } + #[test] + fn build_postgres_create_request_rejects_a_standby_count_the_ha_type_refuses() { + let options = PostgresCreateOptions { + ha_type: Some("none"), + standby_count: Some(2), + ..create_options(&[], false) + }; + let error = build_postgres_create_request(&options).unwrap_err(); + assert_eq!(error.kind, crate::cloud::client::CloudErrorKind::Usage); + } + #[test] fn build_postgres_create_request_sends_rules_or_an_empty_list() { let blocked = build_postgres_create_request(&create_options(&[], true)).unwrap(); @@ -1268,12 +1384,15 @@ pub(super) mod tests { let options = PostgresCreateOptions { pg_version: Some("17"), ha_type: Some("sync"), + standby_count: Some(1), tags: &["env=prod".to_string()][..], ..create_options(&rules, false) }; let req = build_postgres_create_request(&options).unwrap(); assert_eq!(req.postgres_version, Some(PgVersion::_17)); assert_eq!(req.ha_type, Some(PgHaType::Sync)); + assert_eq!(req.standby_count, Some(PgStandbyCount::One)); + assert_eq!(serde_json::to_value(&req).unwrap()["standbyCount"], 1); assert_eq!(req.tags.as_ref().unwrap().len(), 1); assert_eq!(req.ip_access_list.as_ref(), Some(&rules)); assert_eq!( diff --git a/crates/clickhousectl/src/cloud/postgres/mod.rs b/crates/clickhousectl/src/cloud/postgres/mod.rs index d4de0779..80289d7e 100644 --- a/crates/clickhousectl/src/cloud/postgres/mod.rs +++ b/crates/clickhousectl/src/cloud/postgres/mod.rs @@ -222,6 +222,7 @@ pub async fn run(client: &CloudClient, command: PostgresCommands, json: bool) -> provider, pg_version, ha_type, + standby_count, tag, pg_config_file, pg_bouncer_config_file, @@ -235,6 +236,7 @@ pub async fn run(client: &CloudClient, command: PostgresCommands, json: bool) -> provider: &provider, pg_version: pg_version.as_deref(), ha_type: ha_type.as_deref(), + standby_count, tags: &tag, pg_config_file: pg_config_file.as_deref(), pg_bouncer_config_file: pg_bouncer_config_file.as_deref(), @@ -248,6 +250,7 @@ pub async fn run(client: &CloudClient, command: PostgresCommands, json: bool) -> name, size, ha_type, + standby_count, deletion_protection, add_tag, remove_tag, @@ -259,6 +262,7 @@ pub async fn run(client: &CloudClient, command: PostgresCommands, json: bool) -> name: name.as_deref(), size: size.as_deref(), ha_type: ha_type.as_deref(), + standby_count, deletion_protection, add_tag: &add_tag, remove_tag: &remove_tag, diff --git a/crates/clickhousectl/src/cloud/postgres/topology.rs b/crates/clickhousectl/src/cloud/postgres/topology.rs index 9b43eb0d..8bb6e744 100644 --- a/crates/clickhousectl/src/cloud/postgres/topology.rs +++ b/crates/clickhousectl/src/cloud/postgres/topology.rs @@ -251,7 +251,7 @@ async fn apply_restored_access_rules( Some(tags) => merge_response_tags(Some(tags), &[], &[]).map_err(unapplied)?, None => requested_tags.unwrap_or_default(), }; - let req = build_postgres_update_request(None, None, None, None, Some(tags), Some(patch)); + let req = build_postgres_update_request(None, None, None, None, None, Some(tags), Some(patch)); let patched = client .patch_postgres_service(org_id, &restored_id, &req) .await diff --git a/crates/clickhousectl/tests/cloud/postgres.rs b/crates/clickhousectl/tests/cloud/postgres.rs index 34577940..291269e5 100644 --- a/crates/clickhousectl/tests/cloud/postgres.rs +++ b/crates/clickhousectl/tests/cloud/postgres.rs @@ -1458,6 +1458,7 @@ fn postgres_list_response() -> ResponseTemplate { "provider": "aws", "isPrimary": true, "deletionProtection": true, + "standbyCount": 1, }, { "id": "66666666-7777-8888-9999-000000000000", @@ -1517,7 +1518,7 @@ async fn postgres_list_applies_supported_filters_client_side() { } #[tokio::test] -async fn postgres_list_shows_provider_in_human_output_and_preserves_json() { +async fn postgres_list_shows_provider_and_standbys_in_human_output_and_preserves_json() { let mock = MockServer::start().await; Mock::given(method("GET")) .and(path("/v1/organizations/org-1/postgres")) @@ -1551,15 +1552,18 @@ async fn postgres_list_shows_provider_in_human_output_and_preserves_json() { "Size", "PG", "HA", + "Standbys", "Primary", "Deletion protection" ] ); assert_eq!(row_cells("primary-pg")[3], "aws"); assert_eq!(row_cells("unknown-pg")[3], "-"); - assert_eq!(row_cells("primary-pg")[9], "yes"); - assert_eq!(row_cells("replica-pg")[9], "no"); - assert_eq!(row_cells("unknown-pg")[9], "-"); + assert_eq!(row_cells("primary-pg")[8], "1"); + assert_eq!(row_cells("unknown-pg")[8], "-"); + assert_eq!(row_cells("primary-pg")[10], "yes"); + assert_eq!(row_cells("replica-pg")[10], "no"); + assert_eq!(row_cells("unknown-pg")[10], "-"); let json = invoke_cli_with_cloud_credentials(&mock, &["postgres", "list", "--org-id", "org-1"]); assert_success(&json); @@ -1574,6 +1578,7 @@ async fn postgres_list_shows_provider_in_human_output_and_preserves_json() { "provider": "aws", "isPrimary": true, "deletionProtection": true, + "standbyCount": 1, }, { "id": "66666666-7777-8888-9999-000000000000", diff --git a/docs/guides/managed-postgres.md b/docs/guides/managed-postgres.md index a926ca3d..23532cf1 100644 --- a/docs/guides/managed-postgres.md +++ b/docs/guides/managed-postgres.md @@ -86,7 +86,9 @@ Run `SELECT pg_postmaster_start_time()` again: only a later timestamp confirms a `pgConfig` uses supported Cloud GUC names; unknown names, null values, and values outside a setting's documented set (for example `io_method` or `wal_compression`) are rejected before any request. On create, restore, or read-replica creation, `--pg-bouncer-config-file` takes just the string-valued PgBouncer map, without the two-section wrapper. -`update --size` and `--ha-type` return once the API accepts the change, which then applies in the background and can take several minutes. After a resize, the printed service still shows the old size; poll `get` until `size` shows the new one (in JSON mode, `next` names the poll). After an HA change, `haType` shows the new value at once while the standby is still being added or removed, so `get` cannot confirm it; check `pg_stat_replication` on the primary through `psql`, where an added standby appears once it is replicating. +`--ha-type` sets high availability and `--standby-count` the number of hot standbys, on `create` or `update`. `none` takes 0 standbys, `async` takes 1, and `sync` takes 1 or 2; when you change the HA type without a count, the new type's default applies (0, 1 and 2 respectively). Passing a count the given `--ha-type` does not take is a usage error (exit 2) before any request; a count alone is checked by the API against the service's current HA type. `get` and `list` show the standby count. + +`update --size`, `--ha-type` and `--standby-count` return once the API accepts the change, which then applies in the background and can take several minutes. After a resize, the printed service still shows the old size; poll `get` until `size` shows the new one (in JSON mode, `next` names the poll). After an HA or standby-count change, `haType` and `standbyCount` show the new values at once while standbys are still being added or removed, so `get` cannot confirm it; check `pg_stat_replication` on the primary through `psql`, where an added standby appears once it is replicating. Tag updates fetch and replace the complete tag snapshot. Omitted flags preserve it; `--clear-tags` empties it. Avoid concurrent tag edits because one snapshot can overwrite another. diff --git a/docs/reference/automation.md b/docs/reference/automation.md index 1a9ab326..da883b38 100644 --- a/docs/reference/automation.md +++ b/docs/reference/automation.md @@ -90,7 +90,7 @@ When a local error's text comes from another program, `message` is clickhousectl | ClickHouse delete | Poll `service get` until `state` is `terminated` or `softdeleted`, or it fails with `resource_not_found` | | Postgres create/restore/replica | Poll `postgres get`; verify connectivity and credentials separately | | Postgres resize (`update --size`) | Poll `postgres get` until `size` shows the requested value; this can take several minutes | -| Postgres HA change (`update --ha-type`) | No field signal: `haType` shows the new value as soon as the change is accepted, minutes before the standby exists; check `pg_stat_replication` on the primary | +| Postgres HA change (`update --ha-type` or `--standby-count`) | No field signal: `haType` and `standbyCount` show the new value as soon as the change is accepted, minutes before the standby exists; check `pg_stat_replication` on the primary | | Postgres config/restart | Re-read configuration, compare `pg_postmaster_start_time()` before/after restart, then `SHOW` the changed setting | | Postgres promote | Poll the replica until `isPrimary: true` | | Postgres switchover | No completion signal: it may wait for the maintenance window, and service-level state, `isPrimary` and readiness do not confirm it | @@ -128,7 +128,7 @@ Run `command` as is: it carries the resolved IDs and `--org-id`, but not credent | `clickpipe cdc-scaling update` | `clickpipe cdc-scaling get` | `replicaCpuMillicores` | The requested value | None | | `clickpipe reverse-private-endpoint create` | `clickpipe reverse-private-endpoint get` | `status` | `Ready` | `Failed`, `Rejected`, `Expired` | -Some commands have no `next`, because no single field confirms them. `postgres restart` can show `running` before the restart begins, so compare `pg_postmaster_start_time()` instead. Nothing that `postgres get` returns confirms a `postgres switchover`. A `postgres update --ha-type`, alone or with `--size`, has none because `haType` shows the new value on acceptance, minutes before the standby is replicating, so check `pg_stat_replication` on the primary instead. Any other `postgres update` applies at once. `next` is also omitted when the API response has no ID to poll. An endpoint in `PendingAcceptance` stays there until the source-side owner accepts it. +Some commands have no `next`, because no single field confirms them. `postgres restart` can show `running` before the restart begins, so compare `pg_postmaster_start_time()` instead. Nothing that `postgres get` returns confirms a `postgres switchover`. A `postgres update --ha-type` or `--standby-count`, alone or with `--size`, has none because `haType` and `standbyCount` show the new value on acceptance, minutes before the standby is replicating, so check `pg_stat_replication` on the primary instead. Any other `postgres update` applies at once. `next` is also omitted when the API response has no ID to poll. An endpoint in `PendingAcceptance` stays there until the source-side owner accepts it. See the relevant [task guide](../README.md) for the full sequence. Resource creation, resync, password reset, and SQL writes are not safe generic retry targets. Reconcile the observed state before deciding what to repeat.