ormpp

ormpp is a modern C++ ORM (Object-Relational Mapping) library designed to simplify database programming in C++. It provides a unified interface across multiple database backends, allowing developers to switch between databases with minimal code changes.

Key features include:

• Header-only: No compilation required; just include the headers.
• Cross-platform: Supports Linux, macOS, and Windows.
• Unified Interface: Supports MySQL, PostgreSQL, and SQLite with a consistent API.
• Type-safe SQL Builder: Uses compile-time reflection and safe chained calls to ensure field types are checked at compile time.
• Built-in Connection Pool: Supports automatic recovery and health checks.
• Asynchronous MySQL: Supports non-blocking queries via ASIO/async_simple.
• AOP Support: Allows logging and validation via warper_connect.
• SQLite Encryption: Supports SQLCipher for encrypted storage.

ormpp uses a four-layer architecture to provide fully asynchronous database operations that integrate with coroutine frameworks like async_simple. This design ensures that database I/O and business logic can run on the same non-blocking event loop, preventing thread blocking in high-concurrency services.

The Four Layers

1. mysql_async (Protocol Layer): A direct implementation of the MySQL client protocol where all I/O is performed using ASIO coroutines.
2. AsioAwaitableAdapter / SafeAsioAwaitableAdapter (Bridge Layer): Bridges asio::awaitable into an awaiter that can be used with co_await in async_simple::Lazy.
3. dbng<mysql_async> + Chained Query API (Interface Layer): Provides the unified chained query API (e.g., select(), insert(), update()) and transaction management on top of the adapter.
4. async_connection_pool (Management Layer): Manages connection pools, supporting health checks, dynamic scaling, and timeout waiting.

┌─────────────────────────────────────────────────────────────┐
│  业务代码 (async_simple::Lazy)                               │
│  co_await db.await(db.raw().select(...).from<T>().collect())│
└────────────────────────────────────────┬────────────────────┘
                         │ co_await
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  AsioAwaitableAdapter / SafeAsioAwaitableAdapter            │
│  协程框架桥接层                                              │
└────────────────────────────────────────┬────────────────────┘
                         │ asio::co_spawn
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  dbng<mysql_async>                                          │
│  异步数据库接口 (ASIO 协程)                                  │
│  - select().from<T>().where(...).collect()                  │
│  - insert() / update() / delete()                           │
│  - execute() / begin() / commit() / rollback()             │
└────────────────────────────────────────┬────────────────────┘
                         │ asio::async_read/write
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  MySQL TCP 连接                                             │
│  完整实现 MySQL 客户端协议                                   │
└─────────────────────────────────────────────────────────────┘

ORMPP supports advanced C++ types within your mapped structures:

1. Optional Types: Use std::optional<T> to map columns that allow NULL values. When querying, use .has_value() to check for presence.
2. Enum Types: Map enum class directly to database integer values. Ensure the enum values correspond to the database representation.
3. BLOB Data: Use ormpp::blob to handle binary data. Use .assign(ptr, end_ptr) to load data and .size() to retrieve it.

All types must be registered using REGISTER_AUTO_KEY and YLT_REFL (or similar reflection macros) to be compatible with the ORM.

// Optional Example
struct OptionalPerson {
  int id;
  std::optional<std::string> name;
  std::optional<int> age;
};
REGISTER_AUTO_KEY(OptionalPerson, id)
YLT_REFL(OptionalPerson, id, name, age)

// Enum Example
enum class Gender { Male = 0, Female = 1 };
struct PersonWithEnum {
  int id;
  std::string name;
  Gender gender;
};
REGISTER_AUTO_KEY(PersonWithEnum, id)
YLT_REFL(PersonWithEnum, id, name, gender)

// BLOB Example
struct BlobData {
  int id;
  ormpp::blob data;
};
YLT_REFL(BlobData, id, data)

