@@ -398,8 +398,132 @@ pub struct Timestamp;
398398#[ derive( Debug , Clone , Copy , Default , QueryId , SqlType ) ]
399399#[ diesel( postgres_type( oid = 114 , array_oid = 199 ) ) ]
400400#[ diesel( mysql_type( name = "String" ) ) ]
401+ #[ diesel( sqlite_type( name = "Text" ) ) ]
401402pub struct Json ;
402403
404+ /// The [`jsonb`] SQL type. This type can only be used with `feature =
405+ /// "serde_json"`
406+ ///
407+ /// In SQLite, `jsonb` brings mainly [performance improvements][sqlite-adv] over
408+ /// regular JSON:
409+ ///
410+ /// > The advantage of JSONB in SQLite is that it is smaller and faster than
411+ /// > text JSON - potentially several times faster. There is space in the
412+ /// > on-disk JSONB format to add enhancements and future versions of SQLite
413+ /// > might include options to provide O(1) lookup of elements in JSONB, but no
414+ /// > such capability is currently available.
415+ ///
416+ /// <div class="warning">
417+ /// In SQLite, JSONB is intended for internal use by SQLite only. Thus, future
418+ /// SQLite updates might break our JSONB implementation. And one might have to
419+ /// wait and then upgrade <code>diesel</code> for those changes to be accounted
420+ /// for. If you do not want this, prefer the regular
421+ /// <a href="./struct.Json.html"><code>Json</code></a> type.
422+ /// </div>
423+ ///
424+ /// In PostgreSQL, `jsonb` offers [several advantages][pg-adv] over regular JSON:
425+ ///
426+ /// > There are two JSON data types: `json` and `jsonb`. They accept almost
427+ /// > identical sets of values as input. The major practical difference
428+ /// > is one of efficiency. The `json` data type stores an exact copy of
429+ /// > the input text, which processing functions must reparse on each
430+ /// > execution; while `jsonb` data is stored in a decomposed binary format
431+ /// > that makes it slightly slower to input due to added conversion
432+ /// > overhead, but significantly faster to process, since no reparsing
433+ /// > is needed. `jsonb` also supports indexing, which can be a significant
434+ /// > advantage.
435+ /// >
436+ /// > ...In general, most applications should prefer to store JSON data as
437+ /// > `jsonb`, unless there are quite specialized needs, such as legacy
438+ /// > assumptions about ordering of object keys.
439+ ///
440+ /// [pg-adv]: https://www.postgresql.org/docs/current/static/datatype-json.html
441+ /// [sqlite-adv]: https://sqlite.org/draft/jsonb.html
442+ ///
443+ /// ### [`ToSql`] impls
444+ ///
445+ /// - [`serde_json::Value`]
446+ ///
447+ /// ### [`FromSql`] impls
448+ ///
449+ /// - [`serde_json::Value`]
450+ ///
451+ /// [`ToSql`]: crate::serialize::ToSql
452+ /// [`FromSql`]: crate::deserialize::FromSql
453+ /// [`jsonb`]: https://www.postgresql.org/docs/current/datatype-json.html
454+ #[ cfg_attr(
455+ feature = "serde_json" ,
456+ doc = "[`serde_json::Value`]: serde_json::value::Value"
457+ ) ]
458+ #[ cfg_attr(
459+ not( feature = "serde_json" ) ,
460+ doc = "[`serde_json::Value`]: https://docs.rs/serde_json/1.0.64/serde_json/value/enum.Value.html"
461+ ) ]
462+ ///
463+ /// ## Examples
464+ ///
465+ /// ```rust
466+ /// # #![allow(dead_code)]
467+ /// # include!("../doctest_setup.rs");
468+ /// #
469+ /// table! {
470+ /// contacts {
471+ /// id -> Integer,
472+ /// name -> Text,
473+ /// address -> Jsonb,
474+ /// }
475+ /// }
476+ ///
477+ /// # #[cfg(all(
478+ /// # feature = "serde_json",
479+ /// # any(
480+ /// # feature = "postgres_backend",
481+ /// # all(feature = "sqlite", feature = "returning_clauses_for_sqlite_3_35"),
482+ /// # )
483+ /// # ))]
484+ /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
485+ /// # use diesel::insert_into;
486+ /// # use self::contacts::dsl::*;
487+ /// # let connection = &mut connection_no_data();
488+ /// # #[cfg(feature = "postgres_backend")]
489+ /// # diesel::sql_query("CREATE TABLE contacts (
490+ /// # id SERIAL PRIMARY KEY,
491+ /// # name VARCHAR NOT NULL,
492+ /// # address JSONB NOT NULL
493+ /// # )").execute(connection)?;
494+ /// # #[cfg(feature = "sqlite")]
495+ /// # diesel::sql_query("CREATE TABLE contacts (
496+ /// # id INT PRIMARY KEY,
497+ /// # name TEXT NOT NULL,
498+ /// # address BLOB NOT NULL
499+ /// # )").execute(connection)?;
500+ /// let santas_address: serde_json::Value = serde_json::from_str(r#"{
501+ /// "street": "Article Circle Expressway 1",
502+ /// "city": "North Pole",
503+ /// "postcode": "99705",
504+ /// "state": "Alaska"
505+ /// }"#)?;
506+ /// let inserted_address = insert_into(contacts)
507+ /// .values((name.eq("Claus"), address.eq(&santas_address)))
508+ /// .returning(address)
509+ /// .get_result::<serde_json::Value>(connection)?;
510+ /// assert_eq!(santas_address, inserted_address);
511+ /// # Ok(())
512+ /// # }
513+ /// # #[cfg(not(all(
514+ /// # feature = "serde_json",
515+ /// # any(
516+ /// # feature = "postgres_backend",
517+ /// # all(feature = "sqlite", feature = "returning_clauses_for_sqlite_3_35"),
518+ /// # )
519+ /// # )))]
520+ /// # fn main() {}
521+ /// ```
522+ #[ derive( Debug , Clone , Copy , Default , QueryId , SqlType ) ]
523+ #[ diesel( postgres_type( oid = 3802 , array_oid = 3807 ) ) ]
524+ #[ diesel( sqlite_type( name = "Binary" ) ) ]
525+ pub struct Jsonb ;
526+
403527/// The nullable SQL type.
404528///
405529/// This wraps another SQL type to indicate that it can be null.
0 commit comments