Struct tiberius::Client

source ·
pub struct Client<S: AsyncRead + AsyncWrite + Unpin + Send> { /* private fields */ }
Expand description

Client is the main entry point to the SQL Server, providing query execution capabilities.

A Client is created using the Config, defining the needed connection options and capabilities.

§Example

use tokio_util::compat::TokioAsyncWriteCompatExt;

let mut config = Config::new();

config.host("0.0.0.0");
config.port(1433);
config.authentication(AuthMethod::sql_server("SA", "<Mys3cureP4ssW0rD>"));

let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
tcp.set_nodelay(true)?;
// Client is ready to use.
let client = tiberius::Client::connect(config, tcp.compat_write()).await?;

Implementations§

source§

impl<S: AsyncRead + AsyncWrite + Unpin + Send> Client<S>

source

pub async fn connect(config: Config, tcp_stream: S) -> Result<Client<S>>

Uses an instance of Config to specify the connection options required to connect to the database using an established tcp connection

source

pub async fn execute<'a>( &mut self, query: impl Into<Cow<'a, str>>, params: &[&dyn ToSql], ) -> Result<ExecuteResult>

Executes SQL statements in the SQL Server, returning the number rows affected. Useful for INSERT, UPDATE and DELETE statements. The query can define the parameter placement by annotating them with @PN, where N is the index of the parameter, starting from 1. If executing multiple queries at a time, delimit them with ; and refer to ExecuteResult how to get results for the separate queries.

For mapping of Rust types when writing, see the documentation for ToSql. For reading data from the database, see the documentation for FromSql.

This API is not quite suitable for dynamic query parameters. In these cases using a Query object might be easier.

§Example
let results = client
    .execute(
        "INSERT INTO ##Test (id) VALUES (@P1), (@P2), (@P3)",
        &[&1i32, &2i32, &3i32],
    )
    .await?;
source

pub async fn query<'a, 'b>( &'a mut self, query: impl Into<Cow<'b, str>>, params: &'b [&'b dyn ToSql], ) -> Result<QueryStream<'a>>
where 'a: 'b,

Executes SQL statements in the SQL Server, returning resulting rows. Useful for SELECT statements. The query can define the parameter placement by annotating them with @PN, where N is the index of the parameter, starting from 1. If executing multiple queries at a time, delimit them with ; and refer to QueryStream on proper stream handling.

For mapping of Rust types when writing, see the documentation for ToSql. For reading data from the database, see the documentation for FromSql.

This API can be cumbersome for dynamic query parameters. In these cases, if fighting too much with the compiler, using a Query object might be easier.

§Example
let stream = client
    .query(
        "SELECT @P1, @P2, @P3",
        &[&1i32, &2i32, &3i32],
    )
    .await?;
source

pub async fn simple_query<'a, 'b>( &'a mut self, query: impl Into<Cow<'b, str>>, ) -> Result<QueryStream<'a>>
where 'a: 'b,

Execute multiple queries, delimited with ; and return multiple result sets; one for each query.

§Example
let row = client.simple_query("SELECT 1 AS col").await?.into_row().await?.unwrap();
assert_eq!(Some(1i32), row.get("col"));
§Warning

Do not use this with any user specified input. Please resort to prepared statements using the query method.

source

pub async fn bulk_insert<'a>( &'a mut self, table: &'a str, ) -> Result<BulkLoadRequest<'a, S>>

Execute a BULK INSERT statement, efficiantly storing a large number of rows to a specified table. Note: make sure the input row follows the same schema as the table, otherwise calling send() will return an error.

§Example
let create_table = r#"
    CREATE TABLE ##bulk_test (
        id INT IDENTITY PRIMARY KEY,
        val INT NOT NULL
    )
"#;

client.simple_query(create_table).await?;

// Start the bulk insert with the client.
let mut req = client.bulk_insert("##bulk_test").await?;

for i in [0i32, 1i32, 2i32] {
    let row = (i).into_row();

    // The request will handle flushing to the wire in an optimal way,
    // balancing between memory usage and IO performance.
    req.send(row).await?;
}

// The request must be finalized.
let res = req.finalize().await?;
assert_eq!(3, res.total());
source

pub async fn close(self) -> Result<()>

Closes this database connection explicitly.

Trait Implementations§

source§

impl<S: Debug + AsyncRead + AsyncWrite + Unpin + Send> Debug for Client<S>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<S> Freeze for Client<S>
where S: Freeze,

§

impl<S> RefUnwindSafe for Client<S>
where S: RefUnwindSafe,

§

impl<S> Send for Client<S>

§

impl<S> Sync for Client<S>
where S: Sync,

§

impl<S> Unpin for Client<S>

§

impl<S> UnwindSafe for Client<S>
where S: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more