# db-cores

Database core utilities for Rust. A SQL abstraction toolkit providing multi-database support (PostgreSQL, MySQL, SQLite) with query building, connection management, and schema utilities.

## Overview

db-cores provides a unified interface for working with multiple SQL databases in Rust:

1. **Query Building** — Generic SQL query builders with type-safe parameter binding, using sqlx's `Database` trait for cross-database compatibility. Supports SELECT, INSERT, UPDATE, DELETE with conditions, pagination, and ordering.

2. **SQL Generation** — Database-specific SQL generation for PostgreSQL, MySQL, and SQLite. Supports generating SQL from JSON structures and simplified query structures.

3. **JSON Conversion** — Convert database rows (`PgRow`, `MySqlRow`, `SqliteRow`) to `serde_json::Value` with automatic type mapping.

4. **Connection Pool Management** — Global connection pool cache with `DbPool` enum wrapping `MySqlPool`, `PgPool`, and `SqlitePool`. Supports auto-creation and caching.

5. **Plugin System** — Database-specific plugins (e.g., `pg_get_tabledef` for PostgreSQL).

6. **Macro System** — Procedural macros including:
   - `define_model!` — Generates struct with `FromRow`, `Serialize`, `Deserialize`
   - `define_enum!` — Generates enum with sqlx `Decode`/`Type` and serde traits
   - `SqlxEnum` derive macro
   - `pg_builder!` — Parameterized Postgres query builder

7. **Schema Utilities** — Table creation, alteration, and comparison (diff detection for columns and tables).

8. **AST Parsing** — SQL AST parsing using `sqlparser`.

9. **Validation** — SQL identifier validation.

## Features

The crate uses feature flags to control which database backends are included. sqlx is an **optional dependency** — it's only pulled in when at least one database feature is enabled.

```toml
[features]
default = ["postgres"]
postgres = ["dep:sqlx", "sqlx/postgres"]
mysql = ["dep:sqlx", "sqlx/mysql"]
sqlite = ["dep:sqlx", "sqlx/sqlite"]
```

## Usage

Add to your `Cargo.toml`:

```toml
# Default (PostgreSQL only)
db-cores = "0.1.0"

# SQLite only
db-cores = { version = "0.1.0", default-features = false, features = ["sqlite"] }

# MySQL only
db-cores = { version = "0.1.0", default-features = false, features = ["mysql"] }

# PostgreSQL + MySQL
db-cores = { version = "0.1.0", features = ["mysql"] }

# All databases
db-cores = { version = "0.1.0", features = ["postgres", "mysql", "sqlite"] }

# No database (SQL building utilities only)
db-cores = { version = "0.1.0", default-features = false }
```

## Quick Examples

### Define a Model

```rust
use db_cores::define_model;

define_model!(User, "users",
    id: String,
    name: String,
    email: Option<String>,
    created_at: Option<i64>,
    is_active: bool
);
```

### Get a Connection Pool

```rust
use db_cores::{postgres_pool, DbConnect, DatabaseKind};

let connect = DbConnect {
    kind: DatabaseKind::Postgres,
    host: "127.0.0.1".to_string(),
    port: 5432,
    username: "postgres".to_string(),
    password: "postgres".to_string(),
    db_name: "mydb".to_string(),
    ..Default::default()
};
let pool = postgres_pool(&connect).await?;
```

## Modules

- `query` — Database-specific query execution (`postgres`, `mysql`, `sqlite` submodules)
- `builder` — SQL query builder with type-safe parameter binding
- `to_json` — Row-to-JSON conversion for each database backend
- `common` — Shared types (`DbConnect`, `DatabaseKind`, `TableColumn`, etc.)
- `plugin` — Database-specific plugins
- `ast` — SQL AST parsing utilities
- `verify` — SQL identifier validation
- `utlis` — General utilities

## Links

- **Repository:** https://github.com/Kaifang-123/db-cores
- **Documentation:** https://docs.rs/db-cores

## License

MIT
