diff --git a/README.md b/README.md index 0305b2b4f..79a6af76a 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,11 @@ [![Linux GCC/Clang Qt6.2 TinyDrivers][action-linux-qt6-drivers-badge]][action-linux-qt6-drivers] [![TinyORM - www.tinyorm.org][docs-badge]][docs] -[![License MIT][license-badge]][license] +[![License MIT][license-badge]][license]
[![TinyORM v0.36.5][version-tinyorm-badge]][docs] [![tom v0.7.0][version-tom-badge]][docs-tom] +[![TinyDrivers v0.1.0][version-tinydrivers-badge]][docs-tinydrivers] +[![TinyMySql v0.1.0][version-tinymysql-badge]][docs-tinydrivers] TinyORM is a modern ORM library that makes interacting with a database extremely simple. @@ -55,6 +57,18 @@ Whole library is documented as markdown documents: ### Features Summary +The following list summarizes all the `TinyDrivers` and `TinyMySql` libraries' features. 🆕 + + - both, normal and prepared statements are supported + - TLS/SSL connections using [`MYSQL_OPT_SSL_MODE`](https://dev.mysql.com/doc/c-api/en/mysql-options.html) (verify_ca, verify_identity) 🔥 + - setting many other connection options (see [`mysqldriver_p.cpp`](https://github.com/silverqx/TinyORM/blob/main/drivers/mysql/src/orm/drivers/mysql/mysqldriver_p.cpp)) + - building and linking against the [`MariaDB Connector/C`](https://mariadb.com/kb/en/mariadb-connector-c/) + - transactions + - re-using the current `SqlQuery` instance to re-execute the same or another query + - detaching from the result set (associated to release memory) + - query size, number of affected rows, last inserted ID, testing `isNull()`, ... + - all __3269 unit tests__ passed 😮 + The following list fastly summarizes all the `TinyORM` features. - __simple database connections management__ 🧬 @@ -143,7 +157,10 @@ The following list fastly summarizes all the `TinyORM` features. [docs-badge]: https://img.shields.io/badge/Docs-www.tinyorm.org-blue [docs]: https://www.tinyorm.org [docs-tom]: https://www.tinyorm.org/database/migrations +[docs-tinydrivers]: https://www.tinyorm.org/tinydrivers/getting-started [license-badge]: https://img.shields.io/github/license/silverqx/TinyORM [license]: https://github.com/silverqx/TinyORM/blob/main/LICENSE [version-tinyorm-badge]: https://img.shields.io/badge/TinyORM-v0.36.5-blue [version-tom-badge]: https://img.shields.io/badge/tom-v0.7.0-blue +[version-tinydrivers-badge]: https://img.shields.io/badge/TinyDrivers-v0.1.0-blue +[version-tinymysql-badge]: https://img.shields.io/badge/TinyMySql-v0.1.0-blue diff --git a/docs/README.mdx b/docs/README.mdx index 0831a840c..3303c1c2a 100644 --- a/docs/README.mdx +++ b/docs/README.mdx @@ -47,3 +47,5 @@ If you don't want to use full [`ORM`](tinyorm/getting-started.mdx), then you can - __TinyORM__ v0.36.5 - __tom__ v0.7.0 +- __TinyDrivers__ v0.1.0 +- __TinyMySql__ v0.1.0 diff --git a/docs/building/_category_.yml b/docs/building/_category_.yml index 66acc4372..005d275a0 100644 --- a/docs/building/_category_.yml +++ b/docs/building/_category_.yml @@ -1,2 +1,2 @@ -position: 5 +position: 6 label: '🚧 Building' diff --git a/docs/building/tinyorm.mdx b/docs/building/tinyorm.mdx index 53ea8cdfe..18d2ccbc2 100644 --- a/docs/building/tinyorm.mdx +++ b/docs/building/tinyorm.mdx @@ -488,9 +488,12 @@ CMake multi-config generators like `Ninja Multi-Config` or `Visual Studio 16 201 | Option Name | Default | Description | | --------------------------------- | ------- | ----------- | +| `BUILD_DRIVERS` | `OFF` | Build [`TinyDrivers`](tinydrivers/getting-started.mdx) SQL database drivers (core/common code; replaces QtSql module). | +| `BUILD_MYSQL_DRIVERS` | `OFF` | Build `TinyDrivers` MySQL database driver.
Available when: `BUILD_DRIVERS` | | `BUILD_SHARED_LIBS` | `ON` | Build as a shared/static library. | | `BUILD_TESTS` | `OFF` | Build TinyORM unit tests. | | `BUILD_TREE_DEPLOY` | `ON` | Copy `TinyDrivers` and `TinyMySql` libraries to the root of the build tree. | +| `DRIVERS_TYPE` | `Shared`| How to build and link against `TinyDrivers` SQL database drivers.
The `Static` value will be select by default when the `BUILD_SHARED_LIBS` is `OFF`.
Supported values: `Shared`, `Loadable`, and `Static`
Available when: `BUILD_DRIVERS AND BUILD_SHARED_LIBS` | | `INLINE_CONSTANTS` | `OFF` | Use inline constants instead of extern constants in the `shared build`.
`OFF` is highly recommended for the `shared build`;
is always `ON` for the `static build`.
Available when: `BUILD_SHARED_LIBS` | | `MSVC_RUNTIME_DYNAMIC` | `ON` | Use MSVC dynamic runtime library (`-MD`) instead of static (`-MT`), also considers a Debug configuration (`-MTd`, `-MDd`).
Available when: `MSVC AND NOT DEFINED CMAKE_MSVC_RUNTIME_LIBRARY` | | `MYSQL_PING` | `OFF` | Enable `Orm::MySqlConnection::pingDatabase()` method. | @@ -753,6 +756,10 @@ Everything is ready for build, you can press Ctrl+b to bui | `CONFIG` Option Name | Default | Description | | ----------------------------------- | ------- | ----------- | +| `build_loadable_drivers` | `OFF` | Build `TinyDrivers` as a shared library and SQL database drivers (eg. `TinyMySql`) as shared libraries ([`Loadable`](tinydrivers/getting-started.mdx#the-loadable-sql-drivers-build) modules) that are loaded at runtime using `LoadLibrary()` on Windows or `dlopen()` on Linux. | +| `build_mysql_driver` | `OFF` | Build `TinyDrivers` MySQL database driver.
It's enabled by default when `build_shared_drivers`, `build_loadable_drivers`, or `build_static_drivers` is enabled.
Available when: `build_shared_drivers` OR `build_loadable_drivers` OR `build_static_drivers` | +| `build_shared_drivers` | `OFF` | Build `TinyDrivers` as a [`Shared`](tinydrivers/getting-started.mdx#the-shared-library-build) library. | +| `build_static_drivers` | `OFF` | Build `TinyDrivers` as a [`Static`](tinydrivers/getting-started.mdx#the-static-build) library archive.
The `build_static_drivers` `qmake` configuration option will be select by default when the `CONFIG*=staticlib` is enabled. | | `build_tests` | `OFF` | Build TinyORM unit tests. | | `disable_autoconf` | `OFF` | Disable the [`Auto-configuration`](#auto-configuration-internals) feature (auto-configuration is enabled by default from `TinyORM` `v0.34.0`). | | `disable_dotenv` | `OFF` | Disable the [`tiny_dotenv`](#environment-files) feature (environment files are enabled by default from `TinyORM` `v0.34.0`). | diff --git a/docs/features-summary.mdx b/docs/features-summary.mdx index d86939bf4..c88d27e25 100644 --- a/docs/features-summary.mdx +++ b/docs/features-summary.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 sidebar_label: 📄 Features Summary hide_table_of_contents: true description: List that fastly summarizes all TinyORM features. @@ -62,6 +62,10 @@ The following list fastly summarizes all the `TinyORM` features. - extensive documentation 📃 - ... +:::info +See the `TinyDrivers` [Features summary](tinydrivers/getting-started#features-summary). +::: + ## Showcase Images ###### Tom console application diff --git a/docs/sponsors.mdx b/docs/sponsors.mdx index 44ebb9b46..ac9ad7044 100644 --- a/docs/sponsors.mdx +++ b/docs/sponsors.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 sidebar_label: ❤️ Sponsors hide_table_of_contents: true description: How to sponsor and support the TinyORM project. diff --git a/docs/tinydrivers/_category_.yml b/docs/tinydrivers/_category_.yml new file mode 100644 index 000000000..99cf9414c --- /dev/null +++ b/docs/tinydrivers/_category_.yml @@ -0,0 +1,2 @@ +position: 5 +label: '🧬 TinyDrivers' diff --git a/docs/tinydrivers/getting-started.mdx b/docs/tinydrivers/getting-started.mdx new file mode 100644 index 000000000..5f2452922 --- /dev/null +++ b/docs/tinydrivers/getting-started.mdx @@ -0,0 +1,122 @@ +--- +sidebar_position: 0 +sidebar_label: Getting Started +description: TinyORM makes interacting with a database extremely simple using raw SQL, a fluent query builder, and the TinyORM. It provides first-party support for four databases MySQL/MariaDB, PostgreSQL, and SQLite. +keywords: [c++ orm, database, getting started, tinydrivers, sql drivers] +--- + +# TinyDrivers: Getting Started + +- [Introduction](#introduction) +- [Differences from QtSql](#differences-from-qtsql) + - [Build system](#build-system) + - [Performance](#performance) +- [Internals](#internals) + +## Introduction + +The `TinyDrivers` library is an underlying SQL database layer for `TinyORM`. It can be used instead of the `QtSql` module, can be __swapped__ at compile, and has __1:1__ API as the `QtSql` module. 😮 Swapping is controlled by the `qmake` and `CMake` build system options. + +It was designed to drop the `QtSql` dependency while maintaining backward compatibility and without the need for any code changes after the swap. + +##### Features summary + + - both, normal and prepared statements are supported + - TLS/SSL connections using [`MYSQL_OPT_SSL_MODE`](https://dev.mysql.com/doc/c-api/en/mysql-options.html) (verify_ca, verify_identity) 🔥 + - setting many other connection options (see [`mysqldriver_p.cpp`](https://github.com/silverqx/TinyORM/blob/main/drivers/mysql/src/orm/drivers/mysql/mysqldriver_p.cpp)) + - building and linking against the [`MariaDB Connector/C`](https://mariadb.com/kb/en/mariadb-connector-c/) + - transactions + - re-using the current `SqlQuery` instance to re-execute the same or another query + - detaching from the result set (associated to release memory) + - query size, number of affected rows, last inserted ID, testing `isNull()`, ... + - all __3269 unit tests__ passed 😮 + +:::info +Currently, only the `MySQL` database driver is supported and finished. +::: + +:::info +`TinyDrivers` can only be built with `Qt v6`, `Qt v5.15` isn't supported. +::: + +:::note +`TinyDrivers` library supports both build systems `qmake` and also `CMake`. +::: + +## Differences from QtSql + +`TinyDrivers` doesn't return errors the the same way as the `QtSql` module, which means return a `bool` and if it's the result `false` then obtain the `SqlError` instance using the `lastError()` method from `SqlDatabase` or `SqlQuery` instances. Instead, it throws exceptions, and methods returning a `bool` type to report an error state always return `true`. + +##### Removed features + +Simulation of prepared statements while calling `SqlQuery::exec(QString)`, this functionality is useless because you can call regular prepared statements using `SqlQuery::prepare(QString)` and then `SqlQuery::exec()`. + +##### Missing features + +Fetching multiple result sets using `SqlQuery::nextResult()`. Multiple statement queries are supported they will be executed correctly (they can return multiple result sets), but only the first result set can be fetched currently. However, destroying multiple result sets is handled correctly. + +### Build system + +Another difference is that you can build the `TinyDrivers` and its SQL drivers (`TinyMySql`) in 3 different ways; `Shared`, `Static`, and as a `Loadable` library at runtime using `LoadLibrary()` on Windows or `dlopen()` on Linux. + +##### The `Shared` library build + +It builds two shared libraries, the `TinyDrivers` shared library that contains the core/common code and the `TinyMySql` shared library that contains `MySQL` implementation. The `TinyOrm` links only against the `TinyDrivers` shared library and `TinyMySql` is a private implementation. + +##### The `Static` build + +It builds one `TinyDrivers` static archive that contains the core/common code and SQL drivers (`TinyMySql`). This static library is linked or merged into the `TinyOrm` shared or static library (both variants are supported). + +##### The `Loadable` SQL drivers build + +It builds two shared libraries, the `TinyDrivers` shared library that contains the core/common code and `TinyMySql` shared library (module) that contains `MySQL` implementation that is loaded at runtime using `LoadLibrary()` on Windows or `dlopen()` on Linux. The SQL driver library loader throws an exception if it cannot find this library at runtime. + +:::info +The `TinyMySql` links directly against the `MySQL C connector` (`libmysql` or `mysqlclient` library). +::: + +#### `CMake`/`qmake` build options + +##### For `CMake` + +See [CMake build options](building/tinyorm.mdx#cmake-build-options), related `CMake` build options are:
[`BUILD_DRIVERS`](building/tinyorm.mdx#BUILD_DRIVERS), [`BUILD_MYSQL_DRIVERS`](building/tinyorm.mdx#BUILD_MYSQL_DRIVERS), and [`DRIVERS_TYPE`](building/tinyorm.mdx#DRIVERS_TYPE) + +To control shared and static build use [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) `CMake` configuration option. + +##### For `qmake` + +See [qmake build options](building/tinyorm.mdx#qmake-build-options), related `qmake` configuration options are:
[`build_loadable_drivers`](building/tinyorm.mdx#build_loadable_drivers), [`build_mysql_driver`](building/tinyorm.mdx#build_mysql_driver), [`build_shared_drivers`](building/tinyorm.mdx#build_shared_drivers), and [`build_static_drivers`](building/tinyorm.mdx#build_static_drivers) + +To control shared and static build use [`staticlib`](https://doc.qt.io/qt/qmake-variable-reference.html#config) `qmake` configuration option. + +### Performance + +Performance is several milliseconds faster compared to `QtSql` with the `QMYSQL` driver. It was tuned using the `KCacheGrind` to be so. It's ~40ms faster on [`TinyOrmPlayground`](https://github.com/silverqx/TinyOrmPlayground) project with __620__ database queries compiled using `GCC v13.2.1` Debug build on Linux. Similar results can be expected on other platforms but it's not guaranteed. + +This means performance is very similar to `QtSql`. There is not much to speed up because `TinyDrivers` code is swift and 90% of the time is spent inside the [`MySQL C API`](https://dev.mysql.com/doc/c-api/en/) because we always have to wait for the database server, especially when creating database connections using eg. [`mysql_real_connect()`](https://dev.mysql.com/doc/c-api/en/mysql-real-connect.html) (this function is king among the slowest functions 😎, which is understandable of course). + +## Internals + +`TinyDrivers` internal design can be divided into 3 different layers: + + - Driver layer + - SQL API layer + - Public API layer + +The Driver layer is eg. `TinyMySql` library which is responsible for communicating with the underlying database driver (eg. [`MySQL C API`](https://dev.mysql.com/doc/c-api/en/)). + +The SQL API layer is a semi-layer that glues everything up and sits between the Public interface API and the Driver layer. + +The Public interface API layer are the end classes like `SqlDatabase` and `SqlQuery` which are exposed to the end user. + +##### SqlDatabase + +One more thing worth mentioning is the `SqlDatabase` API. It's one class that has two responsibilities! All static methods act as the database connection manager and an instance of the `SqlDatabase` represents a physical database connection. It's not a good design because it breaks the [Single Responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle), but it's what it is. + +##### Namespaces + +`TinyDrivers` classes are defined in the `Orm::Drivers` namespace and `TinyMySql` classes in the `Orm::Drivers::MySql` namespace. + +##### Documentation + +For all other APIs you can follow the [QtSql documentation](https://doc.qt.io/qt/qtsql-index.html) as the API is 1:1. The exception is of course the build system, `TinyOrm` has its own build system that doesn't follow the `QtSql` module. diff --git a/tools/deploy.ps1 b/tools/deploy.ps1 index 72f4d7d35..9e7a17c61 100644 --- a/tools/deploy.ps1 +++ b/tools/deploy.ps1 @@ -50,7 +50,7 @@ $Script:BumpCommitMessage = $null # Base template RegEx to match Number of Unit Tests in all files $Script:NumberOfUnitTestsRegExTmpl = - '(?(?:with|currently|then) (?:__)?)(?{0})(?(?:__)? unit (?:and|tests))' + '(?(?:with|currently|then|all) (?:__)?)(?{0})(?(?:__)? unit (?:and|tests))' # RegEx to match Number of Unit Tests in all files $Script:NumberOfUnitTestsRegEx = $Script:NumberOfUnitTestsRegExTmpl -f '\d{1,2} ?\d{3}' # The current Number of unit tests found in the README.md file @@ -156,6 +156,19 @@ function Initialize-ScriptVariables { [VersionType]::VersionOnly = [ordered] @{ (Resolve-Path -Path ./tom/src/tom/commands/aboutcommand.cpp) = 1 } + # RegEx: (?v0\.0\.0) + [VersionType]::VersionWith_v = [ordered] @{ + (Resolve-Path -Path ./README.md) = 2 + (Resolve-Path -Path ./docs/README.mdx) = 1 + } + } + + TinyMySql = @{ + # RegEx: (?v0\.0\.0) + [VersionType]::VersionWith_v = [ordered] @{ + (Resolve-Path -Path ./README.md) = 2 + (Resolve-Path -Path ./docs/README.mdx) = 1 + } } # TinyUtils doesn't have any version numbers in files @@ -165,10 +178,11 @@ function Initialize-ScriptVariables { $Script:NumberOfUnitTestsLocations = [ordered] @{ # The README.md will be read from to populate the current number of unit tests using this # RegEx: with __(?\d{1,2} ?\d{3})__ unit - (Resolve-Path -Path ./README.md) = 2 - (Resolve-Path -Path ./docs/features-summary.mdx) = 1 - (Resolve-Path -Path ./docs/README.mdx) = 2 - (Resolve-Path -Path ./docs/supported-compilers.mdx) = 1 + (Resolve-Path -Path ./README.md) = 3 + (Resolve-Path -Path ./docs/features-summary.mdx) = 1 + (Resolve-Path -Path ./docs/README.mdx) = 2 + (Resolve-Path -Path ./docs/supported-compilers.mdx) = 1 + (Resolve-Path -Path ./docs/tinydrivers/getting-started.mdx) = 1 } $Script:VcpkgHash = [ordered] @{ @@ -877,7 +891,9 @@ function Edit-VersionNumbersInAllFiles { Write-Progress 'Editing bumped version numbers in all files...' foreach ($versionLocationsAll in $Script:VersionLocations.GetEnumerator()) { - $bumpValue = $Script:BumpsHash[$versionLocationsAll.Name] + $libraryName = $versionLocationsAll.Name + $bumpValue = $Script:BumpsHash[$libraryName] + $isTinyDriversOrMySql = $libraryName -in @('TinyDrivers', 'TinyMySql') # Nothing to edit if ($bumpValue.type -eq [BumpType]::None) { @@ -892,6 +908,13 @@ function Edit-VersionNumbersInAllFiles { # Prepend the v character to better target the replacement (be more accurate) if ($versionType -eq [VersionType]::VersionWith_v) { $versionOld = 'v' + $versionOld + + # Currently, TinyDrivers and TinyMySql have the same version number so replacing + # doesn't work, we must be more specific to better target the version number to + # search. + if ($isTinyDriversOrMySql) { + $regex = "(?$libraryName(?:__ | |-))" + } } # Can't precede the v character else { @@ -917,6 +940,12 @@ function Edit-VersionNumbersInAllFiles { # Prepend the v character (follow/copy the old version number format) if ($versionType -eq [VersionType]::VersionWith_v) { $versionBumped = 'v' + $versionBumped + + # Also, we must prepend what was there before for this special case (same + # version numbers). + if ($isTinyDriversOrMySql) { + $versionBumped = "`${before}$versionBumped" + } } # Replace the old version number with the bumped version number