scylla/
lib.rs

1//! Async Rust driver for the [Scylla](https://scylladb.com) database written in Rust.
2//! Although optimized for Scylla, the driver is also compatible with [Apache Cassandra®](https://cassandra.apache.org/).
3//!
4//! # Documentation book
5//! The best source to learn about this driver is the [documentation book](https://rust-driver.docs.scylladb.com/).\
6//! This page contains mainly API documentation
7//!
8//! # Other documentation
9//! * [Documentation book](https://rust-driver.docs.scylladb.com/)
10//! * [Examples](https://github.com/scylladb/scylla-rust-driver/tree/main/examples)
11//! * [Scylla documentation](https://docs.scylladb.com)
12//! * [Cassandra® documentation](https://cassandra.apache.org/doc/latest/)
13//!
14//! # Driver overview
15//! ### Connecting
16//! All driver activity revolves around the [Session](crate::client::session::Session)\
17//! `Session` is created by specifying a few known nodes and connecting to them:
18//!
19//! ```rust,no_run
20//! use scylla::client::session::Session;
21//! use scylla::client::session_builder::SessionBuilder;
22//! use std::error::Error;
23//!
24//! #[tokio::main]
25//! async fn main() -> Result<(), Box<dyn Error>> {
26//!    let session: Session = SessionBuilder::new()
27//!         .known_node("127.0.0.1:9042")
28//!         .known_node("1.2.3.4:9876")
29//!         .build()
30//!         .await?;
31//!
32//!    Ok(())
33//! }
34//! ```
35//! `Session` is usually created using the [SessionBuilder](crate::client::session_builder::SessionBuilder).\
36//! All configuration options for a `Session` can be specified while building.
37//!
38//! ### Making queries
39//! After successfully connecting to the cluster we can make queries.\
40//! The driver supports multiple query types:
41//! * [Simple](crate::client::session::Session::query_unpaged)
42//! * [Simple paged](crate::client::session::Session::query_iter)
43//! * [Prepared](crate::client::session::Session::execute_unpaged) (need to be [prepared](crate::client::session::Session::prepare) before use)
44//! * [Prepared paged](crate::client::session::Session::execute_iter)
45//! * [Batch](crate::client::session::Session::batch)
46//!
47//! To specify options for a single query create the query object and configure it:
48//! * For simple: [`Statement`](crate::statement::unprepared::Statement)
49//! * For prepared: [`PreparedStatement`](crate::statement::prepared::PreparedStatement)
50//! * For batch: [`Batch`](crate::statement::batch::Batch)
51//!
52//! The easiest way to specify bound values in a query is using a tuple:
53//! ```rust
54//! # use scylla::client::session::Session;
55//! # use std::error::Error;
56//! # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
57//! // Insert an int and text into the table
58//! session
59//!     .query_unpaged(
60//!         "INSERT INTO ks.tab (a, b) VALUES(?, ?)",
61//!         (2_i32, "some text")
62//!     )
63//!     .await?;
64//! # Ok(())
65//! # }
66//! ```
67//! But the driver will accept anything implementing the trait [SerializeRow].
68//!
69//! ### Receiving results
70//! The easiest way to read rows returned by a query is to cast each row to a tuple of values:
71//!
72//! ```rust
73//! # use scylla::client::session::Session;
74//! # use std::error::Error;
75//! # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
76//!
77//! // Read rows containing an int and text
78//! // Keep in mind that all results come in one response (no paging is done!),
79//! // so the memory footprint and latency may be huge!
80//! // To prevent that, use `Session::query_iter` or `Session::query_single_page`.
81//! let query_rows = session
82//!     .query_unpaged("SELECT a, b FROM ks.tab", &[])
83//!     .await?
84//!     .into_rows_result()?;
85//!
86//! for row in query_rows.rows()? {
87//!     // Parse row as int and text \
88//!     let (int_val, text_val): (i32, &str) = row?;
89//! }
90//! # Ok(())
91//! # }
92//! ```
93//! See the [book](https://rust-driver.docs.scylladb.com/stable/statements/result.html) for more receiving methods
94
95#![cfg_attr(docsrs, feature(doc_auto_cfg))]
96
97#[doc(hidden)]
98pub mod _macro_internal {
99    pub use scylla_cql::_macro_internal::*;
100}
101
102pub use scylla_cql::{DeserializeRow, DeserializeValue, SerializeRow, SerializeValue};
103
104pub mod value {
105    // Every `pub` item is re-exported here, apart from `deser_cql_value`.
106    pub use scylla_cql::value::{
107        Counter, CqlDate, CqlDecimal, CqlDecimalBorrowed, CqlDuration, CqlTime, CqlTimestamp,
108        CqlTimeuuid, CqlValue, CqlVarint, CqlVarintBorrowed, MaybeUnset, Row, Unset, ValueOverflow,
109    };
110}
111
112pub mod frame {
113    pub use scylla_cql::frame::{frame_errors, Authenticator, Compression};
114    pub(crate) use scylla_cql::frame::{
115        parse_response_body_extensions, protocol_features, read_response_frame, request,
116        server_event_type, FrameParams, SerializedRequest,
117    };
118
119    pub mod types {
120        pub use scylla_cql::frame::types::{Consistency, SerialConsistency};
121    }
122
123    pub mod response {
124        pub(crate) use scylla_cql::frame::response::*;
125
126        pub mod result {
127            #[cfg(cpp_rust_unstable)]
128            pub use scylla_cql::frame::response::result::DeserializedMetadataAndRawRows;
129
130            pub(crate) use scylla_cql::frame::response::result::*;
131            pub use scylla_cql::frame::response::result::{
132                CollectionType, ColumnSpec, ColumnType, NativeType, PartitionKeyIndex, TableSpec,
133                UserDefinedType,
134            };
135        }
136    }
137}
138
139/// Serializing bound values of a query to be sent to the DB.
140// Note: When editing comment on submodules here edit corresponding comments
141// on scylla-cql modules too.
142pub mod serialize {
143    pub use scylla_cql::serialize::SerializationError;
144    /// Contains the [BatchValues][batch::BatchValues] and [BatchValuesIterator][batch::BatchValuesIterator] trait and their
145    /// implementations.
146    pub mod batch {
147        // Main types
148        pub use scylla_cql::serialize::batch::{
149            BatchValues, BatchValuesFromIterator, BatchValuesIterator,
150            BatchValuesIteratorFromIterator, TupleValuesIter,
151        };
152    }
153
154    /// Contains the [SerializeRow][row::SerializeRow] trait and its implementations.
155    pub mod row {
156        // Main types
157        pub use scylla_cql::serialize::row::{RowSerializationContext, SerializeRow};
158
159        // Errors
160        pub use scylla_cql::serialize::row::{
161            BuiltinSerializationError, BuiltinSerializationErrorKind, BuiltinTypeCheckError,
162            BuiltinTypeCheckErrorKind,
163        };
164    }
165
166    /// Contains the [SerializeValue][value::SerializeValue] trait and its implementations.
167    pub mod value {
168        // Main types
169        pub use scylla_cql::serialize::value::SerializeValue;
170
171        // Errors
172        pub use scylla_cql::serialize::value::{
173            BuiltinSerializationError, BuiltinSerializationErrorKind, BuiltinTypeCheckError,
174            BuiltinTypeCheckErrorKind, MapSerializationErrorKind, MapTypeCheckErrorKind,
175            SetOrListSerializationErrorKind, SetOrListTypeCheckErrorKind,
176            TupleSerializationErrorKind, TupleTypeCheckErrorKind, UdtSerializationErrorKind,
177            UdtTypeCheckErrorKind,
178        };
179    }
180
181    /// Contains types and traits used for safe serialization of values for a CQL statement.
182    pub mod writers {
183        pub use scylla_cql::serialize::writers::{
184            CellOverflowError, CellValueBuilder, CellWriter, RowWriter, WrittenCellProof,
185        };
186    }
187}
188
189/// Deserializing DB response containing CQL query results.
190pub mod deserialize {
191    pub use scylla_cql::deserialize::{DeserializationError, FrameSlice, TypeCheckError};
192
193    /// Deserializing the whole query result contents.
194    pub mod result {
195        pub use scylla_cql::deserialize::result::TypedRowIterator;
196    }
197
198    /// Deserializing a row of the query result.
199    pub mod row {
200        pub use scylla_cql::deserialize::row::{
201            BuiltinDeserializationError, BuiltinDeserializationErrorKind, BuiltinTypeCheckError,
202            BuiltinTypeCheckErrorKind, ColumnIterator, DeserializeRow, RawColumn,
203        };
204    }
205
206    /// Deserializing a single CQL value from a column of the query result row.
207    pub mod value {
208        pub use scylla_cql::deserialize::value::{
209            BuiltinDeserializationError, BuiltinDeserializationErrorKind, BuiltinTypeCheckError,
210            BuiltinTypeCheckErrorKind, DeserializeValue, Emptiable, ListlikeIterator,
211            MapDeserializationErrorKind, MapIterator, MapTypeCheckErrorKind, MaybeEmpty,
212            SetOrListDeserializationErrorKind, SetOrListTypeCheckErrorKind,
213            TupleDeserializationErrorKind, TupleTypeCheckErrorKind, UdtIterator,
214            UdtTypeCheckErrorKind,
215        };
216    }
217
218    // Shorthands for better readability.
219    pub(crate) trait DeserializeOwnedRow:
220        for<'frame, 'metadata> row::DeserializeRow<'frame, 'metadata>
221    {
222    }
223    impl<T> DeserializeOwnedRow for T where
224        T: for<'frame, 'metadata> row::DeserializeRow<'frame, 'metadata>
225    {
226    }
227}
228
229pub mod authentication;
230pub mod client;
231#[cfg(feature = "unstable-cloud")]
232pub mod cloud;
233
234pub mod cluster;
235pub mod errors;
236mod network;
237pub mod observability;
238pub mod policies;
239pub mod response;
240pub mod routing;
241pub mod statement;
242
243pub(crate) mod utils;
244
245#[cfg(test)]
246pub(crate) use utils::test_utils;
247
248#[cfg(feature = "unstable-testing")]
249#[doc(hidden)]
250pub mod internal_testing {
251    use scylla_cql::serialize::row::SerializedValues;
252
253    use crate::routing::partitioner::PartitionerName;
254    use crate::routing::Token;
255    use crate::statement::prepared::TokenCalculationError;
256
257    pub fn calculate_token_for_partition_key(
258        serialized_partition_key_values: &SerializedValues,
259        partitioner: &PartitionerName,
260    ) -> Result<Token, TokenCalculationError> {
261        crate::routing::partitioner::calculate_token_for_partition_key(
262            serialized_partition_key_values,
263            partitioner,
264        )
265    }
266}
scylla/lib.rs

scylla/
lib.rs
