rust_query/

lib.rs

#![allow(private_bounds, private_interfaces)]
#![doc = include_str!("../README.md")]

extern crate self as rust_query;

#[macro_use]
extern crate static_assertions;

mod alias;
mod ast;
mod async_db;
mod db;
mod joinable;
mod lazy;
mod migrate;
mod mutable;
#[cfg(feature = "mutants")]
mod mutants;
mod mymap;
mod pool;
mod query;
mod rows;
mod schema;
mod select;
mod transaction;
mod value;
mod writable;

pub use async_db::DatabaseAsync;
pub use db::TableRow;
pub use lazy::Lazy;
use private::Reader;
pub use rust_query_macros::{FromExpr, Select};
use schema::from_macro::TypBuilder;
pub use select::{IntoSelect, Select};
pub use transaction::{Database, Transaction, TransactionWeak};
use value::MyTyp;
#[expect(deprecated)]
pub use value::UnixEpoch;
pub use value::aggregate::aggregate;
pub use value::trivial::FromExpr;
pub use value::{Expr, IntoExpr, optional::optional};
pub use writable::Update;

use crate::alias::JoinableTable;

/// Types that are used as closure arguments.
///
/// You generally don't need to import these types.
pub mod args {
    pub use crate::query::{OrderBy, Query};
    pub use crate::rows::Rows;
    pub use crate::value::aggregate::Aggregate;
    pub use crate::value::optional::Optional;
}

/// Types to declare schemas and migrations.
///
/// A good starting point is too look at [crate::migration::schema].
pub mod migration {
    pub use crate::migrate::{
        Migrator,
        config::{Config, ForeignKeys, Synchronous},
        migration::{Migrated, TransactionMigrate},
    };
    #[cfg(feature = "dev")]
    pub use crate::schema::dev::hash_schema;
    pub use rust_query_macros::schema;
}

/// These items are only exposed for use by the proc macros.
/// Direct use is unsupported.
#[doc(hidden)]
pub mod private {
    use std::marker::PhantomData;

    pub use crate::joinable::Joinable;
    pub use crate::migrate::{
        Schema, SchemaMigration, TableTypBuilder,
        migration::{Migration, SchemaBuilder},
    };
    pub use crate::query::get_plan;
    pub use crate::schema::from_macro::TypBuilder;
    pub use crate::value::{
        DynTypedExpr, MyTyp, Typed, ValueBuilder, adhoc_expr, new_column, unique_from_joinable,
    };
    pub use crate::writable::{Reader, TableInsert};

    pub struct Lazy<'t>(PhantomData<&'t ()>);
    pub struct Ignore;
    pub struct Custom<T>(PhantomData<T>);
    pub struct AsUpdate;
    pub struct AsExpr<'t>(PhantomData<&'t ()>);

    pub trait Apply {
        type Out<T: MyTyp, S>;
    }

    impl<'t> Apply for Lazy<'t> {
        type Out<T: MyTyp, S> = T::Lazy<'t>;
    }

    impl Apply for Ignore {
        type Out<T: MyTyp, S> = ();
    }

    impl<X> Apply for Custom<X> {
        type Out<T: MyTyp, S> = X;
    }

    impl Apply for AsUpdate {
        type Out<T: MyTyp, S> = crate::Update<S, T>;
    }

    impl<'t> Apply for AsExpr<'t> {
        type Out<T: MyTyp, S> = crate::Expr<'t, S, T>;
    }

    pub trait UpdateOrUnit<S, T>: Default {}
    impl<S, T: MyTyp> UpdateOrUnit<S, T> for crate::Update<S, T> {}
    impl<S, T> UpdateOrUnit<S, T> for () {}

    pub mod doctest {
        use crate::{Database, Transaction, migrate::config::Config, migration};

        #[migration::schema(Empty)]
        pub mod vN {
            pub struct User {
                #[unique]
                pub name: String,
            }
        }
        pub use v0::*;

        #[cfg_attr(test, mutants::skip)] // this function is only used in doc tests
        pub fn get_txn(f: impl Send + FnOnce(&'static mut Transaction<Empty>)) {
            let db = Database::new(Config::open_in_memory());
            db.transaction_mut_ok(|txn| {
                txn.insert(User { name: "Alice" }).unwrap();
                f(txn)
            })
        }
    }
}

/// This trait is implemented for all table types as generated by the [crate::migration::schema] macro.
///
/// **You can not implement this trait yourself!**
pub trait Table: Sized + 'static {
    #[doc(hidden)]
    type Ext2<'t>;

    #[doc(hidden)]
    fn covariant_ext<'x, 't>(val: &'x Self::Ext2<'static>) -> &'x Self::Ext2<'t>;

    #[doc(hidden)]
    fn build_ext2<'t>(val: &Expr<'t, Self::Schema, Self>) -> Self::Ext2<'t>;

    /// The schema that this table is a part of.
    type Schema;

    #[doc(hidden)]
    /// The table that this table can be migrated from.
    type MigrateFrom: MyTyp;

    /// The type of conflict that can result from inserting a row in this table.
    /// This is the same type that is used for row updates too.
    type Conflict;

    /// The type of updates used by [Transaction::update_ok].
    type UpdateOk;
    /// The type of updates used by [Transaction::update].
    type Update;
    /// The type of error when a delete fails due to a foreign key constraint.
    type Referer;

    #[doc(hidden)]
    type Mutable;
    #[doc(hidden)]
    type Lazy<'t>;
    #[doc(hidden)]
    type Insert;

    #[doc(hidden)]
    fn read(val: &Self::Insert, f: &mut Reader<Self::Schema>);

    #[doc(hidden)]
    fn get_conflict_unchecked(
        txn: &Transaction<Self::Schema>,
        val: &Self::Insert,
    ) -> Self::Conflict;

    #[doc(hidden)]
    fn select_mutable(
        val: Expr<'_, Self::Schema, Self>,
    ) -> Select<'_, Self::Schema, (Self::Mutable, TableRow<Self>)>;

    #[doc(hidden)]
    fn mutable_into_update(val: Self::Mutable) -> Self::UpdateOk;

    #[doc(hidden)]
    fn update_into_try_update(val: Self::UpdateOk) -> Self::Update;

    #[doc(hidden)]
    fn apply_try_update(val: Self::Update, old: Expr<'static, Self::Schema, Self>) -> Self::Insert;

    #[doc(hidden)]
    fn get_referer_unchecked() -> Self::Referer;

    #[doc(hidden)]
    fn get_lazy<'t>(txn: &'t Transaction<Self::Schema>, row: TableRow<Self>) -> Self::Lazy<'t>;

    #[doc(hidden)]
    fn typs(f: &mut TypBuilder<Self::Schema>);

    #[doc(hidden)]
    const SPAN: (usize, usize);

    #[doc(hidden)]
    const ID: &'static str;
    #[doc(hidden)]
    const NAME: &'static str;
}

trait CustomJoin: Table {
    fn name(&self) -> JoinableTable;
}

#[test]
fn compile_tests() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/compile/*.rs");
}