The `Transaction` implementation never actually mutates the
`Connection` reference we give it. In fact, the `Transaction`
structure itself only requires an immutable connection. So it can be
surprising to readers that the constructor requires a `&mut
Connection`. We do this so as to prevent at compile-time nested or
concurrent transactions on the same connection as these are not
allowed by SQLite.
In this commit, we add a comment explaining this nuance.
We implement `ToSql` and `FromSql` for `time::Timespec` values. Our
documentation indicates that we store the value in the same format
used by SQLite's built-in date/time functions, but this was not
correct.
We were using the format:
%Y-%m-%d %H:%M:%S:%f %Z
This format cannot be interpreted at all by SQLite's built-in
date/time functions. There are three reasons for this:
- SQLite supports only two timezone formats: `[+-]HH:MM` and the
literal character `Z` (indicating UTC)
- SQLite does not support a space before the timezone indicator
- SQLite supports a period (`.`) between the seconds field and the
fractional seconds field, but not a colon (`:`)
SQLite does support the RFC 3339 date/time format, which is standard
in many other places. As we're always storing a UTC value, we'll
simply use a trailing `Z` to indicate the timezone, as allowed by RFC
3339. The new format is:
%Y-%m-%dT%H:%M:%S.%fZ
To avoid breaking applications using databases with values in the old
format, we'll continue to support it as a fallback for `FromSql`.
[1] https://www.sqlite.org/lang_datefunc.html
[2] https://tools.ietf.org/html/rfc3339
Currently `libsqlite3-sys` is the first result for both the "database"
keyword, and the "Database interfaces" category. This makes sense, as it
is a dependency of both Diesel and rusqlite. However, this library is
not intended to be used directly. While it can technically be called a
database interface, FFI is clearly the category that applies more than
anything else. Someone browsing this keyword or category is likely
looking for a Rust library they can use, not a C one.
