docudb
1.0
|
DocuDB is a lightweight document database built on top of SQLite. It provides a simple interface for managing JSON documents.
The library has been tested with the following C++ compilers
However it should build with any reasonable C++20 compiler.
https://dgl.cx/2020/06/sqlite-json-support
To use DocDB, include the header file in your project:
It is crucial to understand the concurrency model of DocuDB to use it safely in a multi-threaded application. The library's thread safety is directly inherited from the underlying SQLite C library it is built upon.
SQLite databases can be opened in one of three threading modes. You should be aware of how your system's SQLite library is configured. For detailed information, please refer to the official SQLite documentation on the topic: SQLite and Multiple Threads.
Here is a summary of how to use DocuDB safely based on SQLite's mode:
docudb::database
object (and its corresponding sqlite3
handle) can be safely shared and used across multiple threads. SQLite guarantees that all access is serialized, preventing race conditions.docudb::database
object must not be shared across threads. The safe and recommended pattern is to create a separate docudb::database
connection object for each thread that needs to interact with the database.The Query Builder DSL uses a thread_local
counter to generate unique names for bound parameters (e.g., :p1
, :p2
). This has an important implication:
A single query builder chain must be constructed and executed on the same thread.
You cannot, for example, start building a query on one thread and pass the partially-built query object to another thread to finish and execute it.
This design also means that while you can use a connection pool, you must be careful if a single thread can acquire different database connections from the pool. Using multiple docudb::database
objects on the same thread can cause the thread_local
counter to be shared, potentially leading to incorrect query parameter binding if queries are built in an interleaved fashion. The most robust approach remains creating one connection per thread.
db_document_ref
)A docudb::db_document_ref
object holds a raw pointer to the internal sqlite3
handle, which is managed by the docudb::database
object. If the database
object is destroyed before a db_document_ref
that refers to it, the reference will become a dangling pointer, and using it will lead to undefined behavior.
Safe Usage: Always ensure that the docudb::database
object outlives any document or collection objects derived from it.
The library generates UUIDs for new documents using std::mt19937
, which is not cryptographically secure. Do not rely on these UUIDs in security-sensitive contexts where guessability is a concern. If you need secure random identifiers, generate them using a dedicated cryptography library and provide them when creating documents.
Of course. Here is a new "Usage" section for your README.md
file that explains how to use the new database connection options. You can add this to your main usage or features section.
You can connect to a database file or an in-memory database by creating a docudb::database
object.
The simplest way to open a database is to provide a path. This is suitable for most use cases.
By default the database will be opened with the default built-in in the SQLite library.
For more control over the connection, you can provide optional open_mode
and threading_mode
arguments to the constructor.
1. Open Mode (open_mode
)
This enum controls the file access permissions.
docudb::open_mode::read_only
: Opens an existing database for reading only.docudb::open_mode::read_write
: Opens an existing database for reading and writing.docudb::open_mode::read_write_create
: (Default) Opens for reading and writing, creating the file if it does not already exist.Example: Opening a database for read-only access
2. Threading Mode (threading_mode
)
This enum specifies the concurrency model for the connection. For more details on what these mean, please refer to the Concurrency and Thread Safety section.
docudb::threading_mode::default_mode
: Uses SQLite's default mode.docudb::threading_mode::multi_thread
: The connection can only be used in one thread at a time.docudb::threading_mode::serialized
: (Default) The connection is protected by a mutex and can be safely used across multiple threads.Example: Opening a database in Multi-Thread mode
This project is licensed under the MIT License.