DOCSEARCHbyAlgolia
Submit Docs

SQLiteC++ Documentation

repository·master·Indexed 25 days ago

https://github.com/srombauts/sqlitecpp

A lightweight C++11 wrapper for the SQLite3 C API focusing on RAII, ease of use, and minimal dependencies. It provides intuitive C++ classes for database connections, prepared statements, and transaction management, utilizing exceptions for error handling. Supports CMake and Meson build systems, and can be installed via vcpkg.

Tokens
3.2K
Snippets
9
Records
17
Agent score
83%

What's inside SQLiteC++

  1. Overview of SQLiteC++

    master

    SQLiteC++ (SQLiteCpp) is a lean, easy-to-use C++ wrapper for the native SQLite3 C APIs. It provides intuitive C++ classes designed with C++11 standards, utilizing the RAII (Resource Acquisition Is Initialization) idiom and STL.

    Key characteristics:

    • Error Handling: Uses exceptions for SQLite errors (the Exception class inherits from std::runtime_error).
    • Thread Safety: Thread-safe only as much as SQLite's "Multi-thread" mode.
    • Design: Uses RAII to ensure objects remain valid from construction (with a valid connection) until destruction.

  2. Requirements and Dependencies for SQLiteC++

    master

    To use SQLiteC++, your environment must meet the following requirements:

    • Compiler: A C++11 compatible compiler (GCC 4.8.4+, Clang 5+, AppleClang 8+, or Visual Studio 2015+).
    • Standard Library: A modern C++11 STL implementation.
    • Exception Support: Required for error handling.
    • SQLite Library:
      • Minimum version: 3.7.15.
      • Must be linked dynamically or statically.
      • Crucial: The SQLITE_ENABLE_COLUMN_METADATA macro must be defined during the SQLite compilation/usage.

    On Debian/Ubuntu/Mint Linux, you can install the necessary SQLite development files using:

    sudo apt-get install libsqlite3-dev

  4. Use SQLiteCpp as a subdirectory in a CMake project

    master
    The example2 demonstrates the pattern for including SQLiteCpp as a subdirectory within your own CMake-based project. This is useful when you want to manage the library's source directly within your project tree rather than installing it globally or using a package manager.

  5. Use a system-wide SQLiteCpp installation in CMake

    master

    If SQLiteCpp is already installed on your system, use find_package to locate it and link against the SQLiteCpp target.

    # You can optionally define a minimum version in this call
find_package(SQLiteCpp REQUIRED)

# Link against the SQLiteCpp library
target_link_libraries(my_target PRIVATE SQLiteCpp)

  6. Configure SQLite dependency for SQLiteC++

    master

    By default, the CMake build uses the internal sqlite3.c and sqlite3.h files provided in the repository for easy setup and compatibility across Windows, Linux, and MacOS.

    If you prefer to link against a system-installed SQLite library (such as the libsqlite3-dev package on Linux) instead of using the internal files, you can disable the internal SQLite implementation using the -DSQLITECPP_INTERNAL_SQLITE=OFF CMake flag.

  7. Integrate SQLiteCpp as a CMake Subdirectory

    master

    You can add SQLiteCpp directly to your project by including its source files and linking against the sqlite3 library. The easiest method is to add the repository as a Git submodule and use add_subdirectory in your CMakeLists.txt.

    add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/thirdparty/SQLiteCpp)

add_executable(main src/main.cpp)
target_link_libraries(main
  SQLiteCpp
  sqlite3
  pthread
  dl
  )

  9. Build SQLiteCpp with Meson

    master

    SQLiteCpp supports the Meson build system. You can build the library with or without tests and examples using the following commands.

    # Build with default options
meson setup builddir
meson compile -C builddir

# Build with tests and examples enabled
meson setup builddir -DSQLITECPP_BUILD_TESTS=true -DSQLITECPP_BUILD_EXAMPLES=true
meson compile -C builddir

  10. Troubleshoot SQLite3 linker errors

    master

    If you encounter linker errors on Linux, check the following:

    1. undefined reference to sqlite3_xxx: You are missing the SQLite3 development files. Install the libsqlite3-dev package.
    2. Column.cpp: undefined reference to sqlite3_column_origin_name: Your SQLite3 library was not compiled with SQLITE_ENABLE_COLUMN_METADATA.

    To fix the second error, you can:

    • Recompile your distribution's SQLite3 library with the required macro.
    • Turn off SQLITE_ENABLE_COLUMN_METADATA in CMakeFiles.txt.
    • Turn on SQLITECPP_INTERNAL_SQLITE in CMakeFiles.txt to use the internal SQLite3 source provided by the project.

  12. Manage transactions with SQLite::Transaction

    master

    Use SQLite::Transaction to wrap multiple database operations in a single atomic unit. The transaction begins when the object is constructed and is committed when .commit() is called. If the object is destroyed before commit is called (e.g., due to an exception), the transaction is automatically rolled back.

    try
{
    SQLite::Database    db("transaction.db3", SQLite::OPEN_READWRITE|SQLite::OPEN_CREATE);

    db.exec("DROP TABLE IF EXISTS test");

    // Begin transaction
    SQLite::Transaction transaction(db);

    db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)");

    int nb = db.exec("INSERT INTO test VALUES (NULL, \"test\")");
    std::cout << "INSERT INTO test VALUES (NULL, \"test\")", returned " << nb << std::endl;

    // Commit transaction
    transaction.commit();
}
catch (std::exception& e)
{
    std::cout << "exception: " << e.what() << std::endl;
}