OpenAPI drift: 114 gaps between live spec and library

[github-actions]

The live ClickHouse Cloud OpenAPI spec has operations or schemas that the
Rust library (client.rs / models.rs) does not cover yet.

• Live spec: https://api.clickhouse.cloud/v1
• Client: crates/clickhouse-cloud-api/src/client.rs
• Models: crates/clickhouse-cloud-api/src/models.rs

Summary

Change	Count
Missing client methods	0
Extra client methods (not in spec)	1
Missing model types	7
Missing struct fields	13
Field optionality mismatches	86
Stale snapshot changes	7

Extra Client Methods

These pub async fn methods exist in client.rs but have no matching
operation in the live spec. They may have been removed from the API.

• run_query

Missing Model Types

The live spec defines these schemas but models.rs has no matching
pub struct, pub enum, or pub type.

CurrentScaling (spec name: CurrentScaling)

Schema JSON

{
  "properties": {
    "effectiveAutoscalingMode": {
      "description": "Autoscaling mode currently in effect on the running service. May diverge from the configured baseline mode while a schedule entry is active.",
      "type": "string",
      "enum": [
        "vertical",
        "horizontal"
      ]
    },
    "effectiveMinReplicaMemoryGb": {
      "description": "Minimum memory per replica (Gb) currently applied to the running service. May diverge from the top-level `minReplicaMemoryGb` baseline while a schedule entry is active.",
      "type": "number"
    },
    "effectiveMaxReplicaMemoryGb": {
      "description": "Maximum memory per replica (Gb) currently applied to the running service. May diverge from the top-level `maxReplicaMemoryGb` baseline while a schedule entry is active. In horizontal autoscaling mode equals `effectiveMinReplicaMemoryGb`.",
      "type": "number"
    },
    "effectiveMinReplicas": {
      "description": "Minimum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active. In vertical autoscaling mode equals `effectiveMaxReplicas` (vertical mode runs a fixed replica count).",
      "type": "integer"
    },
    "effectiveMaxReplicas": {
      "description": "Maximum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active.",
      "type": "integer"
    },
    "effectiveIdleScaling": {
      "description": "Whether idle scaling is currently in effect on the service. May diverge from the top-level `idleScaling` baseline while a schedule entry is active.",
      "type": "boolean"
    },
    "effectiveIdleTimeoutMinutes": {
      "description": "Idle timeout in minutes currently in effect on the service. May diverge from the top-level `idleTimeoutMinutes` baseline while a schedule entry is active.",
      "type": "integer"
    },
    "activeEntryId": {
      "description": "ID of the schedule entry whose values are currently applied to the service. Absent when no entry is active.",
      "type": "string",
      "format": "uuid"
    }
  }
}

ScalingSchedule (spec name: ScalingSchedule)

Schema JSON

