cdbc_mysql/options/
mod.rs

1use std::path::{Path, PathBuf};
2
3mod connect;
4mod parse;
5mod ssl_mode;
6
7use cdbc::{net::CertificateInput};
8pub use ssl_mode::MySqlSslMode;
9
10/// Options and flags which can be used to configure a MySQL connection.
11///
12/// A value of `MySqlConnectOptions` can be parsed from a connection URI,
13/// as described by [MySQL](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-jdbc-url-format.html).
14///
15/// The generic format of the connection URL:
16///
17/// ```text
18/// mysql://[host][/database][?properties]
19/// ```
20///
21/// ## Properties
22///
23/// |Parameter|Default|Description|
24/// |---------|-------|-----------|
25/// | `ssl-mode` | `PREFERRED` | Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated. See [`MySqlSslMode`]. |
26/// | `ssl-ca` | `None` | Sets the name of a file containing a list of trusted SSL Certificate Authorities. |
27/// | `statement-cache-capacity` | `100` | The maximum number of prepared statements stored in the cache. Set to `0` to disable. |
28/// | `socket` | `None` | Path to the unix domain socket, which will be used instead of TCP if set. |
29///
30/// # Example
31///
32/// ```rust,no_run
33/// # use cdbc::error::Error;
34/// # use cdbc::connection::{Connection, ConnectOptions};
35/// # use cdbc_mysql::::{MySqlConnectOptions, MySqlConnection, MySqlSslMode};
36/// #
37/// # fn main() ->Result<()>{
38/// // URI connection string
39/// let conn = MySqlConnection::connect("mysql://root:password@localhost/db")?;
40///
41/// // Manually-constructed options
42/// let conn = MySqlConnectOptions::new()
43///     .host("localhost")
44///     .username("root")
45///     .password("password")
46///     .database("db")
47///     .connect()?;
48///      Ok(())
49/// # }
50/// ```
51#[derive(Debug, Clone)]
52pub struct MySqlConnectOptions {
53    pub host: String,
54    pub port: u16,
55    pub socket: Option<PathBuf>,
56    pub username: String,
57    pub password: Option<String>,
58    pub database: Option<String>,
59    pub ssl_mode: MySqlSslMode,
60    pub ssl_ca: Option<CertificateInput>,
61    pub statement_cache_capacity: usize,
62    pub charset: String,
63    pub collation: Option<String>,
64}
65
66impl Default for MySqlConnectOptions {
67    fn default() -> Self {
68        Self::new()
69    }
70}
71
72impl MySqlConnectOptions {
73    /// Creates a new, default set of options ready for configuration
74    pub fn new() -> Self {
75        Self {
76            port: 3306,
77            host: String::from("localhost"),
78            socket: None,
79            username: String::from("root"),
80            password: None,
81            database: None,
82            charset: String::from("utf8mb4"),
83            collation: None,
84            ssl_mode: MySqlSslMode::Disabled,
85            ssl_ca: None,
86            statement_cache_capacity: 100,
87        }
88    }
89
90    /// Sets the name of the host to connect to.
91    ///
92    /// The default behavior when the host is not specified,
93    /// is to connect to localhost.
94    pub fn host(mut self, host: &str) -> Self {
95        self.host = host.to_owned();
96        self
97    }
98
99    /// Sets the port to connect to at the server host.
100    ///
101    /// The default port for MySQL is `3306`.
102    pub fn port(mut self, port: u16) -> Self {
103        self.port = port;
104        self
105    }
106
107    /// Pass a path to a Unix socket. This changes the connection stream from
108    /// TCP to UDS.
109    ///
110    /// By default set to `None`.
111    pub fn socket(mut self, path: impl AsRef<Path>) -> Self {
112        self.socket = Some(path.as_ref().to_path_buf());
113        self
114    }
115
116    /// Sets the username to connect as.
117    pub fn username(mut self, username: &str) -> Self {
118        self.username = username.to_owned();
119        self
120    }
121
122    /// Sets the password to connect with.
123    pub fn password(mut self, password: &str) -> Self {
124        self.password = Some(password.to_owned());
125        self
126    }
127
128    /// Sets the database name.
129    pub fn database(mut self, database: &str) -> Self {
130        self.database = Some(database.to_owned());
131        self
132    }
133
134    /// Sets whether or with what priority a secure SSL TCP/IP connection will be negotiated
135    /// with the server.
136    ///
137    /// By default, the SSL mode is [`Preferred`](MySqlSslMode::Preferred), and the client will
138    /// first attempt an SSL connection but fallback to a non-SSL connection on failure.
139    ///
140    /// # Example
141    ///
142    /// ```rust
143    /// # use cdbc_mysql::::{MySqlSslMode, MySqlConnectOptions};
144    /// let options = MySqlConnectOptions::new()
145    ///     .ssl_mode(MySqlSslMode::Required);
146    /// ```
147    pub fn ssl_mode(mut self, mode: MySqlSslMode) -> Self {
148        self.ssl_mode = mode;
149        self
150    }
151
152    /// Sets the name of a file containing a list of trusted SSL Certificate Authorities.
153    ///
154    /// # Example
155    ///
156    /// ```rust
157    /// # use cdbc_mysql::::{MySqlSslMode, MySqlConnectOptions};
158    /// let options = MySqlConnectOptions::new()
159    ///     .ssl_mode(MySqlSslMode::VerifyCa)
160    ///     .ssl_ca("path/to/ca.crt");
161    /// ```
162    pub fn ssl_ca(mut self, file_name: impl AsRef<Path>) -> Self {
163        self.ssl_ca = Some(CertificateInput::File(file_name.as_ref().to_owned()));
164        self
165    }
166
167    /// Sets PEM encoded list of trusted SSL Certificate Authorities.
168    ///
169    /// # Example
170    ///
171    /// ```rust
172    /// # use cdbc_mysql::::{MySqlSslMode, MySqlConnectOptions};
173    /// let options = MySqlConnectOptions::new()
174    ///     .ssl_mode(MySqlSslMode::VerifyCa)
175    ///     .ssl_ca_from_pem(vec![]);
176    /// ```
177    pub fn ssl_ca_from_pem(mut self, pem_certificate: Vec<u8>) -> Self {
178        self.ssl_ca = Some(CertificateInput::Inline(pem_certificate));
179        self
180    }
181
182    /// Sets the capacity of the connection's statement cache in a number of stored
183    /// distinct statements. Caching is handled using LRU, meaning when the
184    /// amount of queries hits the defined limit, the oldest statement will get
185    /// dropped.
186    ///
187    /// The default cache capacity is 100 statements.
188    pub fn statement_cache_capacity(mut self, capacity: usize) -> Self {
189        self.statement_cache_capacity = capacity;
190        self
191    }
192
193    /// Sets the character set for the connection.
194    ///
195    /// The default character set is `utf8mb4`. This is supported from MySQL 5.5.3.
196    /// If you need to connect to an older version, we recommend you to change this to `utf8`.
197    pub fn charset(mut self, charset: &str) -> Self {
198        self.charset = charset.to_owned();
199        self
200    }
201
202    /// Sets the collation for the connection.
203    ///
204    /// The default collation is derived from the `charset`. Normally, you should only have to set
205    /// the `charset`.
206    pub fn collation(mut self, collation: &str) -> Self {
207        self.collation = Some(collation.to_owned());
208        self
209    }
210}
cdbc_mysql/options/mod.rs

cdbc_mysql/options/
mod.rs
