Macro diesel::table

macro_rules! table {
    ($($tokens:tt)*) => { ... };
}

Specifies that a table exists, and what columns it has. This will create a new public module, with the same name, as the name of the table. In this module, you’ll find a unit struct named table, and a unit struct with the names of each of the columns.

By default this allows a maximum of 32 columns per table. You can increase this limit to 64 by enabling the 64-column-tables feature. You can increase it to 128 by enabling the 128-column-tables feature. You can decrease it to 16 columns, which improves compilation time, by disabling the default features of Diesel. Note that enabling 64 column tables or larger will substantially increase the compile time of Diesel.

Example usage

diesel::table! {
    users {
        id -> Integer,
        name -> VarChar,
        favorite_color -> Nullable<VarChar>,
    }
}

You may also specify a primary key if it’s called something other than id. Tables with no primary key are not supported.

diesel::table! {
    users (non_standard_primary_key) {
        non_standard_primary_key -> Integer,
        name -> VarChar,
        favorite_color -> Nullable<VarChar>,
    }
}

For tables with composite primary keys, list all of the columns in the primary key.

diesel::table! {
    followings (user_id, post_id) {
        user_id -> Integer,
        post_id -> Integer,
        favorited -> Bool,
    }
}

If you are using types that aren’t from Diesel’s core types, you can specify which types to import.

diesel::table! {
    use diesel::sql_types::*;
    use diesel_full_text_search::*;

    posts {
        id -> Integer,
        title -> Text,
        keywords -> TsVector,
    }
}

If you want to add documentation to the generated code you can use the following syntax:

diesel::table! {
    /// The table containing all blog posts
    posts {
        /// The post's unique id
        id -> Integer,
        /// The post's title
        title -> Text,
    }
}

If you have a column with the same name as a Rust reserved keyword, you can use the sql_name attribute like this:

diesel::table! {
    posts {
        id -> Integer,
        /// This column is named `mytype` but references the table `type` column.
        #[sql_name = "type"]
        mytype -> Text,
    }
}

This module will also contain several helper types:

dsl

This simply re-exports the table, renamed to the same name as the module, and each of the columns. This is useful to glob import when you’re dealing primarily with one table, to allow writing users.filter(name.eq("Sean")) instead of users::table.filter(users::name.eq("Sean")).

all_columns

A constant will be assigned called all_columns. This is what will be selected if you don’t otherwise specify a select clause. It’s type will be table::AllColumns. You can also get this value from the Table::all_columns function.

star

This will be the qualified “star” expression for this table (e.g. users.*). Internally, we read columns by index, not by name, so this column is not safe to read data out of, and it has had it’s SQL type set to () to prevent accidentally using it as such. It is sometimes useful for count statements however. It can also be accessed through the Table.star() method.

SqlType

A type alias called SqlType will be created. It will be the SQL type of all_columns. The SQL type is needed for things like returning boxed queries.

BoxedQuery

pub type BoxedQuery<'a, DB, ST = SqlType> = BoxedSelectStatement<'a, ST, table, DB>;