{
  "properties": {
    "entries": {
      "type": "array",
      "description": "List of schedule entries.",
      "items": {
        "$ref": "#/components/schemas/ScalingScheduleEntry"
      }
    },
    "baseConfig": {
      "$ref": "#/components/schemas/ScalingScheduleBaseConfig"
    },
    "activeEntryId": {
      "description": "ID of the currently-active schedule entry. Absent when no entry is active and the base config is in effect.",
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "entries",
    "baseConfig"
  ]
}

ScalingScheduleBaseConfig (spec name: ScalingScheduleBaseConfig)

Schema JSON

{
  "properties": {
    "minReplicaMemoryGb": {
      "description": "Minimum memory per replica (Gb) when no schedule entry is active.",
      "type": "number"
    },
    "maxReplicaMemoryGb": {
      "description": "Maximum memory per replica (Gb) when no schedule entry is active.",
      "type": "number"
    },
    "minReplicas": {
      "description": "Minimum number of replicas when no schedule entry is active.",
      "type": "integer"
    },
    "maxReplicas": {
      "description": "Maximum number of replicas when no schedule entry is active.",
      "type": "integer"
    },
    "idleScaling": {
      "description": "Whether idle scaling is enabled when no schedule entry is active.",
      "type": "boolean"
    },
    "idleTimeoutMinutes": {
      "description": "Idle timeout in minutes when no schedule entry is active.",
      "type": "integer"
    }
  }
}

ScalingScheduleEntry (spec name: ScalingScheduleEntry)

Schema JSON

{
  "properties": {
    "id": {
      "description": "Unique identifier for this schedule entry.",
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "description": "Human-readable label for this schedule entry.",
      "type": "string"
    },
    "weekdays": {
      "type": "array",
      "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.",
      "items": {
        "type": "integer"
      }
    },
    "startHourUtc": {
      "description": "UTC hour (0\u201323) when this entry becomes active (inclusive).",
      "type": "integer",
      "minimum": 0,
      "maximum": 23
    },
    "endHourUtc": {
      "description": "UTC hour (1\u201324) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.",
      "type": "integer",
      "minimum": 1,
      "maximum": 24
    },
    "minReplicaMemoryGb": {
      "description": "Minimum memory per replica (Gb) during this window.",
      "type": "number"
    },
    "maxReplicaMemoryGb": {
      "description": "Maximum memory per replica (Gb) during this window.",
      "type": "number"
    },
    "minReplicas": {
      "description": "Minimum number of replicas during this window. Must equal maxReplicas \u2014 schedule entries specify a fixed replica count per window.",
      "type": "integer"
    },
    "maxReplicas": {
      "description": "Maximum number of replicas during this window. Must equal minReplicas \u2014 schedule entries specify a fixed replica count per window.",
      "type": "integer"
    },
    "idleScaling": {
      "description": "Whether idle scaling is enabled during this window.",
      "type": "boolean"
    },
    "idleTimeoutMinutes": {
      "description": "Idle timeout in minutes during this window.",
      "type": "integer"
    },
    "isActiveNow": {
      "description": "Whether this entry is currently active. Scheduled times are indicative \u2014 actions are applied on a best-effort basis and may be delayed by a few minutes.",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "name",
    "weekdays",
    "startHourUtc",
    "endHourUtc",
    "isActiveNow"
  ]
}

ScalingScheduleEntryRequest (spec name: ScalingScheduleEntryRequest)

Schema JSON

{
  "properties": {
    "name": {
      "description": "Human-readable label for this schedule entry.",
      "type": "string",
      "example": "Business hours"
    },
    "weekdays": {
      "type": "array",
      "description": "Days of the week this entry applies to. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.",
      "items": {
        "type": "integer"
      }
    },
    "startHourUtc": {
      "description": "UTC hour (0\u201323) when this entry becomes active (inclusive).",
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "example": 9
    },
    "endHourUtc": {
      "description": "UTC hour (1\u201324) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.",
      "type": "integer",
      "minimum": 1,
      "maximum": 24,
      "example": 17
    },
    "minReplicaMemoryGb": {
      "description": "Minimum memory per replica (Gb) during this window.",
      "type": "number"
    },
    "maxReplicaMemoryGb": {
      "description": "Maximum memory per replica (Gb) during this window.",
      "type": "number"
    },
    "minReplicas": {
      "description": "Minimum number of replicas during this window.",
      "type": "integer"
    },
    "maxReplicas": {
      "description": "Maximum number of replicas during this window.",
      "type": "integer"
    },
    "idleScaling": {
      "description": "Whether idle scaling is enabled during this window.",
      "type": "boolean"
    },
    "idleTimeoutMinutes": {
      "description": "Idle timeout in minutes during this window.",
      "type": "integer"
    }
  },
  "required": [
    "name",
    "weekdays",
    "startHourUtc",
    "endHourUtc"
  ]
}

ScalingSchedulePatchRequest (spec name: ScalingSchedulePatchRequest)

Schema JSON

{
  "properties": {
    "entries": {
      "type": "array",
      "description": "Full list of schedule entries. Replaces any existing schedule. Pass an empty array to clear the schedule.",
      "items": {
        "$ref": "#/components/schemas/ScalingScheduleEntryRequest"
      }
    }
  },
  "required": [
    "entries"
  ]
}

ScalingSchedulePostRequest (spec name: ScalingSchedulePostRequest)

Schema JSON

{
  "properties": {
    "entries": {
      "type": "array",
      "description": "List of schedule entries. Pass an empty array to clear the schedule.",
      "items": {
        "$ref": "#/components/schemas/ScalingScheduleEntryRequest"
      }
    }
  },
  "required": [
    "entries"
  ]
}

Missing Struct Fields

These properties exist in the OpenAPI spec but have no corresponding
field in the Rust struct. API response data for these fields is silently
dropped during deserialization.

Schema	Field
Service	currentScaling
Service	maxReplicas
Service	minReplicas
Service	replicaMemoryGb
Service	scalingSchedule
ServiceReplicaScalingPatchRequest	maxReplicas
ServiceReplicaScalingPatchRequest	minReplicas
ServiceReplicaScalingPatchRequest	replicaMemoryGb
ServiceScalingPatchResponse	currentScaling
ServiceScalingPatchResponse	maxReplicas
ServiceScalingPatchResponse	minReplicas
ServiceScalingPatchResponse	replicaMemoryGb
ServiceScalingPatchResponse	scalingSchedule

Field Optionality Mismatches

These fields have incorrect Option<T> vs T types in models.rs.
Required non-nullable fields should be T; optional or nullable fields
should be Option<T>.

Schema	Field	Expected	Actual
ApiKeyPostRequest	hashData	required (T)	Option
ApiKeyPostRequest	roles	required (T)	Option
Service	availablePrivateEndpointIds	optional (Option)	T
Service	byocId	optional (Option)	T
Service	clickhouseVersion	optional (Option)	T
Service	complianceType	optional (Option)	T
Service	createdAt	optional (Option)	T
Service	dataWarehouseId	optional (Option)	T
Service	enableCoreDumps	optional (Option)	T
Service	encryptionRoleId	optional (Option)	T
Service	endpoints	optional (Option)	T
Service	hasTransparentDataEncryption	optional (Option)	T
Service	iamRole	optional (Option)	T
Service	id	optional (Option)	T
Service	idleScaling	optional (Option)	T
Service	idleTimeoutMinutes	optional (Option)	T
Service	ipAccessList	optional (Option)	T
Service	isPrimary	optional (Option)	T
Service	isReadonly	optional (Option)	T
Service	maxReplicaMemoryGb	optional (Option)	T
Service	maxTotalMemoryGb	optional (Option)	T
Service	minReplicaMemoryGb	optional (Option)	T
Service	minTotalMemoryGb	optional (Option)	T
Service	name	optional (Option)	T
Service	numReplicas	optional (Option)	T
Service	privateEndpointIds	optional (Option)	T
Service	profile	optional (Option)	T
Service	provider	optional (Option)	T
Service	region	optional (Option)	T
Service	releaseChannel	optional (Option)	T
Service	state	optional (Option)	T
Service	tags	optional (Option)	T
Service	tier	optional (Option)	T
Service	transparentDataEncryptionKeyId	optional (Option)	T
ServicePostRequest	byocId	required (T)	Option
ServicePostRequest	complianceType	required (T)	Option
ServicePostRequest	dataWarehouseId	required (T)	Option
ServicePostRequest	enableCoreDumps	required (T)	Option
ServicePostRequest	endpoints	required (T)	Option
ServicePostRequest	hasTransparentDataEncryption	required (T)	Option
ServicePostRequest	idleScaling	required (T)	Option
ServicePostRequest	idleTimeoutMinutes	required (T)	Option
ServicePostRequest	isReadonly	required (T)	Option
ServicePostRequest	maxReplicaMemoryGb	required (T)	Option
ServicePostRequest	maxTotalMemoryGb	required (T)	Option
ServicePostRequest	minReplicaMemoryGb	required (T)	Option
ServicePostRequest	minTotalMemoryGb	required (T)	Option
ServicePostRequest	numReplicas	required (T)	Option
ServicePostRequest	privateEndpointIds	required (T)	Option
ServicePostRequest	privatePreviewTermsChecked	required (T)	Option
ServicePostRequest	profile	required (T)	Option
ServicePostRequest	releaseChannel	required (T)	Option
ServicePostRequest	tags	required (T)	Option
ServicePostRequest	tier	required (T)	Option
ServiceScalingPatchResponse	availablePrivateEndpointIds	optional (Option)	T
ServiceScalingPatchResponse	byocId	optional (Option)	T
ServiceScalingPatchResponse	clickhouseVersion	optional (Option)	T
ServiceScalingPatchResponse	complianceType	optional (Option)	T
ServiceScalingPatchResponse	createdAt	optional (Option)	T
ServiceScalingPatchResponse	dataWarehouseId	optional (Option)	T
ServiceScalingPatchResponse	enableCoreDumps	optional (Option)	T
ServiceScalingPatchResponse	encryptionRoleId	optional (Option)	T
ServiceScalingPatchResponse	endpoints	optional (Option)	T
ServiceScalingPatchResponse	hasTransparentDataEncryption	optional (Option)	T
ServiceScalingPatchResponse	iamRole	optional (Option)	T
ServiceScalingPatchResponse	id	optional (Option)	T
ServiceScalingPatchResponse	idleScaling	optional (Option)	T
ServiceScalingPatchResponse	idleTimeoutMinutes	optional (Option)	T
ServiceScalingPatchResponse	ipAccessList	optional (Option)	T
ServiceScalingPatchResponse	isPrimary	optional (Option)	T
ServiceScalingPatchResponse	isReadonly	optional (Option)	T
ServiceScalingPatchResponse	maxReplicaMemoryGb	optional (Option)	T
ServiceScalingPatchResponse	maxTotalMemoryGb	optional (Option)	T
ServiceScalingPatchResponse	minReplicaMemoryGb	optional (Option)	T
ServiceScalingPatchResponse	minTotalMemoryGb	optional (Option)	T
ServiceScalingPatchResponse	name	optional (Option)	T
ServiceScalingPatchResponse	numReplicas	optional (Option)	T
ServiceScalingPatchResponse	privateEndpointIds	optional (Option)	T
ServiceScalingPatchResponse	profile	optional (Option)	T
ServiceScalingPatchResponse	provider	optional (Option)	T
ServiceScalingPatchResponse	region	optional (Option)	T
ServiceScalingPatchResponse	releaseChannel	optional (Option)	T
ServiceScalingPatchResponse	state	optional (Option)	T
ServiceScalingPatchResponse	tags	optional (Option)	T
ServiceScalingPatchResponse	tier	optional (Option)	T
ServiceScalingPatchResponse	transparentDataEncryptionKeyId	optional (Option)	T

Stale Snapshot

The committed clickhouse_cloud_openapi.json is behind the live spec.
Tests that run against the snapshot may pass even though the library is
missing coverage for new endpoints or schemas.

New schemas in live spec (not in snapshot):

• CurrentScaling
• ScalingSchedule
• ScalingScheduleBaseConfig
• ScalingScheduleEntry
• ScalingScheduleEntryRequest
• ScalingSchedulePatchRequest
• ScalingSchedulePostRequest

Implementation Guide

1. Update the checked-in spec:

   curl -s https://api.clickhouse.cloud/v1 -o crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json

2. Add missing types to crates/clickhouse-cloud-api/src/models.rs
   • Use #[serde(rename_all = "camelCase")] on structs
   • Use #[serde(skip_serializing_if = "Option::is_none")] for optional fields
   • Enums should derive Default and include an #[serde(other)] Unknown variant
3. Add missing methods to crates/clickhouse-cloud-api/src/client.rs
4. Fix field optionality:

   python scripts/update-models-optionality.py

5. Verify: cargo test -p clickhouse-cloud-api