Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Diesel Codegen
Provides various macros and annotations for
Diesel to reduce the amount of
boilerplate needing to be written. It can be used through rustc_plugin
, or
syntex
on stable.
Using on nightly
Make sure you're on a nightly from 2015-11-27 or later, we don't compile on earlier versions. To use with nightly, you'll want to turn off the default features. Add this
line to your dependencies section in Cargo.toml
= { = "^0.3.0", = false, = ["nightly"] }
Then you'll need to add two lines to the root of your crate.
After that, you'll be good to go.
Using on stable
On stable, you'll need to use syntex
to
build any modules using our annotations. Add the following to your
build-dependencies.
= "^0.3.0"
= "^0.22.0"
You'll need to move any code using annotations into a different file.
src/schema.rs
include!;
src/schema.in.rs
Then create a build.rs
with the following:
extern crate syntex;
extern crate diesel_codegen;
use env;
use Path;
Note that compiler errors will be reported in the generated file, not the source file. For that reason, it's often easier to develop with nightly rust, and deploy or test on stable. You can see an example of how to do this by looking at Diesel's tests.
Struct annotations
#[derive(Queriable)]
Adds an implementation of the Queriable
trait to the annotated
item. At this time it only supports structs with named fields. Enums and tuple
structs are not supported.
#[insertable_into(table_name)]
Adds an implementation of the Insertable
trait to the annotated
item, targeting the given table. Can only annotate structs and tuple structs.
Enums are not supported. See [field annotations][#field-annotations] for
additional configurations.
#[changeset_for(table_name)]
Adds an implementation of the AsChangeset
trait to the
annotated item, targeting the given table. At this time, it only supports
structs with named fields. Tuple structs and enums are not supported. See [field
annotations][#field-annotations] for additional configurations.
Any fields which are of the type Option
will be skipped when their value is
None
. This makes it easy to support APIs where you may not want to update all
of the fields of a record on every request.
If the struct has a field for the primary key, an additional function,
save_changes<T: Queriable<..>>(&self, connection: &Connection) -> QueryResult<T>
, will be added to the model. This will persist any changes made,
and return the resulting record. It is intended to be a shorthand for filtering
by the primary key.
Field annotations
#[column_name="value"]
Any field can be annotated with column_name=
to have it map to a column with a
different name. This is required for all fields of tuple structs.
Macros (Experimental)
infer_schema!("database_url")
Queries the database for the names of all tables, and calls
infer_table_from_schema!
for each one. We recommend using with the
dotenv
crate, and invoking this as
infer_schema!(dotenv!("DATABASE_URL"))
infer_table_from_schema!("database_url", "table_name")
Establishes a database connection at compile time, loads the schema information
about a table's columns, and invokes
table
for you
automatically. We recommend using with the
dotenv
crate, and invoking this as
infer_table_from_schema!(dotenv!("DATABASE_URL"), "table_name")
At this time, the schema inference macros do not support types from third party crates, and having any columns with a type not already supported will result in a compiler error (please open an issue if this happens unexpectedly for a type listed in our docs.)