1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
use std::io;
use thiserror::Error as ThisError;
use crate::handles::{Diagnostics, Record as DiagnosticRecord, SqlResult, log_diagnostics};
/// Error indicating a failed allocation for a column buffer
#[derive(Debug)]
pub struct TooLargeBufferSize {
/// Number of elements supposed to be in the buffer.
pub num_elements: usize,
/// Element size in the buffer in bytes.
pub element_size: usize,
}
impl TooLargeBufferSize {
/// Map the column allocation error to an [`crate::Error`] adding the context of which
/// column caused the allocation error.
pub fn add_context(self, buffer_index: u16) -> Error {
Error::TooLargeColumnBufferSize {
buffer_index,
num_elements: self.num_elements,
element_size: self.element_size,
}
}
}
#[cfg(feature = "odbc_version_3_5")]
const ODBC_VERSION_STRING: &str = "3.5";
#[cfg(not(feature = "odbc_version_3_5"))]
const ODBC_VERSION_STRING: &str = "3.80";
#[derive(Debug, ThisError)]
/// Error type used to indicate a low level ODBC call returned with SQL_ERROR.
pub enum Error {
/// Setting connection pooling option failed. Exclusively emitted by
/// [`crate::Environment::set_connection_pooling`].
#[error("Failed to set connection pooling.")]
FailedSettingConnectionPooling,
/// Allocating the environment itself fails. Further diagnostics are not available, as they
/// would be retrieved using the envirorment handle. Exclusively emitted by
/// [`crate::Environment::new`].
#[error("Failed to allocate ODBC Environment.")]
FailedAllocatingEnvironment,
/// This should never happen, given that ODBC driver manager and ODBC driver do not have any
/// Bugs. Since we may link vs a bunch of these, better to be on the safe side.
#[error(
"No Diagnostics available. The ODBC function call to {} returned an error. Sadly neither \
the ODBC driver manager, nor the driver were polite enough to leave a diagnostic record \
specifying what exactly went wrong.",
function
)]
NoDiagnostics {
/// ODBC API call which returned error without producing a diagnostic record.
function: &'static str,
},
/// SQL Error had been returned by a low level ODBC function call. A Diagnostic record is
/// obtained and associated with this error.
#[error("ODBC emitted an error calling '{function}':\n{record}")]
Diagnostics {
/// Diagnostic record returned by the ODBC driver manager
record: DiagnosticRecord,
/// ODBC API call which produced the diagnostic record
function: &'static str,
},
/// A user dialog to complete the connection string has been aborted.
#[error("The dialog shown to provide or complete the connection string has been aborted.")]
AbortedConnectionStringCompletion,
/// An error returned if we fail to set the ODBC version
#[error(
"The ODBC diver manager installed in your system does not seem to support ODBC API version \
{ODBC_VERSION_STRING}. Which is required by this application. Most likely you need to \
update your driver manager. Your driver manager is most likely unixODBC if you run on a \
Linux. Diagnostic record returned by SQLSetEnvAttr:\n{0}"
)]
UnsupportedOdbcApiVersion(DiagnosticRecord),
/// An error emitted by an `std::io::ReadBuf` implementation used as an input argument.
#[error("Sending data to the database at statement execution time failed. IO error:\n{0}")]
FailedReadingInput(io::Error),
/// Driver returned "invalid attribute" then setting the row array size. Most likely the array
/// size is too large. Instead of returing "option value changed (SQLSTATE 01S02)" as suggested
/// in <https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlsetstmtattr-function> the
/// driver returned an error instead.
#[error(
"An invalid row array size (aka. batch size) has been set. The ODBC drivers should just \
emit a warning and emmit smaller batches, but not all do (yours does not at least). Try \
fetching data from the database in smaller batches.\nRow array size (aka. batch size): \
{size}\n Diagnostic record returned by SQLSetEnvAttr:\n{record}"
)]
InvalidRowArraySize {
record: DiagnosticRecord,
size: usize,
},
#[error(
"Tried to retrieve a value from the database. The value turned out to be `NULL` yet this \
turned out to not be representable. So the application is written as if the value could \
never be `NULL` in the datasource, yet the in actuallity a `NULL` has been returned. \
Diagnostic record returned:\n{0}"
)]
UnableToRepresentNull(DiagnosticRecord),
/// There are plenty of issues in the net about Oracle ODBC driver not supporting 64Bit. This
/// message, should make it easier identify what is going on, since the message emmitted by,
/// Oracles ODBC driver is a bit cryptic: `[Oracle][ODBC]Invalid SQL data type <-25>`.
#[error(
"SQLFetch came back with an error indicating you specified an invalid SQL Type. You very \
likely did not do that however. Actually SQLFetch is not supposed to return that error \
type. You should have received it back than you were still binding columns or parameters. \
All this is circumstancial evidence that you are using an Oracle Database and want to use \
64Bit integers, which are not supported by Oracles ODBC driver manager. In case this \
diagnose is wrong the original error is:\n{0}."
)]
OracleOdbcDriverDoesNotSupport64Bit(DiagnosticRecord),
#[error(
"There is not enough memory to allocate enough memory for a column buffer. Number of \
elements requested for the column buffer: {num_elements}; Size needed to hold the largest \
possible element: {element_size}."
)]
TooLargeColumnBufferSize {
/// Zero based column buffer index. Note that this is different from the 1 based column
/// index.
buffer_index: u16,
num_elements: usize,
/// `usize::MAX` may be used to indicate a missing aupper bound of an element.
element_size: usize,
},
#[error(
"A value (at least one) is too large to be written into the allocated buffer without \
truncation. Size in bytes indicated by ODBC driver: {indicator:?}"
)]
TooLargeValueForBuffer {
/// Length of the complete value in bytes as reported by the ODBC driver. If the length is
/// not known, this is `None`.
indicator: Option<usize>,
/// Index of the buffer in which the truncation occurred.
buffer_index: usize,
},
}
impl Error {
/// Allows for mapping the error variant from the "catch all" diagnostic to a more specific one
/// offering the oppertunity to provide context in the error message.
fn provide_context_for_diagnostic<F>(self, f: F) -> Self
where
F: FnOnce(DiagnosticRecord, &'static str) -> Error,
{
if let Error::Diagnostics { record, function } = self {
f(record, function)
} else {
self
}
}
}
/// Convinience for easily providing more context to errors without an additional call to `map_err`
pub(crate) trait ExtendResult {
fn provide_context_for_diagnostic<F>(self, f: F) -> Self
where
F: FnOnce(DiagnosticRecord, &'static str) -> Error;
}
impl<T> ExtendResult for Result<T, Error> {
fn provide_context_for_diagnostic<F>(self, f: F) -> Self
where
F: FnOnce(DiagnosticRecord, &'static str) -> Error,
{
self.map_err(|error| error.provide_context_for_diagnostic(f))
}
}
impl SqlResult<()> {
/// Use this instead of [`Self::into_result`] if you expect [`SqlResult::NoData`] to be a
/// valid value. [`SqlResult::NoData`] is mapped to `Ok(false)`, all other success values are
/// `Ok(true)`.
pub fn into_result_bool(self, handle: &impl Diagnostics) -> Result<bool, Error> {
self.on_success(|| true)
.on_no_data(|| false)
.into_result(handle)
}
}
// Define that here rather than in `sql_result` mod to keep the `handles` module entirely agnostic
// about the top level `Error` type.
impl<T> SqlResult<T> {
/// `true` for [`Self::SuccessWithInfo`] and [`Self::Error`]. If `true` one might expect
/// diagnostic records to be present. If `false` it would indicate their absense.
pub fn has_diganostics(&self) -> bool {
matches!(
self,
SqlResult::SuccessWithInfo(_) | SqlResult::Error { function: _ }
)
}
/// [`Self::Success`] and [`Self::SuccessWithInfo`] are mapped to Ok. In case of
/// [`Self::SuccessWithInfo`] any diagnostics are logged. [`Self::Error`] is mapped to error.
/// Other states [`Self::NoData]` and [`Self::NeedData`] would lead to a panic. Most ODBC
/// functions are not suppossed to return these status codes.
pub fn into_result(self, handle: &impl Diagnostics) -> Result<T, Error> {
if self.has_diganostics() {
log_diagnostics(handle);
}
self.into_result_without_logging(handle)
}
/// [`Self::Success`] and [`Self::SuccessWithInfo`] are mapped to Ok. [`Self::Error`] is mapped
/// to error. Other states [`Self::NoData]` and [`Self::NeedData`] would lead to a panic. Most
/// ODBC functions are not suppossed to return these status codes.
///
/// In case of [`Self::Error`] or [`Self::SuccessWithInfo`] no logging of diagnostic records is
/// performed by this method. You may want to use [Self::into_result`] instead.
pub fn into_result_without_logging(self, handle: &impl Diagnostics) -> Result<T, Error> {
match self {
// The function has been executed successfully. Holds result.
SqlResult::Success(value) | SqlResult::SuccessWithInfo(value) => Ok(value),
SqlResult::Error { function } => {
let mut record = DiagnosticRecord::with_capacity(512);
if record.fill_from(handle, 1) {
Err(Error::Diagnostics { record, function })
} else {
// Anecdotal ways to reach this code paths:
//
// * Inserting a 64Bit integers into an Oracle Database.
// * Specifying invalid drivers (e.g. missing .so the driver itself depends on)
Err(Error::NoDiagnostics { function })
}
}
SqlResult::NoData => {
panic!(
"Unexepcted SQL_NO_DATA returned by ODBC function. Use `SqlResult::on_no_data` \
to handle it."
)
}
SqlResult::NeedData => {
panic!(
"Unexpected SQL_NEED_DATA returned by ODBC function. Use \
`SqlResult::on_need_data` to handle it."
)
}
SqlResult::StillExecuting => panic!(
"SqlResult must not be converted to result while the function is still executing."
),
}
}
/// Maps [`SqlResult::Success`] and [`SqlResult::SuccessWithInfo`] to `Some`. Maps
/// [`SqlResult::NoData`] to [`SqlResult::Success`] with `None`.
pub fn or_no_data(self) -> SqlResult<Option<T>> {
self.map(Some).on_no_data(|| None)
}
}