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
51use mz_sql_parser::ast::{CreateClusterStatement, Raw, Statement};
52use mz_sql_parser::parser::parse_statements;
53
54pub use crate::config::Profile;
55pub use connection::{Client, DevOverlaysClient};
56pub(crate) use connection::{build_options_string, default_sslmode, is_loopback_host};
57
58/// Double-quote a SQL identifier, escaping any embedded double quotes.
59pub fn quote_identifier(name: &str) -> String {
60    format!("\"{}\"", name.replace('"', "\"\""))
61}
62
63/// Parse the `create_sql` column of a `SHOW CREATE CLUSTER` result.
64pub fn parse_create_cluster(sql: &str) -> Result<CreateClusterStatement<Raw>, String> {
65    let statements = parse_statements(sql)
66        .map_err(|e| format!("failed to parse SHOW CREATE CLUSTER output: {}", e.error))?;
67    match statements.into_iter().next().map(|statement| statement.ast) {
68        Some(Statement::CreateCluster(create)) => Ok(create),
69        Some(other) => Err(format!("expected CREATE CLUSTER, got: {}", other)),
70        None => Err("SHOW CREATE CLUSTER returned empty SQL".to_string()),
71    }
72}
73
74/// Build a comma-separated `$1, $2, …, $n` placeholder string for parameterized queries.
75pub fn sql_placeholders(n: usize) -> String {
76    (1..=n)
77        .map(|i| format!("${}", i))
78        .collect::<Vec<_>>()
79        .join(", ")
80}
81
82/// Build a `LIKE` pattern (used with `ESCAPE '\'`) matching any name that ends
83/// in the staging suffix `_<deploy_id>`.
84///
85/// The suffix is matched *literally*: `_`, `%`, and the escape character `\` are
86/// LIKE metacharacters, so they are escaped. Only the leading `%` stays a
87/// wildcard. Without escaping, the `_` separating the suffix would act as a
88/// single-character wildcard — pattern `%_prod` would match any name ending in
89/// `<any char>prod` (e.g. a production schema `fooprod` or cluster `dataprod`),
90/// and a `deploy_id` containing `%` would match nearly everything. Used by both
91/// the staging-discovery queries (which feed `DROP ... CASCADE`) and the
92/// hydration-status / `wait` readiness queries.
93pub(crate) fn staging_suffix_like_pattern(deploy_id: &str) -> String {
94    let mut pattern = String::from("%");
95    // The literal suffix is the separating underscore followed by the deploy id.
96    for ch in std::iter::once('_').chain(deploy_id.chars()) {
97        if matches!(ch, '\\' | '_' | '%') {
98            pattern.push('\\');
99        }
100        pattern.push(ch);
101    }
102    pattern
103}
104
105#[cfg(test)]
106mod tests {
107    use super::staging_suffix_like_pattern;
108
109    #[mz_ore::test]
110    fn test_staging_suffix_like_pattern_escapes_separator() {
111        // Regression test for QA Finding 3.
112        //
113        // The `_` separating the staging suffix must be escaped so it matches a
114        // literal underscore, not a single-character wildcard. With deploy id
115        // `prod` the pattern must be `%\_prod` (used with `ESCAPE '\'`), which
116        // matches only names ending in the literal `_prod` — NOT `fooprod` or any
117        // other `<char>prod`, which the unescaped `%_prod` would have matched.
118        assert_eq!(staging_suffix_like_pattern("prod"), r"%\_prod");
119    }
120
121    #[mz_ore::test]
122    fn test_staging_suffix_like_pattern_escapes_metacharacters() {
123        // A deploy id containing LIKE metacharacters must not inject wildcards.
124        // `%` and `_` inside the id are escaped to literals; the only wildcard is
125        // the leading `%`.
126        assert_eq!(staging_suffix_like_pattern("a%b_c"), r"%\_a\%b\_c");
127        // Backslashes (the escape char itself) are also escaped.
128        assert_eq!(staging_suffix_like_pattern(r"a\b"), r"%\_a\\b");
129    }
130
131    #[mz_ore::test]
132    fn test_staging_suffix_like_pattern_plain_id() {
133        // A plain alphanumeric id only escapes the separating underscore.
134        assert_eq!(staging_suffix_like_pattern("deploy123"), r"%\_deploy123");
135    }
136}
137pub use deployment_ops::{
138    ClusterDeploymentStatus, ClusterStatusContext, DEFAULT_ALLOWED_LAG_SECS, FailureReason,
139    HydrationStatusUpdate,
140};
141pub use errors::{ConnectionError, DatabaseValidationError, format_relative_path};
142pub use introspection::DependentSink;
143pub use models::{
144    ApplyState, Cluster, ClusterConfig, ClusterReplica, ConflictRecord, DeploymentDetails,
145    DeploymentHistoryEntry, DeploymentKind, DeploymentMetadata, DeploymentMode,
146    DeploymentObjectRecord, ObjectGrant, PendingStatement, ProductionClusterRecord,
147    ReplacementMvRecord, SchemaDeploymentRecord, StagingDeployment,
148};
mz_deploy/client.rs

mz_deploy/
client.rs
