jiff-sqlx: add integration crate for SQLx

.github/workflows/ci.yml

@@ -124,6 +124,24 @@ jobs:
     # - name: Run integration tests
       # run: cargo test --test integration
 
+  # This job tests that examples outside the workspace build.
+  #
+  # These are outside the workspace because their dependency graphs are
+  # absolutely ludicrous.
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: stable
+    - name: Build sqlx-postgres example
+      run: cargo build --manifest-path ./examples/sqlx-postgres/Cargo.toml
+    - name: Run sqlx-sqlite example
+      run: cargo run --manifest-path ./examples/sqlx-sqlite/Cargo.toml
+
   # Generic testing for most cross targets. Some get special treatment in
   # other jobs.
   cross:

.vim/coc-settings.json

@@ -1,6 +1,8 @@
 {
   "rust-analyzer.linkedProjects": [
     "bench/Cargo.toml",
+    "examples/sqlx-postgres/Cargo.toml",
+    "examples/sqlx-sqlite/Cargo.toml",
     "Cargo.toml"
   ]
 }

Cargo.toml

@@ -32,10 +32,12 @@ include = [
 members = [
   "crates/jiff-cli",
   "crates/jiff-icu",
+  "crates/jiff-sqlx",
   "crates/jiff-tzdb",
   "crates/jiff-tzdb-platform",
   "examples/*",
 ]
+exclude = ["examples/sqlx-postgres", "examples/sqlx-sqlite"]
 
 # Features are documented in the "Crate features" section of the crate docs:
 # https://docs.rs/jiff/*/#crate-features

crates/jiff-icu/Cargo.toml

@@ -6,9 +6,9 @@ license = "Unlicense OR MIT"
 homepage = "https://github.com/BurntSushi/jiff/tree/master/crates/jiff-icu"
 repository = "https://github.com/BurntSushi/jiff"
 documentation = "https://docs.rs/jiff-icu"
-description = "The entire Time Zone Database embedded into your binary."
+description = "Conversion routines for Jiff and ICU4X."
 categories = ["date-and-time"]
-keywords = ["date", "time", "temporal", "zone", "iana"]
+keywords = ["date", "time", "temporal", "zone", "icu"]
 workspace = "../.."
 edition = "2021"
 rust-version = "1.70"

crates/jiff-sqlx/COPYING

@@ -0,0 +1,3 @@
+This project is dual-licensed under the Unlicense and MIT licenses.
+
+You may use this code under the terms of either license.

crates/jiff-sqlx/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "jiff-sqlx"
+version = "0.0.1"  #:version
+authors = ["Andrew Gallant <[email protected]>"]
+license = "Unlicense OR MIT"
+homepage = "https://github.com/BurntSushi/jiff/tree/master/crates/jiff-sqlx"
+repository = "https://github.com/BurntSushi/jiff"
+documentation = "https://docs.rs/jiff-sqlx"
+description = "Integration for Jiff in sqlx."
+categories = ["date-and-time"]
+keywords = ["date", "time", "jiff", "sqlx", "zone"]
+workspace = "../.."
+edition = "2021"
+rust-version = "1.70"
+include = ["/*.rs", "/*.dat", "COPYING", "LICENSE-MIT", "UNLICENSE"]
+
+[lib]
+name = "jiff_sqlx"
+bench = false
+path = "src/lib.rs"
+
+[features]
+default = []
+postgres = ["dep:sqlx-postgres"]
+sqlite = ["dep:sqlx-sqlite"]
+
+[dependencies]
+jiff = { path = "../..", default-features = false }
+sqlx-core = { version = "0.8.0", default-features = false }
+sqlx-postgres = { version = "0.8.0", default-features = false, optional = true }
+sqlx-sqlite = { version = "0.8.0", default-features = false, optional = true }
+
+[dev-dependencies]
+jiff = { path = "../..", default-features = true }

crates/jiff-sqlx/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Andrew Gallant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

crates/jiff-sqlx/README.md

@@ -0,0 +1,7 @@
+jiff-icu
+========
+WIP
+
+### Documentation
+
+https://docs.rs/jiff-icu

crates/jiff-sqlx/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

crates/jiff-sqlx/src/lib.rs

@@ -0,0 +1,73 @@
+/*!
+This crate provides integration points for [Jiff](jiff) and [SQLx][sqlx].
+
+Examples can be found in the
+[examples directory of the Jiff repository][examples].
+
+# Organization
+
+This crates defines several types that wrap corresponding types in Jiff. Each
+wrapper type provides implementations of traits found in SQLx. For most types,
+these are the [`sqlx_core::types::Type`], [`sqlx_core::decode::Decode`] and
+[`sqlx_core::encode::Encode`] traits.
+
+The intended workflow is to use these wrapper types within your wire types for
+encoding and decoding data from databases such as PostgreSQL. The wrapper types
+own the logic for encoding and decoding the data in database specific formats.
+
+In order to the minimize the annoyance of wrapper types, the following
+conveniences are afforded:
+
+* A [`ToSqlx`] trait is provided. Several Jiff types implement this trait. The
+trait provides easy conversion to the corresponding wrapper type in this crate.
+* A concrete `to_jiff` method is provided on each wrapper type. For example,
+[`Timestamp::to_jiff`]. This method is the reverse of `ToSqlx`. This converts
+from the wrapper type to the corresponding Jiff type.
+* There are `From` trait implementations from the wrapper type to the
+corresponding Jiff type, and vice versa.
+
+# Database support
+
+At present, both PostgreSQL and SQLite are supported.
+
+Ideally, MySQL support would be present too, but it
+[appears impossible until SQLx exposes some APIs][sqlx-mysql-bunk].
+
+# Future
+
+This crate exists because there are generally only three ways to implement
+the necessary traits in SQLx:
+
+1. Make Jiff depend on SQLx, and implement the corresponding traits where
+Jiff's types are defined.
+2. Make SQLx depend on Jiff, and implement the corresponding traits where the
+traits are defined.
+3. Make a crate like this one with types that wrap Jiff's types, and implements
+the corresponding traits for the wrapper types.
+
+This was done because it seems inappropriate for a "lower level" crate like
+Jiff to depend on SQLx. And while it might be appropriate for SQLx to optionally
+depend on Jiff (like it does for [`chrono`] or [`time`]), at time of writing,
+Jiff is still early in its life. It's totally reasonable to wait for it to
+mature. Plus, the thought of three different datetime integrations is,
+admittedly, tough to stomach.
+
+In the future, it may be prudent for this crate to be upstreamed into SQLx
+itself.
+
+[sqlx]: https://docs.rs/sqlx/0.8
+[examples]: https://github.com/BurntSushi/jiff/tree/master/examples/uptime
+[`chrono`]: https://docs.rs/chrono
+[`time`]: https://docs.rs/time
+[sqlx-mysql-bunk]: https://github.com/launchbadge/sqlx/issues/3487#issuecomment-2641843693
+*/
+
+#![deny(missing_docs)]
+
+pub use self::wrappers::{Date, DateTime, Span, Time, Timestamp, ToSqlx};
+
+#[cfg(feature = "postgres")]
+mod postgres;
+#[cfg(feature = "sqlite")]
+mod sqlite;
+mod wrappers;