Module rusqlite::types

Traits dealing with SQLite data types.

SQLite uses a dynamic type system. Implementations of the ToSql and FromSql traits are provided for the basic types that SQLite provides methods for:

• Strings (String and &str)
• Blobs (Vec<u8> and &[u8])
• Numbers

The number situation is a little complicated due to the fact that all numbers in SQLite are stored as INTEGER (i64) or REAL (f64).

ToSql and FromSql are implemented for all primitive number types. FromSql has different behaviour depending on the SQL and Rust types, and the value.

• INTEGER to integer: returns an Error::IntegralValueOutOfRange error if the value does not fit in the Rust type.
• REAL to integer: always returns an Error::InvalidColumnType error.
• INTEGER to float: casts using as operator. Never fails.
• REAL to float: casts using as operator. Never fails.

ToSql always succeeds except when storing a u64 or usize value that cannot fit in an INTEGER (i64). Also note that SQLite ignores column types, so if you store an i64 in a column with type REAL it will be stored as an INTEGER, not a REAL.

If the time feature is enabled, implementations are provided for time::OffsetDateTime that use the RFC 3339 date/time format, "%Y-%m-%dT%H:%M:%S.%fZ", to store time values as strings. These values can be parsed by SQLite’s builtin datetime functions. If you want different storage for datetimes, you can use a newtype. For example, to store datetimes as i64s counting the number of seconds since the Unix epoch:

use rusqlite::types::{FromSql, FromSqlError, FromSqlResult, ToSql, ToSqlOutput, ValueRef};
use rusqlite::Result;

pub struct DateTimeSql(pub time::OffsetDateTime);

impl FromSql for DateTimeSql {
    fn column_result(value: ValueRef) -> FromSqlResult<Self> {
        i64::column_result(value).and_then(|as_i64| {
            time::OffsetDateTime::from_unix_timestamp(as_i64)
            .map(|odt| DateTimeSql(odt))
            .map_err(|err| FromSqlError::Other(Box::new(err)))
        })
    }
}

impl ToSql for DateTimeSql {
    fn to_sql(&self) -> Result<ToSqlOutput> {
        Ok(self.0.unix_timestamp().into())
    }
}

ToSql and FromSql are also implemented for Option<T> where T implements ToSql or FromSql for the cases where you want to know if a value was NULL (which gets translated to None).

Structs

Null

Empty struct that can be used to fill in a query parameter as NULL.

Enums

FromSqlError

Enum listing possible errors from FromSql trait.

ToSqlOutput

ToSqlOutput represents the possible output types for implementers of the ToSql trait.

Type

SQLite data types. See Fundamental Datatypes.

Value

Owning dynamic type value. Value’s type is typically dictated by SQLite (not by the caller).

ValueRef

A non-owning dynamic type value. Typically the memory backing this value is owned by SQLite.

Traits

FromSql

A trait for types that can be created from a SQLite value.

ToSql

A trait for types that can be converted into SQLite values. Returns Error::ToSqlConversionFailure if the conversion fails.

Type Definitions

FromSqlResult

Result type for implementors of the FromSql trait.