[−][src]Struct sqlx::PgConnection
An asynchronous connection to a Postgres database.
The connection string expected by [Connection::open] should be a PostgreSQL connection string, as documented at https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNSTRING
TLS Support (requires tls
feature)
This connection type supports the same sslmode
query parameter that libpq
does in
connection strings: https://www.postgresql.org/docs/12/libpq-ssl.html
postgresql://<user>[:<password>]@<host>[:<port>]/<database>[?sslmode=<ssl-mode>[&sslcrootcert=<path>]]
where
ssl-mode = disable | allow | prefer | require | verify-ca | verify-full
path = percent (URL) encoded path on the local machine
If the tls
feature is not enabled, disable
, allow
and prefer
are no-ops and require
,
verify-ca
and verify-full
are forbidden (attempting to connect with these will return
an error).
If the tls
feature is enabled, an upgrade to TLS is attempted on every connection by default
(equivalent to sslmode=prefer
). If the server does not support TLS (because it was not
started with a valid certificate and key, see https://www.postgresql.org/docs/12/ssl-tcp.html)
then it falls back to an unsecured connection and logs a warning.
Add sslmode=require
to your connection string to emit an error if the TLS upgrade fails.
If you're running Postgres locally, your connection string might look like this:
postgresql://root:password@localhost/my_database?sslmode=require
However, like with libpq
the server certificate is not checked for validity by default.
Specifying sslmode=verify-ca
will cause the TLS upgrade to verify the server's SSL
certificate against a local CA root certificate; this is not the system root certificate
but is instead expected to be specified in one of a few ways:
-
The path to the certificate can be specified by adding the
sslrootcert
query parameter to the connection string. (Remember to percent-encode it!) -
The path may also be specified via the
PGSSLROOTCERT
environment variable (which should not be percent-encoded.) -
Otherwise, the library will look for the Postgres global root CA certificate in the default location:
$HOME/.postgresql/root.crt
on POSIX systems%APPDATA%\postgresql\root.crt
on Windows
These locations are documented here: https://www.postgresql.org/docs/12/libpq-ssl.html#LIBQ-SSL-CERTIFICATES If the root certificate cannot be found by any of these means then the TLS upgrade will fail.
If sslmode=verify-full
is specified, in addition to checking the certificate as with
sslmode=verify-ca
, the hostname in the connection string will be verified
against the hostname in the server certificate, so they must be the same for the TLS
upgrade to succeed.
Methods
impl PgConnection
[src]
pub fn open<T>(
url: T
) -> Pin<Box<dyn Future<Output = Result<PgConnection, Error>> + 'static + Send>> where
T: TryInto<Url, Error = Error>,
PgConnection: Sized,
[src]
url: T
) -> Pin<Box<dyn Future<Output = Result<PgConnection, Error>> + 'static + Send>> where
T: TryInto<Url, Error = Error>,
PgConnection: Sized,
please use 'connect' instead
Trait Implementations
impl Connect for PgConnection
[src]
type Connection = PgConnection
fn connect<T>(
url: T
) -> Pin<Box<dyn Future<Output = Result<PgConnection, Error>> + 'static + Send>> where
T: TryInto<Url, Error = Error>,
PgConnection: Sized,
[src]
url: T
) -> Pin<Box<dyn Future<Output = Result<PgConnection, Error>> + 'static + Send>> where
T: TryInto<Url, Error = Error>,
PgConnection: Sized,
impl Connection for PgConnection
[src]
fn close(
self
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'static + Send>>
[src]
self
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'static + Send>>
fn ping(&mut self) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>
[src]
impl Executor for PgConnection
[src]
type Database = Postgres
fn send<'e, 'q>(
&'e mut self,
query: &'q str
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'e + Send>> where
'q: 'e,
fn execute<'e, 'q>(
&'e mut self,
query: &'q str,
args: PgArguments
) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str,
args: PgArguments
) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + 'e + Send>> where
'q: 'e,
fn fetch<'e, 'q>(
&'e mut self,
query: &'q str,
args: PgArguments
) -> Pin<Box<dyn Stream<Item = Result<PgRow, Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str,
args: PgArguments
) -> Pin<Box<dyn Stream<Item = Result<PgRow, Error>> + 'e + Send>> where
'q: 'e,
fn describe<'e, 'q>(
&'e mut self,
query: &'q str
) -> Pin<Box<dyn Future<Output = Result<Describe<<PgConnection as Executor>::Database>, Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str
) -> Pin<Box<dyn Future<Output = Result<Describe<<PgConnection as Executor>::Database>, Error>> + 'e + Send>> where
'q: 'e,
fn fetch_optional<'e, 'q>(
&'e mut self,
query: &'q str,
args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<Option<<Self::Database as Database>::Row>, Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str,
args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<Option<<Self::Database as Database>::Row>, Error>> + 'e + Send>> where
'q: 'e,
fn fetch_one<'e, 'q>(
&'e mut self,
query: &'q str,
args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + 'e + Send>> where
'q: 'e,
[src]
&'e mut self,
query: &'q str,
args: <Self::Database as Database>::Arguments
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + 'e + Send>> where
'q: 'e,
Auto Trait Implementations
impl RefUnwindSafe for PgConnection
impl Send for PgConnection
impl Sync for PgConnection
impl Unpin for PgConnection
impl UnwindSafe for PgConnection
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<'_, T, DB> HasSqlType<&'_ T> for DB where
DB: HasSqlType<T>,
T: ?Sized,
[src]
DB: HasSqlType<T>,
T: ?Sized,
impl<T, DB> HasSqlType<Option<T>> for DB where
DB: HasSqlType<T>,
[src]
DB: HasSqlType<T>,
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,