diff --git a/README.md b/README.md index e0c50e5..f7217a8 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,26 @@ SPDX-License-Identifier: MIT OR Apache-2.0 # naphtha +*Universal database connection layer* + [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-informational?style=flat-square)](COPYRIGHT.md) [![Crates.io](https://img.shields.io/crates/v/naphtha.svg)](https://crates.io/crates/naphtha) [![docs.rs](https://img.shields.io/docsrs/naphtha?style=flat-square)](https://docs.rs/naphtha) **naphtha** [![Crates.io](https://img.shields.io/crates/v/naphtha-proc-macro.svg)](https://crates.io/crates/naphtha-proc-macro) **naphtha-proc-macro** -Please checkout the [documentation page](https://docs.rs/naphtha) for information and examples (also see examples folder in [naphtha](./naphtha/examples)) +Please checkout the [documentation page](https://docs.rs/naphtha) for more information (also see examples folder in [naphtha](./naphtha/examples)) If you have questions, want to contribute or have any other type of request, your invited to create an issue or visit the [openprobst.dev](https://openprobst.dev) discord server. [![](https://img.shields.io/discord/855726181142495242?color=154683&label=discord&style=flat-square)](https://discord.gg/nx7YtsjEbT) +## About + +This crate is to simplify the creation and usage of models that require a database connection. If applied correct, changing the database type is only a feature flag away. + +The models can also be compiled and used without database connection support for better usage on server and client side. + ## Roadmap - [x] Connect to database using a wrapper, defining the base for interchangeable Databases @@ -27,9 +35,13 @@ If you have questions, want to contribute or have any other type of request, you - [x] Thread safe sharing of the database connection - [x] Integrate `barrel` crate for writing migrations in Rust, available at runtime - [x] Implement support for `diesel::MySqlConnection` -- [ ] Implement support for `diesel::PgConnection` -- [ ] Connection pooling -- [ ] More databases!!! +- [x] Implement support for `diesel::PgConnection` +- [ ] Connection pooling? +- [ ] More databases? + +## Troubleshooting + +It is very easy to get a whole bunch of `trait bound not satisfied` error messages when your model is not configured correctly. Make sure that your `schema` module and the containing `table!` definition is in line with your `model` definition and that it uses the correct types defined by [barrel](https://docs.rs/barrel). ## Contributing diff --git a/naphtha/src/lib.rs b/naphtha/src/lib.rs index 357809c..a96018d 100644 --- a/naphtha/src/lib.rs +++ b/naphtha/src/lib.rs @@ -15,11 +15,12 @@ //! //! * Most common function implementations `insert`, `update`, `remove` for your //! models. +//! * Custom transactions provided by the `custom` function //! * [DatabaseUpdateHandler](DatabaseUpdateHandler) enables you to change the models values before and //! after the `update` transaction to the database. //! * Change database on specific model in your application without the need to //! change your code. -//! * Possibility to query a model from the database by using one of its member *(NOT FINISHED YET)*. +//! * Possibility to query a model from the database by using one of its member. //! * Integrated [barrel] for writing your SQL migrations. //! * Thread safe handling of the database connection. //! @@ -45,35 +46,16 @@ //! //! ### Defining a model and use database connection //! -//! ```rust -//! #[macro_use] -//! extern crate diesel; -//! #[macro_use] -//! extern crate naphtha; -//! -//! use { -//! naphtha::{ -//! model, -//! DatabaseModel, -//! DatabaseModelModifier, -//! DatabaseInsertHandler, -//! DatabaseUpdateHandler, -//! DatabaseRemoveHandler -//! }, -//! diesel::table -//! }; -//! #[cfg(any(feature = "barrel-sqlite", feature = "barrel-mysql", feature = "barrel-pg"))] -//! use naphtha::barrel::{types, DatabaseSqlMigration, Migration}; -//! -//! // It is recommended to wrap the actual used database type in a crate-global -//! // alias. If the database is changed later, this is the only line that needs -//! // to be adjusted to the new database type. -//! pub(crate) type DbBackend = diesel::SqliteConnection; +//! To create a model and its database integration, the following code is required. +//! *Note that this is an excerpt, see the `examples` folder in the repository for +//! a full working example.* //! +//! ```ignore //! #[model(table_name = "persons")] //! pub struct Person { //! id: i32, //! pub description: Option, + pub updated_at: NaiveDateTime, //! } //! //! pub mod schema { @@ -81,6 +63,7 @@ //! persons (id) { //! id -> Int4, //! description -> Nullable, + updated_at -> Timestamp, //! } //! } //! } @@ -104,16 +87,12 @@ //! } //! } //! -//! // do not implement custom changes before and after the transactions -//! // to the database. +//! // Define your custom changes to the model before and after the transactions. //! impl naphtha::DatabaseUpdateHandler for Person {} //! impl naphtha::DatabaseRemoveHandler for Person {} //! impl naphtha::DatabaseInsertHandler for Person {} //! -//! #[cfg(any( -//! feature = "barrel-full", -//! feature = "barrel-sqlite", -//! ))] +//! // This implements your database migration functions. //! impl DatabaseSqlMigration for Person { //! fn migration_up(migration: &mut Migration) { //! use naphtha::DatabaseModel; @@ -133,6 +112,8 @@ //! fn main() { //! use naphtha::{DatabaseConnection, DatabaseConnect}; //! let db = DatabaseConnection::connect(":memory:").unwrap(); +//! // p is to be mutable because the insert function updates the id member +//! // to the one given by the database. //! let mut p = Person { //! id: Person::default_primary_key(), //! description: Some("The new person is registered".into()), @@ -147,7 +128,7 @@ //! }); //! //! p.remove(&db); -//! // p not available anymore +//! // p not available anymore in the database //! } //! ```