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
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
/**
* [Connection Status Functions](https://www.postgresql.org/docs/current/libpq-status.html)
*/
impl Connection {
/**
* Returns the database name of the connection.
*
* See [PQdb](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQDB).
*/
pub fn db(&self) -> crate::errors::Result<String> {
crate::ffi::to_string(unsafe { pq_sys::PQdb(self.into()) })
}
/**
* Returns the user name of the connection.
*
* See [PQuser](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQUSER).
*/
pub fn user(&self) -> crate::errors::Result<String> {
crate::ffi::to_string(unsafe { pq_sys::PQuser(self.into()) })
}
/**
* Returns the password of the connection.
*
* See [PQpass](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQPASS).
*/
pub fn pass(&self) -> crate::errors::Result<Option<String>> {
crate::ffi::to_option_string(unsafe { pq_sys::PQpass(self.into()) })
}
/**
* Returns the server host name of the active connection.
*
* This can be a host name, an IP address, or a directory path if the connection is via Unix
* socket. (The path case can be distinguished because it will always be an absolute path,
* beginning with /.)
*
* See [PQhost](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQHOST).
*/
pub fn host(&self) -> crate::errors::Result<String> {
crate::ffi::to_string(unsafe { pq_sys::PQhost(self.into()) })
}
/**
* Returns the server IP address of the active connection.
*
* This can be the address that a host name resolved to, or an IP address provided through the
* hostaddr parameter.
*
* See [PQhostaddr](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQHOSTADDR).
*/
#[cfg(feature = "v12")]
pub fn hostaddr(&self) -> crate::errors::Result<String> {
crate::ffi::to_string(unsafe { pq_sys::PQhostaddr(self.into()) })
}
/**
* Returns the port of the active connection.
*
* See [PQport](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQPORT).
*/
pub fn port(&self) -> crate::errors::Result<String> {
crate::ffi::to_string(unsafe { pq_sys::PQport(self.into()) })
}
/**
* Returns the debug TTY of the connection.
*
* See [PQtty](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQTTY).
*/
#[deprecated(
note = "the server no longer pays attention to the TTY setting, but the function remains for backward compatibility."
)]
pub fn tty(&self) -> crate::errors::Result<Option<String>> {
crate::ffi::to_option_string(unsafe { pq_sys::PQtty(self.into()) })
}
/**
* Returns the command-line options passed in the connection request.
*
* See [PQoptions](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQOPTIONS).
*/
pub fn options(&self) -> crate::errors::Result<Option<String>> {
crate::ffi::to_option_string(unsafe { pq_sys::PQoptions(self.into()) })
}
/**
* Returns the status of the connection.
*
* See [PQstatus](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSTATUS).
*/
pub fn status(&self) -> crate::connection::Status {
unsafe { pq_sys::PQstatus(self.into()) }.into()
}
/**
* Returns the current in-transaction status of the server.
*
* See [PQtransactionStatus](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS).
*/
pub fn transaction_status(&self) -> crate::transaction::Status {
unsafe { pq_sys::PQtransactionStatus(self.into()) }.into()
}
/**
* Looks up a current parameter setting of the server.
*
* See [PQparameterStatus](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQPARAMETERSTATUS).
*/
pub fn parameter_status(&self, param: &str) -> crate::errors::Result<String> {
let c_param = crate::ffi::to_cstr(param);
crate::ffi::to_string(unsafe { pq_sys::PQparameterStatus(self.into(), c_param.as_ptr()) })
}
/**
* Interrogates the frontend/backend protocol being used.
*
* See [PQprotocolVersion](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQPROTOCOLVERSION).
*/
pub fn protocol_version(&self) -> i32 {
unsafe { pq_sys::PQprotocolVersion(self.into()) }
}
/**
* Returns an integer representing the server version.
*
* See [PQserverVersion](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSERVERVERSION).
*/
pub fn server_version(&self) -> i32 {
unsafe { pq_sys::PQserverVersion(self.into()) }
}
/**
* Returns the error message most recently generated by an operation on the connection.
*
* See [PQerrorMessage](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQERRORMESSAGE).
*
* # Implemenatation Notes:
* PQerrorMessage returns a localizable string, which depends on the locale settings and
* is it not guaranteed to be UTF-8 encoded.
*
* Since rust strings are UTF-8 encoded, if the error message cannot be converted to UTF-8,
* the returned string will not be the actual error message but
* "PQerrorMessage internal error: the error message is not UTF-8".
* You can get the actual error message, by changing your locale settings an UTF-8 compatible one.
*/
pub fn error_message(&self) -> Option<&str> {
let error = unsafe { pq_sys::PQerrorMessage(self.into()) };
if error.is_null() {
None
} else {
//SAFETY: the pointer is valid because we checked it above.
match unsafe { std::ffi::CStr::from_ptr(error) }.to_str() {
Ok(s) => Some(s),
Err(_) => Some("PQerrorMessage internal error: the error message is not UTF-8"),
}
}
}
/**
* Obtains the file descriptor number of the connection socket to the server.
*
* See [PQsocket](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSOCKET).
*/
pub fn socket(&self) -> crate::errors::Result<i32> {
let socket = unsafe { pq_sys::PQsocket(self.into()) };
if socket < 0 {
self.error()
} else {
Ok(socket)
}
}
/**
* Returns the process ID (PID) of the backend process handling this connection.
*
* See [PQbackendPID](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQBACKENDPID).
*/
pub fn backend_pid(&self) -> u32 {
unsafe { pq_sys::PQbackendPID(self.into()) as u32 }
}
/**
* Returns `true` if the connection authentication method required a password, but none was
* available. Returns `false` if not.
*
* See [PQconnectionNeedsPassword](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQCONNECTIONNEEDSPASSWORD).
*/
pub fn needs_password(&self) -> bool {
unsafe { pq_sys::PQconnectionNeedsPassword(self.into()) == 1 }
}
/**
* Returns `true` if the connection authentication method used a password. Returns `false` if
* not.
*
* See [PQconnectionUsedPassword](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQCONNECTIONUSEDPASSWORD).
*/
pub fn used_password(&self) -> bool {
unsafe { pq_sys::PQconnectionUsedPassword(self.into()) == 1 }
}
/**
* Returns `true` if the connection uses SSL, `false` if not.
*
* See [PQsslInUse](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSSLINUSE).
*/
pub fn ssl_in_use(&self) -> bool {
unsafe { pq_sys::PQsslInUse(self.into()) == 1 }
}
/**
* Returns SSL-related information about the connection.
*
* See [PQsslAttribute](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSSLATTRIBUTE).
*/
pub fn ssl_attribute(&self, attribute: crate::ssl::Attribute) -> crate::errors::Result<Option<String>> {
let c_attribute = crate::ffi::to_cstr(&attribute.to_string());
let raw = unsafe { pq_sys::PQsslAttribute(self.into(), c_attribute.as_ptr()) };
if raw.is_null() {
Ok(None)
} else {
crate::ffi::to_option_string(raw)
}
}
/**
* Return an array of SSL attribute names available.
*
* See [PQsslAttributeNames](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSSLATTRIBUTENAMES).
*/
pub fn ssl_attribute_names(&self) -> crate::errors::Result<Vec<crate::ssl::Attribute>> {
let raw = unsafe { pq_sys::PQsslAttributeNames(self.into()) };
crate::ffi::vec_from_nta(raw)?
.iter()
.map(TryFrom::try_from)
.collect()
}
/**
* Return a pointer to an SSL-implementation-specific object describing the connection.
*
* See [PQsslStruct](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQSSLSTRUCT).
*
* # Safety
*
* This function returns a `void*` pointer.
*/
pub unsafe fn ssl_struct(&self, struct_name: &str) -> *const std::ffi::c_void {
let c_struct_name = crate::ffi::to_cstr(struct_name);
unsafe {
pq_sys::PQsslStruct(self.into(), c_struct_name.as_ptr())
}
}
/**
* Returns the SSL structure used in the connection, or null if SSL is not in use.
*
* See [PQgetssl](https://www.postgresql.org/docs/current/libpq-status.html#LIBPQ-PQGETSSL).
*
* # Safety
*
* This function returns a `void*` pointer.
*/
pub unsafe fn ssl(&self) -> *const std::ffi::c_void {
unsafe {
pq_sys::PQgetssl(self.into())
}
}
}