mz_deploy/
client.rs

1// Copyright Materialize, Inc. and contributors. All rights reserved.
2//
3// Use of this software is governed by the Business Source License
4// included in the LICENSE file.
5//
6// As of the Change Date specified in that file, in accordance with
7// the Business Source License, use of this software will be governed
8// by the Apache License, Version 2.0.
9
10//! Database client layer for communicating with a Materialize region.
11//!
12//! All interaction with the live database flows through this module. The
13//! `Client` type (defined in `connection`) holds a `tokio_postgres`
14//! connection and exposes scoped sub-clients that group related operations:
15//!
16//! - **`introspection`** — Read-only catalog queries: schema/cluster/object
17//!   existence checks, dependency lookups, and batch metadata retrieval.
18//! - **`provisioning`** — DDL operations that create or alter databases,
19//!   schemas, and clusters to match the project definition.
20//! - **`deployment_ops`** — Blue/green deployment lifecycle: staging,
21//!   hydration monitoring, cutover, and abort.
22//! - **`validation`** — Pre-deployment validation: checks that the target
23//!   environment matches expected state before applying changes.
24//! - **`type_info`** — `SHOW COLUMNS` queries used to generate and refresh
25//!   the `types.lock` data-contract file.
26//!
27//! ## Supporting Submodules
28//!
29//! - **`models`** — Data structures shared across sub-clients (deployment
30//!   records, cluster configs, conflict records, etc.).
31//! - **`errors`** — Error types: `ConnectionError` for transport/query
32//!   failures, `DatabaseValidationError` for semantic mismatches.
33//!
34//! Most sub-client types are internal; this module re-exports the key public
35//! types so that consumers only need `use crate::client::*`.
36
37mod connection;
38mod deployment_ops;
39mod dev_overlays;
40mod errors;
41mod introspection;
42mod models;
43mod provisioning;
44mod type_info;
45mod validation;
46
47/// Name of the dedicated cluster mz-deploy creates during `setup` and
48/// pins every connection to via libpq options.
49pub const SERVER_CLUSTER_NAME: &str = "_mz_deploy_server";
50
51pub use crate::config::Profile;
52pub use connection::{Client, DevOverlaysClient};
53pub(crate) use connection::{build_options_string, default_sslmode, is_loopback_host};
54
55/// Double-quote a SQL identifier, escaping any embedded double quotes.
56pub fn quote_identifier(name: &str) -> String {
57    format!("\"{}\"", name.replace('"', "\"\""))
58}
59
60/// Build a comma-separated `$1, $2, …, $n` placeholder string for parameterized queries.
61pub fn sql_placeholders(n: usize) -> String {
62    (1..=n)
63        .map(|i| format!("${}", i))
64        .collect::<Vec<_>>()
65        .join(", ")
66}
67
68/// Build a `LIKE` pattern (used with `ESCAPE '\'`) matching any name that ends
69/// in the staging suffix `_<deploy_id>`.
70///
71/// The suffix is matched *literally*: `_`, `%`, and the escape character `\` are
72/// LIKE metacharacters, so they are escaped. Only the leading `%` stays a
73/// wildcard. Without escaping, the `_` separating the suffix would act as a
74/// single-character wildcard — pattern `%_prod` would match any name ending in
75/// `<any char>prod` (e.g. a production schema `fooprod` or cluster `dataprod`),
76/// and a `deploy_id` containing `%` would match nearly everything. Used by both
77/// the staging-discovery queries (which feed `DROP ... CASCADE`) and the
78/// hydration-status / `wait` readiness queries.
79pub(crate) fn staging_suffix_like_pattern(deploy_id: &str) -> String {
80    let mut pattern = String::from("%");
81    // The literal suffix is the separating underscore followed by the deploy id.
82    for ch in std::iter::once('_').chain(deploy_id.chars()) {
83        if matches!(ch, '\\' | '_' | '%') {
84            pattern.push('\\');
85        }
86        pattern.push(ch);
87    }
88    pattern
89}
90
91#[cfg(test)]
92mod tests {
93    use super::staging_suffix_like_pattern;
94
95    #[mz_ore::test]
96    fn test_staging_suffix_like_pattern_escapes_separator() {
97        // Regression test for QA Finding 3.
98        //
99        // The `_` separating the staging suffix must be escaped so it matches a
100        // literal underscore, not a single-character wildcard. With deploy id
101        // `prod` the pattern must be `%\_prod` (used with `ESCAPE '\'`), which
102        // matches only names ending in the literal `_prod` — NOT `fooprod` or any
103        // other `<char>prod`, which the unescaped `%_prod` would have matched.
104        assert_eq!(staging_suffix_like_pattern("prod"), r"%\_prod");
105    }
106
107    #[mz_ore::test]
108    fn test_staging_suffix_like_pattern_escapes_metacharacters() {
109        // A deploy id containing LIKE metacharacters must not inject wildcards.
110        // `%` and `_` inside the id are escaped to literals; the only wildcard is
111        // the leading `%`.
112        assert_eq!(staging_suffix_like_pattern("a%b_c"), r"%\_a\%b\_c");
113        // Backslashes (the escape char itself) are also escaped.
114        assert_eq!(staging_suffix_like_pattern(r"a\b"), r"%\_a\\b");
115    }
116
117    #[mz_ore::test]
118    fn test_staging_suffix_like_pattern_plain_id() {
119        // A plain alphanumeric id only escapes the separating underscore.
120        assert_eq!(staging_suffix_like_pattern("deploy123"), r"%\_deploy123");
121    }
122}
123pub use deployment_ops::{
124    ClusterDeploymentStatus, ClusterStatusContext, DEFAULT_ALLOWED_LAG_SECS, FailureReason,
125    HydrationStatusUpdate,
126};
127pub use errors::{ConnectionError, DatabaseValidationError, format_relative_path};
128pub use introspection::DependentSink;
129pub use models::{
130    ApplyState, Cluster, ClusterConfig, ClusterOptions, ClusterReplica, ConflictRecord,
131    DeploymentDetails, DeploymentHistoryEntry, DeploymentKind, DeploymentMetadata, DeploymentMode,
132    DeploymentObjectRecord, ObjectGrant, PendingStatement, ProductionClusterRecord,
133    ReplacementMvRecord, SchemaDeploymentRecord, StagingDeployment,
134};
mz_deploy/client.rs

mz_deploy/
client.rs
