Crate rp1

RP1 is a Diesel based CRUD for Rocket. To get started with RP1 you can read the project setup below, which will guide to through setting up a basic application. If you already have a running rocket/diesel application you should continue with reading the docs for the crud macro, which will explain the basic setup and explain all options that the crud generation has.

Example

This is an example of what RP1 allows you to create (note that we assume that you already have a schema definition for the users table generated by diesel).

#[macro_use]
extern crate diesel;

mod schema;

use rocket_sync_db_pools::database;

#[database("diesel")]
struct Db(diesel::PgConnection);

#[rp1::crud(database = "Db", table = "users", auth = false)]
struct User {
    #[primary_key]
    pub id: i32,
    #[validate(email)]
    username: String,
    role: String,
    #[generated]
    created_at: rp1::datetime::OffsetDateTime,
    #[generated]
    updated_at: rp1::datetime::OffsetDateTime,
}

#[rocket::launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/users", User::get_routes())
        .attach(Db::fairing())
}

Project setup

To get started, you will need to add a few dependencies to your Cargo.toml.

[dependencies]
rp1 = "0.3"
diesel = { version = "1.4", features = ["postgres", "r2d2"] }
diesel_migrations = "1.4"
rocket = "0.5.0-rc.1"
rocket_sync_db_pools = { version = "0.1.0-rc.1", features = ["diesel_postgres_pool"] }
serde = "1.0"
serde_json = "1.0"
validator = "0.14"

Next, make sure you have installed the diesel cli. To do this, you can run

cargo install diesel_cli --no-default-features --features postgres

If you need to have support for all database types supported by diesel you can run cargo install diesel_cli instead. Do make sure you installed the relevant libraries for the databases you intend to use (e.g. for debian based OSes make sure you installed libpq-dev). You should now also start a postgresql server. For the example in this repository we have a docker-compose.yml file that you can use to start a simple PostgreSQL development server using docker-compose.

Next, create a file .env and add the DATABASE_URL environment variable. If you used the docker-compose.yml file then it should read:

DATABASE_URL=postgres://crud@127.0.0.1:5432/crud

Now we are ready to run diesel setup which will create an initial migration and get us ready to define our database schema. Start by adding your initial migration using diesel migration generate <name>. After you completed your migration run diesel migration run and a schema.rs file should appear.

Next, update your main.rs file to read:

#[macro_use]
extern crate diesel;

mod schema;

use rocket_sync_db_pools::database;

#[database("diesel")]
struct Db(diesel::PgConnection);

#[rocket::launch]
fn rocket() -> _ {
    rocket::build()
        .attach(Db::fairing())
}

Note the #[macro_use] extern crate diesel; and mod schema specifically for Diesel, and the struct Db and fn rocket which are used by Rocket to communicate with Diesel. Finally, we need to configure rocket to use the same database as the diesel-cli. To do this, create a file Rocket.toml and place the following configuration in it (replacing the database URL with your own):

[global.databases]
diesel = { url = "postgres://crud@127.0.0.1:5432/crud" }

Now, you should be able to run cargo run and your project should start! You are finally ready for your first RP1 struct. To get started with your first RP1 struct, you should take a look at the documentation for the crud macro.

Re-exports

• pub use access_control::*;

Modules

• access_control
  Authorization and access control support.
• datetime
  Date and time helpers that can be used in both diesel, serde and rocket contexts.
• helper
  Contains some utilities mostly useful internally, but may be used in other places a well.

Structs

• SortSpec
  Sort specification, contains a field and direction.

Enums

• CrudError
• FilterOperator
  Supported filter operators for the filter parameter.
• ParseError
  Indicates an error while trying to parse a filter value in the query string.
• SortDirection
  Specifies in which direction a sorting operation should occur.

Traits

• CrudFilterSpec
  This trait is implemented on the main struct and indicates the type that is used for filtering on properties.
• CrudInsertable
  This trait is implemented on the main struct and indicates the type that is used for insert operations.
• CrudStruct
  This trait is implemented on the main struct and indicates the type that is the diesel table struct.
• CrudUpdatable
  This trait is implemented on the main struct and indicates the type that is used for update operations.

Type Aliases

• CrudJsonResult
  Return type for all handler functions that return json generated by the crud macro.
• CrudResult
  Return type for all handler functions generated by the crud macro.

Attribute Macros

• crud
  The crud macro