chdb_rust/version.rs
1//! Which engine this build carries.
2//!
3//! Three accessors, each reporting exactly one versioning scheme. Nothing here
4//! falls back to another scheme when its own source is unavailable: a chdb-core
5//! release number and a ClickHouse version number cannot be compared, so
6//! answering one question with the other number is worse than answering with an
7//! error.
8//!
9//! | | scheme | resolved | example |
10//! | --- | --- | --- | --- |
11//! | [`EXPECTED_ENGINE_VERSION`] | chdb-core | at compile time | `26.7.0` |
12//! | [`engine_version`] | chdb-core | by the linked library | `26.7.0` |
13//! | [`clickhouse_version`] | ClickHouse | by a query | `26.5.1.1` |
14//!
15//! A chdb-core release number is not a ClickHouse one: `X.Y` is the ClickHouse
16//! minor line the release sits on and `Z` is chdb-core's own counter, so the two
17//! agree on the first two fields at most.
18
19use crate::error::{Error, Result};
20
21/// The chdb-core release this build fetched, without the leading `v`.
22///
23/// `None` when the build linked a library it did not fetch — a `CHDB_LIB_DIR`
24/// build, a copy already installed on the machine, a docs.rs build. The pinned
25/// version says nothing about an artifact that came from somewhere else, so this
26/// reports nothing rather than reporting the pin. [`ENGINE_SOURCE`] says where
27/// the library came from, and [`engine_version`] asks the library itself.
28///
29/// ```no_run
30/// use chdb_rust::version::{engine_version, EXPECTED_ENGINE_VERSION};
31///
32/// // A build that fetched its own engine can check the two agree.
33/// if let Some(expected) = EXPECTED_ENGINE_VERSION {
34/// assert_eq!(expected, engine_version()?);
35/// }
36/// # Ok::<(), chdb_rust::error::Error>(())
37/// ```
38pub const EXPECTED_ENGINE_VERSION: Option<&str> = {
39 let declared = env!("CHDB_EXPECTED_ENGINE_VERSION");
40 if declared.is_empty() {
41 None
42 } else {
43 Some(declared)
44 }
45};
46
47/// Where the linked library came from, as the build script resolved it.
48///
49/// One of `download: chdb-core <tag>`, `CHDB_LIB_DIR: <path>`,
50/// `local: <path>`, or `none: docs.rs build`. Diagnostic only — the shape is not
51/// part of the API.
52pub const ENGINE_SOURCE: &str = env!("CHDB_ENGINE_SOURCE");
53
54/// The chdb-core release the linked library reports, without the leading `v`.
55///
56/// This is the only accessor that describes the artifact actually loaded, which
57/// is what makes it the way to tell which engine a binary carries when the build
58/// did not fetch it.
59///
60/// # Errors
61///
62/// Returns [`Error::EngineVersionUnavailable`] when the library predates
63/// `chdb_version()`, which arrived in chdb-core v26.7.0.
64pub fn engine_version() -> Result<&'static str> {
65 #[cfg(has_chdb_version)]
66 {
67 // SAFETY: chdb_version() takes no arguments and returns a pointer to a
68 // string constant in the library, valid for as long as it is loaded.
69 let raw = unsafe { crate::bindings::chdb_version() };
70 if raw.is_null() {
71 return Err(Error::InvalidData(
72 "chdb_version() returned NULL".to_string(),
73 ));
74 }
75 unsafe { std::ffi::CStr::from_ptr(raw) }
76 .to_str()
77 .map_err(|e| Error::InvalidData(format!("chdb_version() is not UTF-8: {e}")))
78 }
79 #[cfg(not(has_chdb_version))]
80 {
81 Err(Error::EngineVersionUnavailable)
82 }
83}
84
85/// A fetched dynamic library may be shadowed by an older runtime installation.
86/// Only compare when the build itself resolved a release: a caller-supplied
87/// CHDB_LIB_DIR has no known version to assert against.
88pub(crate) fn verify_loaded_engine() -> Result<()> {
89 if let Some(expected) = EXPECTED_ENGINE_VERSION {
90 let reported = engine_version()?;
91 verify_engine_versions(expected, reported)?;
92 }
93 Ok(())
94}
95
96fn verify_engine_versions(expected: &str, reported: &str) -> Result<()> {
97 if reported != expected {
98 return Err(Error::InvalidData(format!(
99 "built against chdb-core {expected}, but loaded libchdb reports {reported}; check the runtime library search path"
100 )));
101 }
102 Ok(())
103}
104
105/// The ClickHouse version the linked engine reports, as `SELECT version()` gives
106/// it.
107///
108/// Opens a temporary in-memory connection, the same as [`crate::execute`]. Use
109/// `SELECT version()` on a connection you already hold if you have one.
110pub fn clickhouse_version() -> Result<String> {
111 let result = crate::execute("SELECT version()", None)?;
112 Ok(result.data_utf8()?.trim().to_string())
113}
114
115#[cfg(test)]
116mod version_guard_tests {
117 use super::*;
118
119 #[test]
120 fn runtime_mismatch_names_both_releases() {
121 let message = verify_engine_versions("26.11.0-rc.3", "26.7.3")
122 .unwrap_err()
123 .to_string();
124 assert!(message.contains("26.11.0-rc.3"));
125 assert!(message.contains("26.7.3"));
126 assert!(verify_engine_versions("26.11.0-rc.3", "26.11.0-rc.3").is_ok());
127 }
128}