ormpp uses ASIO coroutines for asynchronous database interfaces, while business logic may use the async_simple framework. Because these two frameworks use different schedulers and suspension mechanisms, they cannot directly co_await each other.

To bridge them, ormpp provides two types of adapters:

1. AsioAwaitableAdapter (Lightweight): Use this when you have a single-threaded executor (only one thread calling io_context::run()), a shared execution context between ASIO and async_simple, and structured concurrency where the parent Lazy coroutine is guaranteed not to be destroyed while waiting.
2. SafeAsioAwaitableAdapter (Safe): Use this for multi-threaded executors (multiple threads calling run() on the same io_context), scenarios where the awaiter might be destroyed prematurely (e.g., parent coroutine cancellation), or when you need explicit cancellation support.

To prevent SQL injection and allow dynamic values in your queries, use the token placeholder. When you use token in a clause (like where, limit, or offset), you must provide the corresponding runtime values in the final collect() or scalar() call.

Alternatively, if a value is fixed and known at compile time, you can pass it directly to the method (e.g., .limit(10)) instead of using token to avoid the extra parameter in collect().

// Using token for runtime parameters
co_await db.select(all)
    .from<person>()
    .where(col(&person::name).param())   // → WHERE name = ?
    .limit(token)                         // → LIMIT ?
    .offset(token)                        // → OFFSET ?
    .collect("Alice", 10, 0);            // Alice → name, 10 → LIMIT, 0 → OFFSET

// Using fixed values directly
co_await db.select(all)
    .from<person>()
    .limit(10)    // → LIMIT 10
    .offset(0);   // → OFFSET 0

The AsioAwaitableAdapter<T> is a high-performance adapter designed for single-threaded environments. It avoids heap allocations, mutexes, and atomic variables by storing results directly in the awaiter object.

Constraints for use:

• Single-threaded io_context::run().
• Shared underlying io_context for both ASIO and async_simple executors.
• Parent Lazy coroutine will not be cancelled or destroyed during the wait.

Key implementation details:

• It implements await_ready, await_suspend, and await_resume for C++ coroutine compatibility.
• It provides a coAwait(async_simple::Executor*) method to allow async_simple to recognize the custom awaiter.

template <typename T>
class AsioAwaitableAdapter {
 public:
  AsioAwaitableAdapter(asio::awaitable<T> awaitable, asio::any_io_executor executor);
  bool await_ready() const noexcept;
  bool await_suspend(std::coroutine_handle<>) noexcept;
  T await_resume();
  auto coAwait(async_simple::Executor*) noexcept;
};

The SafeAsioAwaitableAdapter<T> is designed for complex, multi-threaded, or high-reliability environments. It uses a SharedState managed by std::shared_ptr to ensure that even if the awaiter is destroyed, the asynchronous operation can complete safely without causing dangling pointers.

Features:

• Thread Safety: Uses asio::strand to serialize all non-atomic state modifications.
• Lifecycle Safety: Uses std::shared_ptr<SharedState> so the ASIO side can continue working even if the parent coroutine is destroyed.
• Cancellation Support: Provides a cancellation_handle to request cancellation of the underlying ASIO operation.

When to use:

• Multi-threaded io_context::run().
• When the awaiter might be destroyed before completion.
• When you need to support cancellation requests.

template <typename T>
class SafeAsioAwaitableAdapter {
 public:
  class cancellation_handle {
   public:
    bool valid() const noexcept;
    bool cancel(asio::cancellation_type) const noexcept;
  };

  SafeAsioAwaitableAdapter(asio::awaitable<T>, asio::any_io_executor executor);
  ~SafeAsioAwaitableAdapter();

  bool await_ready() const noexcept;
  bool await_suspend(std::coroutine_handle<>) noexcept;
  T await_resume();

  cancellation_handle get_cancellation_handle() const noexcept;
  bool cancel(asio::cancellation_type) const noexcept;
  auto coAwait(async_simple::Executor*) noexcept;
};