db-library 0.1.2

A Rust library for listening to database changes and notifying connected backend services.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! # Database Change Listener
//!
//! This Rust library provides an event-based mechanism to monitor changes in database tables or collections
//! and notify backend services, eliminating the need for polling. It supports PostgreSQL and MongoDB,
//! allowing developers to register listeners and receive real-time updates on specified tables, columns, or collections.
//!
//! ## Features
//! - **Database-Agnostic:** Designed to support multiple databases, starting with PostgreSQL and MongoDB.
//! - **Event-Driven:** Notifies backend services of table or collection changes via event-based channels.
//! - **Customizable:** Users can specify the database type, connection URL, table or collection name, and columns to monitor.
//! - **Efficient:** Eliminates the need for polling, reducing unnecessary database load.
//! - **Automatic Pool Management:** Handles connection pooling internally to ensure efficient resource usage.
//!
//! ## Installation
//! Add the following to your `Cargo.toml`:
//! ```bash
//!    cargo add db-library
//! ```
//!
//! ## Quick Start
//!
//! Example for PostgreSQL:
//!
//! ```rust
//! use db_library::{config::DBListenerError, DBConfig, DBListener, EventType, PgNotify};\
//!
//! #[tokio::main]
//! async fn main() -> Result<(), DBListenerError> {
//!     let database_config = DBConfig::Postgres {
//!         url, // Database connection URL
//!         table_name, // Name of the table to monitor
//!         columns, // List of specific columns to monitor for updates
//!         table_identifier, // Unique identifier for the table
//!     };
//!
//!     let events = vec![EventType::UPDATE, EventType::INSERT, EventType::DELETE]; // Events to monitor
//!
//!     let db_listener = DBListener::new(database_config, events).await?; // Create a new database listener
//!
//!     db_listener
//!         .listen(|notification| async move {
//!             // Print the raw notification
//!             println!("Received notification: {:?}", notification);
//!
//!             // Attempt to deserialize the notification into the `PgNotify` struct
//!             match serde_json::from_str::<PgNotify>(&notification.to_string()) {
//!                 Ok(pg_notify) => {
//!                     println!("--> Payload received in channel");
//!                     println!("Parsed Payload: {:#?}", pg_notify);
//!                 }
//!                 Err(err) => {
//!                     epritnln!("Error deserializing notification: {:#?}", err);
//!                 }
//!             }
//!         })
//!         .await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! Example for MongoDB:
//!
//! ```rust
//! use db_library::{config::DBListenerError, DBConfig, DBListener, EventType, MongoNotify};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), DBListenerError> {
//!     let database_config = DBConfig::MongoDB {
//!         url, // Database connection URL
//!         database, // Name of the database to monitor.
//!         collection, // Name of the collection to monitor.
//!     };
//!
//!     let events = vec![EventType::INSERT, EventType::UPDATE, EventType::DELETE]; // Events to monitor
//!
//!     let db_listener = DBListener::new(database_config, events).await?; // Create a new database listener
//!
//!     db_listener
//!         .listen(|notification| async move {
//!             // Print the raw notification
//!             println!("Received notification: {:?}", notification);
//!
//!             // Attempt to deserialize the notification into the `MongoNotify` struct
//!             match serde_json::from_str::<MongoNotify>(&notification.to_string()) {
//!                 Ok(mongo_notify) => {
//!                     println!("--> Payload received in channel");
//!                     println!("Parsed Payload: {:#?}", mongo_notify);
//!                 }
//!                 Err(err) => {
//!                     eprintln!("Error deserializing notification: {:#?}", err);
//!                 }
//!             }
//!         })
//!         .await?; // <-- Ensuring `.await?` is correctly placed
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Supported Databases
//! - **PostgreSQL**
//! - **MongoDB**
//!
//! ## Configuration
//! Users can specify the database type, connection URL, table name or collection name, and columns when initializing
//! a listener instance. The library provides a flexible configuration to accommodate various use cases.
//!
//! ## Use Cases
//! - **Real-time Data Synchronization:** Keep your application data in sync with database changes.
//! - **Event-Driven Microservices:** Build microservices that react to database events.
//! - **Change Tracking for Analytics:** Monitor changes for analytics and reporting purposes.

pub mod config;
pub mod database;
pub mod utils;

pub use config::DBListenerError;
pub use database::mongodb::MongoNotify;
pub use database::postgres::PgNotify;
pub use database::{DBConfig, DBListener, EventType};