0
0
mirror of https://github.com/rbock/sqlpp11.git synced 2024-11-16 04:47:18 +08:00
A type safe SQL template library for C++
Go to file
Roland Bock bda77c620b Introduce optional, string_view, and span
sqlpp::optional is an alias for std::optional for C++17 and beyond.
Otherwise, it is a simple and incomplete backport.
For older versions of C++, the library offers simple back

Similar for string_view and span.
2024-06-12 20:29:10 +02:00
cmake Update FindMariaDB.cmake 2024-04-10 06:27:41 +02:00
connector_api Add is_transaction_active() to all connectors (#550) 2024-01-05 08:59:42 +01:00
dependencies style: Align CMake files with 4 spaces indent 2022-11-26 08:32:46 +01:00
docs Update the documentation for NULL #568 2024-04-13 08:56:57 +02:00
examples Connection pools documentation and example (#533) 2023-10-03 09:45:21 +02:00
include/sqlpp11 Introduce optional, string_view, and span 2024-06-12 20:29:10 +02:00
scripts ddl2cpp: Add tests for the column isPrimaryKey property. 2024-06-12 20:22:06 +02:00
tests Introduce optional, string_view, and span 2024-06-12 20:29:10 +02:00
_config.yml Set theme jekyll-theme-minimal 2017-06-04 14:59:27 +02:00
.appveyor.yml ci: enable ctest output on failure 2023-02-11 09:04:45 +01:00
.clang-format Stop clang-format from sorting includes 2016-10-07 12:13:31 +02:00
.gitignore add set(tuple<...>) implementation for insert and update statements 2018-02-15 07:55:43 +01:00
.travis.yml Add Connector CMake Logic (#394) 2021-12-02 07:45:38 +01:00
ChangeLog.md Update ChangeLog.md 2016-08-30 09:48:04 +02:00
CMakeLists.txt Fix building with sqlcipher (#508) 2023-07-30 10:12:59 +02:00
coveralls add coveralls coverage reporting 2015-05-30 00:56:33 +02:00
CREDITS shamelessly adding myself to CREDITS 2015-05-30 01:12:31 +02:00
LICENSE Update LICENSE 2016-03-05 20:14:35 +01:00
pre-commit Reformatted using clang-format 2015-09-13 21:33:19 +02:00
README.md ddl2cpp command line argument for custom types (#491) 2023-06-22 07:06:00 +02:00
wishlist.md Fix some formatting in wish list 2019-08-20 18:58:24 +02:00

sqlpp11

A type safe embedded domain specific language for SQL queries and results in C++.

!If you are a tenured user of sqlpp11, please note that
!  - with 0.61 the connector libraries for mysql/sqlite/postgresql got merged into the main repo.
!  - master has been renamed to main and is now the default branch

Documentation is found in docs.

So what is this about?

SQL and C++ are both strongly typed languages. Still, most C/C++ interfaces to SQL are based on constructing queries as strings and on interpreting arrays or maps of strings as results.

sqlpp11 is a templated library representing an embedded domain specific language (EDSL) that allows you to

  • define types representing tables and columns,
  • construct type safe queries checked at compile time for syntax errors, type errors, name errors and even some semantic errors,
  • interpret results by iterating over query-specific structs with appropriately named and typed members.

This results in several benefits, e.g.

  • the library user operates comfortably on structs and functions,
  • the compiler reports many kinds of errors long before the code enters unit testing or production,
  • the library hides the gory details of string construction for queries and interpreting results returned by select calls.

The library supports both static and dynamic queries. The former offers greater benefit in terms of type and consistency checking. The latter makes it easier to construct queries in flight.

sqlpp11s core is vendor-neutral. Specific traits of databases (e.g. unsupported or non-standard features) are handled by connector libraries. Connector libraries can inform the developer of missing features at compile time. They also interpret expressions specifically where needed. For example, the connector could use the operator|| or the concat method for string concatenation without the developer being required to change the statement.

Connectors for MariaDB, MySQL, PostgreSQL, sqlite3, sqlcipher are included in this repository.

The library is already used in production but it is certainly not complete yet. Feature requests, bug reports, contributions to code or documentation are most welcome.

Examples:

For the examples, lets assume you have a table class representing something like

CREATE TABLE foo (
    id bigint,
    name varchar(50),
    hasFun bool
);

And we assume to have a database connection object:

TabFoo foo;
Db db(/* some arguments*/);

// selecting zero or more results, iterating over the results
for (const auto& row : db(select(foo.name, foo.hasFun).from(foo).where(foo.id > 17 and foo.name.like("%bar%"))))
{
    if (row.name.is_null())
        std::cerr << "name is null, will convert to empty string" << std::endl;
    std::string name = row.name;   // string-like fields are implicitly convertible to string
    bool hasFun = row.hasFun;          // bool fields are implicitly convertible to bool
}

// selecting ALL columns of a table
for (const auto& row : db(select(all_of(foo)).from(foo).where(foo.hasFun or foo.name == "joker")))
{
    int64_t id = row.id; // numeric fields are implicitly convertible to numeric c++ types
}

// selecting zero or one row, showing off with an alias:
SQLPP_ALIAS_PROVIDER(cheese);
if (const auto& row = db(select(foo.name.as(cheese)).from(foo).where(foo.id == 17)))
{
    std::cerr << "found: " << row.cheese << std::endl;
}

// selecting a single row with a single result:
return db(select(count(foo.id)).from(foo).unconditionally()).front().count;

Of course there are joins and subqueries, more functions, order_by, group_by etc.
These will be documented soon.

// A sample insert
db(insert_into(foo).set(foo.id = 17, foo.name = "bar", foo.hasFun = true));

// A sample update
db(update(foo).set(foo.hasFun = not foo.hasFun).where(foo.name != "nobody"));

// A sample delete
db(remove_from(foo).where(not foo.hasFun));

License:

sqlpp11 is distributed under the BSD 2-Clause License.

Status:

Branch / Compiler clang, gcc MSVC Test Coverage
master Build Status Build status Coverage Status
develop Build Status Build status Coverage Status

Additional information available:

Past talks about sqlpp11 and some coding concepts used within the library:

Requirements:

Compiler: sqlpp11 makes heavy use of C++11 and requires a recent compiler and STL. The following compilers are known to compile the test programs:

  • clang-3.4+ on Ubuntu-12.4
  • g++-4.8+ on Ubuntu-12.4
  • g++-4.8+ on cygwin 64bit
  • g++-4.9+ on Debian Unstable
  • Xcode-7 on OS X
  • MSVC 2015 Update 1 on Windows Server 2012

Database Connector: sqlpp11 requires a certain api in order to connect with the database, see database/api.h.

This repository includes the following connectors:

  • MySQL
  • MariaDB
  • SQLite3
  • SQLCipher
  • PostgreSQL

Other connectors can be found here:

Date Library: sqlpp11 requires Howard Hinnants date library for date and date_time data types. By default, sqlpp11 uses FetchContent to pull the library automatically in the project. If you want to use an already installed version of the library with find_package, set USE_SYSTEM_DATE option to ON.

Build and Install

Note: Depending on how you use the lib, you might not need to install it (see Basic Usage)

Build from Source:

Download and unpack the latest release from https://github.com/rbock/sqlpp11/releases or clone the repository. Inside the directory run the following commands:

cmake -B build
cmake --build build --target install

The last step will build the library and install it system wide, therefore it might need admins rights.

By default only the core library will be installed. To also install connectors set the appropriate variable to ON:

  • BUILD_MYSQL_CONNECTOR
  • BUILD_MARIADB_CONNECTOR
  • BUILD_POSTGRESQL_CONNECTOR
  • BUILD_SQLITE3_CONNECTOR
  • BUILD_SQLCIPHER_CONNECTOR

The library will check if all required dependencies are installed on the system. If connectors should be installed even if the dependencies are not yet available on the system, set DEPENDENCY_CHECK to OFF.

Example: Install the core library, sqlite3 connector and postgresql connector. Dont check if the dependencies such as Sqlite3 are installed and dont build any tests:

cmake -B build -DBUILD_POSTGRESQL_CONNECTOR=ON -DBUILD_SQLITE3_CONNECTOR=ON -DDEPENDENCY_CHECK=OFF -DBUILD_TESTING=OFF
cmake --build build --target install

Install via Homebrew (MacOS):

brew install marvin182/zapfhahn/sqlpp11

Some connectors can be installed with the formula. See brew info marvin182/zapfhahn/sqlpp11 for available options.

Build via vcpkg:

You can download and install sqlpp11 using the vcpkg dependency manager:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install sqlpp11

The sqlpp11 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

The following connector libraries for sqlpp11 are maintained as a separate package in vcpkg:

Basic usage:

Use with cmake: The library officially supports two ways how it can be used with cmake. You can find examples for both methods in the examples folder.

  1. FetchContent (Recommended, no installation required)
  2. FindPackage (installation required, see above)

Both methods will provide the sqlpp11::sqlpp11 target as well as targets for each connector:

  • sqlpp11::mysql
  • sqlpp11::mariadb
  • sqlpp11::sqlite3
  • sqlpp11::sqlcipher
  • sqlpp11::postgresql

These targets will make sure all required dependencies are available and correctly linked and include directories are set correctly.

Create DDL files:

mysql: 'show create table MyDatabase.MyTable' #or
mysqldump --no-data MyDatabase > MyDatabase.sql

Create headers for them with provided Python script:

%sqlpp11_dir%/scripts/ddl2cpp ~/temp/MyTable.ddl  ~/temp/MyTable %DatabaseNamespaceForExample%

In case youre getting notes about unsupported column type consider:

  • Take a look at the other datatypes in sqlpp11/data_types. They are not hard to implement.
  • Use the --datatype-file command line argument as described below.

Include generated header (MyTable.h), thats all.

If you prefer Ruby over Python, you might want to take a look at https://github.com/douyw/sqlpp11gen

Unsupported column types:

Map unsupported column types to supported column types with a csv file:

One can use the --datatype-file command line argument for the ddl2cpp script to map unsupported column types to supported column types.

The format of the csv file is:

<dataType>, <col_type1>, <col_type2>
<dataType>, <col_type3>

Where <dataType> is one or more of the following internal types:

  • Boolean
  • Integer
  • Serial
  • FloatingPoint
  • Text
  • Blob
  • Date
  • DateTime
  • Time

Example:

Boolean, one_or_zero
Text, url, uuid

Contact: