kitx 0.0.11

A lightweight wrapper for database operations based on sqlx, enabling fast CRUD operations.
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

# KitX - Lightweight SQL Builder for Rust


A minimalistic SQL builder library based on [sqlx](https://crates.io/crates/sqlx), supporting SQLite, MySQL/MariaDB, and PostgreSQL. It offers efficient database operations with soft delete capabilities and global filters, enabling developers to interact with databases more effectively.

## Features


### Core Functionality

- **Efficient CRUD Operations**  
  `insert_one`, `insert_many`, `update_by_key`, `update_one`, `upsert_by_key`,  
  `upsert_many`, `delete_by_key`, `delete_by_cond`, `delete_many`  
   with transaction support

- **Advanced Queries**  
  `get_list`, `get_by_key`, `get_one`, `get_list_paginated`, `get_list_by_cursor`,  
  `exists`, `count`

- **Soft Delete Management**  
  `restore_one`, `restore_many`  
  with global configuration

- **Flexible Query Building**  
  Supports JOINs, CASE WHEN, WITH CTE, and aggregations. Supports ON CONFLICT/DUPLICATE KEY (upsert) and RETURNING for conflict resolution and data retrieval.

- **Code Characteristics** 
  - **No Macros**: Public interfaces avoid macros, ensuring transparency and maintainability.
  - **No `.unwrap()` or `.expect()`**: Prevents runtime panics by promoting robust error handling.


### Key Advantages

- 🚀 **No ORM Overhead** - Direct SQL interaction with builder pattern  
- 🔧 **Field Access API** - Utilizes [field_access](https://crates.io/crates/field_access) for field operations  
- 🌍 **Global Filters** - Apply tenant ID or soft delete filters across all queries  
- 📦 **Extensible** - Easily add custom operations and query modifiers  

## Quick Start


### 1. Add Dependency

```toml
# Default SQL Builder, completely decoupled from any external libraries.

kitx = "0.0.11"

# For SQLite only

kitx = { version = "0.0.11", features = ["sqlite"] }

# For MySQL/MariaDB only

kitx = { version = "0.0.11", features = ["mysql"] }

# For PostgreSQL only

kitx = { version = "0.0.11", features = ["postgres"] }
```

### 2. Basic Usage

```rust
use kitx::sqlite::{sql::Select, sql::Insert, sql::col, operations::Operations};

// SQL Builder Example
// AND and OR conditions can be applied either within filter clauses or directly in the builder.
let query = Select::columns(&["id", "name"])
    .from("users")
    .where_(col("age").eq(23))
    .and(col("salary").gt(4500))
    .or(col("status").in_(vec!["active", "pending"]))
    .order_by("created_at", false)
    .build().0;

let query2 = Insert::into("users")
    .columns(&["id", "name"])
    .values(&[22, "John Doe"])
    .build().0;
  
// CRUD Operations
// KitX does not support composite primary keys. For such cases, please use constraints instead.
let op = Operations::new("articles", ("article_id", true));
let article = Article {
    id: 22,
    title: "Rust Best Practices".into(),
    content: "...".into(),
};

// Insert with transaction
op.insert_one(article).await?;
```

### 3. Pagination Example

```rust
let results = op.get_list_paginated(10, 2, empty_query()).await?;

let results = op.get_list_by_cursor(10, |&mut builder|{
    builder.where_mut(col("created_at").gt(DateTime::now()));
}).await?;

```

### 4. Optional: Global Configuration

```rust
// Soft delete configuration
set_global_soft_delete_field("deleted_at", vec!["audit_logs"]);

// Global_filter is applied on a per-thread basis.
// Multi-tenant filtering
set_global_filter(col("tenant_id").eq(123)), vec!["system_metrics"]);
```

### 5. More Usage Examples 

For more detailed usage examples and advanced scenarios, please refer to the test cases provided in the repository.

## License

MIT License