diff --git a/404.html b/404.html index 7a3767199..654ab3110 100644 --- a/404.html +++ b/404.html @@ -14,7 +14,7 @@ - +
diff --git a/assets/js/cb1e72f9.35c45e85.js b/assets/js/cb1e72f9.35c45e85.js deleted file mode 100644 index c1f13a7fe..000000000 --- a/assets/js/cb1e72f9.35c45e85.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunktinyorm_org=self.webpackChunktinyorm_org||[]).push([[258],{6349:(e,i,n)=>{n.r(i),n.d(i,{assets:()=>c,contentTitle:()=>l,default:()=>u,frontMatter:()=>t,metadata:()=>a,toc:()=>o});var r=n(4848),s=n(8453),d=n(8774);const t={sidebar_position:0,sidebar_label:"Getting Started",description:"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 time, 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.",keywords:["c++ orm","database","getting started","tinydrivers","sql drivers"]},l="TinyDrivers: Getting Started",a={id:"tinydrivers/getting-started",title:"TinyDrivers: Getting Started",description:"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 time, 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.",source:"@site/docs/tinydrivers/getting-started.mdx",sourceDirName:"tinydrivers",slug:"/tinydrivers/getting-started",permalink:"/tinydrivers/getting-started",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:0,frontMatter:{sidebar_position:0,sidebar_label:"Getting Started",description:"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 time, 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.",keywords:["c++ orm","database","getting started","tinydrivers","sql drivers"]},sidebar:"tinyormSidebar",previous:{title:"Serialization",permalink:"/tinyorm/serialization"},next:{title:"TinyORM",permalink:"/building/tinyorm"}},c={},o=[{value:"Introduction",id:"introduction",level:2},{value:"Features summary",id:"features-summary",level:4},{value:"Differences from QtSql",id:"differences-from-qtsql",level:2},{value:"Naming conventions",id:"naming-conventions",level:5},{value:"MySQL driver",id:"mysql-driver",level:5},{value:"Removed features",id:"removed-features",level:5},{value:"Missing features",id:"missing-features",level:5},{value:"Build system",id:"build-system",level:3},{value:"TheShared
library build",id:"the-shared-library-build",level:5},{value:"The Static
build",id:"the-static-build",level:5},{value:"The Loadable
SQL drivers build",id:"the-loadable-sql-drivers-build",level:5},{value:"CMake
/qmake
build options",id:"cmakeqmake-build-options",level:4},{value:"For CMake
",id:"for-cmake",level:5},{value:"For qmake
",id:"for-qmake",level:5},{value:"Performance",id:"performance",level:3},{value:"Internals",id:"internals",level:2},{value:"SqlDatabase",id:"sqldatabase",level:5},{value:"Namespaces",id:"namespaces",level:5},{value:"Documentation",id:"documentation",level:5}];function h(e){const i={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",header:"header",li:"li",p:"p",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(i.header,{children:(0,r.jsx)(i.h1,{id:"tinydrivers-getting-started",children:"TinyDrivers: Getting Started"})}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.a,{href:"#introduction",children:"Introduction"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#features-summary",children:"Features summary"})}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.a,{href:"#differences-from-qtsql",children:"Differences from QtSql"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#build-system",children:"Build system"})}),"\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#performance",children:"Performance"})}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#internals",children:"Internals"})}),"\n"]}),"\n",(0,r.jsx)(i.h2,{id:"introduction",children:"Introduction"}),"\n",(0,r.jsx)("div",{className:"api-stability alert alert--success",children:(0,r.jsxs)(i.p,{children:[(0,r.jsx)(d.A,{to:"/stability#stability-indexes",children:(0,r.jsx)(i.strong,{children:"Stability: 2"})})," - Stable"]})}),"\n",(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," library is an underlying SQL database layer for ",(0,r.jsx)(i.code,{children:"TinyORM"}),". It can be used instead of the ",(0,r.jsx)(i.code,{children:"QtSql"})," module, can be ",(0,r.jsx)("u",{children:(0,r.jsx)(i.strong,{children:"swapped"})})," at compile time, and has ",(0,r.jsx)(i.strong,{children:"1:1"})," API as the ",(0,r.jsx)(i.code,{children:"QtSql"})," module. \ud83d\ude2e Swapping is controlled by the ",(0,r.jsx)(i.code,{children:"qmake"})," and ",(0,r.jsx)(i.code,{children:"CMake"})," build system options."]}),"\n",(0,r.jsxs)(i.p,{children:["It was designed to drop the ",(0,r.jsx)(i.code,{children:"QtSql"})," dependency while maintaining backward compatibility and without the need for any code changes after the swap."]}),"\n",(0,r.jsx)(i.h4,{id:"features-summary",children:"Features summary"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:"both, normal and prepared statements are supported"}),"\n",(0,r.jsxs)(i.li,{children:["TLS/SSL connections using ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:(0,r.jsx)(i.code,{children:"MYSQL_OPT_SSL_MODE"})})," (verify_ca, verify_identity) \ud83d\udd25"]}),"\n",(0,r.jsxs)(i.li,{children:["setting many other MySQL connection options (see ",(0,r.jsx)(i.a,{href:"https://github.com/silverqx/TinyORM/blob/main/drivers/mysql/src/orm/drivers/mysql/mysqldriver_p.cpp",children:(0,r.jsx)(i.code,{children:"mysqldriver_p.cpp"})}),")"]}),"\n",(0,r.jsxs)(i.li,{children:["building and linking against the ",(0,r.jsx)(i.a,{href:"https://mariadb.com/kb/en/mariadb-connector-c/",children:(0,r.jsx)(i.code,{children:"MariaDB Connector/C"})})," \ud83d\udd7a"]}),"\n",(0,r.jsx)(i.li,{children:"transactions"}),"\n",(0,r.jsxs)(i.li,{children:["re-using the current ",(0,r.jsx)(i.code,{children:"SqlQuery"})," instance to re-execute the same or another SQL query"]}),"\n",(0,r.jsx)(i.li,{children:"detaching from the result set (related to freeing/releasing memory)"}),"\n",(0,r.jsxs)(i.li,{children:["query size, number of affected rows, last inserted ID, testing ",(0,r.jsx)(i.code,{children:"isNull()"}),", ..."]}),"\n",(0,r.jsxs)(i.li,{children:["all ",(0,r.jsx)(i.strong,{children:"3378 unit tests"})," passed \ud83d\ude2e"]}),"\n",(0,r.jsxs)(i.li,{children:["strictly using ",(0,r.jsx)(i.strong,{children:"smart pointers"})," (no ",(0,r.jsx)(i.code,{children:"new"})," keyword in the whole ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," code base \ud83d\ude0e)"]}),"\n",(0,r.jsx)(i.li,{children:"clear code \ud83e\udd14"}),"\n"]}),"\n",(0,r.jsx)(i.admonition,{type:"info",children:(0,r.jsxs)(i.p,{children:["Currently, only the ",(0,r.jsx)(i.code,{children:"MySQL"})," database driver is supported and finished. \ud83d\ude1e"]})}),"\n",(0,r.jsx)(i.admonition,{type:"note",children:(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," library supports both build systems ",(0,r.jsx)(i.code,{children:"qmake"})," and also ",(0,r.jsx)(i.code,{children:"CMake"}),"."]})}),"\n",(0,r.jsx)(i.h2,{id:"differences-from-qtsql",children:"Differences from QtSql"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," doesn't return errors the the same way as the ",(0,r.jsx)(i.code,{children:"QtSql"})," module, which means return a ",(0,r.jsx)(i.code,{children:"bool"})," and if it's the result ",(0,r.jsx)(i.code,{children:"false"})," then obtain the ",(0,r.jsx)(i.code,{children:"SqlError"})," instance using the ",(0,r.jsx)(i.code,{children:"lastError()"})," method from ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," or ",(0,r.jsx)(i.code,{children:"SqlQuery"})," instances. Instead, it throws exceptions, and methods returning a ",(0,r.jsx)(i.code,{children:"bool"})," type to report an error state always return ",(0,r.jsx)(i.code,{children:"true"}),"."]}),"\n",(0,r.jsx)(i.h5,{id:"naming-conventions",children:"Naming conventions"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.code,{children:"QtSql"})," ",(0,r.jsx)("small",{children:"module"})," -> ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," ",(0,r.jsx)("small",{children:"library"})]}),"\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.code,{children:"QMYSQL"})," ",(0,r.jsx)("small",{children:"driver"})," -> ",(0,r.jsx)(i.code,{children:"TinyMySql"})," ",(0,r.jsx)("small",{children:"driver"})]}),"\n"]}),"\n",(0,r.jsx)(i.h5,{id:"mysql-driver",children:"MySQL driver"}),"\n",(0,r.jsxs)(i.p,{children:["The following describes the differences between ",(0,r.jsx)(i.code,{children:"QMYSQL"})," and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," drivers."]}),"\n",(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"QMYSQL"})," driver doesn't support setting ",(0,r.jsx)(i.code,{children:"MySQL"})," non-flag ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:"connection options"})," like ",(0,r.jsx)(i.code,{children:"MYSQL_OPT_RECONNECT"})," without the value, it needs to be defined with value like ",(0,r.jsx)(i.code,{children:"=1"})," or ",(0,r.jsx)(i.code,{children:"=TRUE"})," (case-sensitive), only real flag options like ",(0,r.jsx)(i.code,{children:"CLIENT_INTERACTIVE"})," can be set without the value and ",(0,r.jsx)(i.code,{children:"="})," character."]}),"\n",(0,r.jsxs)(i.p,{children:["On the other hand, the ",(0,r.jsx)(i.code,{children:"TinyMySql"})," driver allows setting non-flag ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:"connection options"})," options without the value and ",(0,r.jsx)(i.code,{children:"="})," character, which are considered enabled (ON or TRUE)."]}),"\n",(0,r.jsx)(i.h5,{id:"removed-features",children:"Removed features"}),"\n",(0,r.jsxs)(i.p,{children:["Simulation of prepared statements while calling ",(0,r.jsx)(i.code,{children:"SqlQuery::exec(QString)"}),", this functionality is useless because you can call regular prepared statements using ",(0,r.jsx)(i.code,{children:"SqlQuery::prepare(QString)"})," and then ",(0,r.jsx)(i.code,{children:"SqlQuery::exec()"}),"."]}),"\n",(0,r.jsx)(i.h5,{id:"missing-features",children:"Missing features"}),"\n",(0,r.jsxs)(i.p,{children:["Fetching multiple result sets using ",(0,r.jsx)(i.code,{children:"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."]}),"\n",(0,r.jsx)(i.h3,{id:"build-system",children:"Build system"}),"\n",(0,r.jsxs)(i.p,{children:["Another difference is that you can build the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," and its SQL drivers (",(0,r.jsx)(i.code,{children:"TinyMySql"}),") in 3 different ways; ",(0,r.jsx)(i.code,{children:"Shared"}),", ",(0,r.jsx)(i.code,{children:"Static"}),", and as a ",(0,r.jsx)(i.code,{children:"Loadable"})," library at runtime using ",(0,r.jsx)(i.code,{children:"LoadLibrary()"})," on Windows or ",(0,r.jsx)(i.code,{children:"dlopen()"})," on Linux."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-shared-library-build",children:["The ",(0,r.jsx)(i.code,{children:"Shared"})," library build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds two shared libraries, the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library that contains the core/common code and the ",(0,r.jsx)(i.code,{children:"TinyMySql"})," shared library that contains ",(0,r.jsx)(i.code,{children:"MySQL"})," implementation. The ",(0,r.jsx)(i.code,{children:"TinyOrm"})," links only against the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," is a private implementation."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-static-build",children:["The ",(0,r.jsx)(i.code,{children:"Static"})," build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds one ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," static archive that contains the core/common code and SQL drivers (",(0,r.jsx)(i.code,{children:"TinyMySql"}),"). This static library is linked or merged into the ",(0,r.jsx)(i.code,{children:"TinyOrm"})," shared or static library (both variants are supported)."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-loadable-sql-drivers-build",children:["The ",(0,r.jsx)(i.code,{children:"Loadable"})," SQL drivers build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds two shared libraries, the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library that contains the core/common code and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," shared library (module) that contains ",(0,r.jsx)(i.code,{children:"MySQL"})," implementation that is loaded at runtime using ",(0,r.jsx)(i.code,{children:"LoadLibrary()"})," on Windows or ",(0,r.jsx)(i.code,{children:"dlopen()"})," on Linux. The SQL driver library loader throws an exception if it cannot find this library at runtime."]}),"\n",(0,r.jsx)(i.admonition,{type:"info",children:(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"TinyMySql"})," links directly against the ",(0,r.jsx)(i.code,{children:"MySQL C connector"})," (",(0,r.jsx)(i.code,{children:"libmysql"})," or ",(0,r.jsx)(i.code,{children:"mysqlclient"})," library)."]})}),"\n",(0,r.jsxs)(i.h4,{id:"cmakeqmake-build-options",children:[(0,r.jsx)(i.code,{children:"CMake"}),"/",(0,r.jsx)(i.code,{children:"qmake"})," build options"]}),"\n",(0,r.jsxs)(i.h5,{id:"for-cmake",children:["For ",(0,r.jsx)(i.code,{children:"CMake"})]}),"\n",(0,r.jsxs)(i.p,{children:["See ",(0,r.jsx)(i.a,{href:"/building/tinyorm#cmake-build-options",children:"CMake build options"}),", related ",(0,r.jsx)(i.code,{children:"CMake"})," build options are:",(0,r.jsx)("br",{}),(0,r.jsx)(i.a,{href:"/building/tinyorm#BUILD_DRIVERS",children:(0,r.jsx)(i.code,{children:"BUILD_DRIVERS"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#BUILD_MYSQL_DRIVER",children:(0,r.jsx)(i.code,{children:"BUILD_MYSQL_DRIVER"})}),", and ",(0,r.jsx)(i.a,{href:"/building/tinyorm#DRIVERS_TYPE",children:(0,r.jsx)(i.code,{children:"DRIVERS_TYPE"})})]}),"\n",(0,r.jsxs)(i.p,{children:["To control shared and static build use ",(0,r.jsx)(i.a,{href:"https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html",children:(0,r.jsx)(i.code,{children:"BUILD_SHARED_LIBS"})})," ",(0,r.jsx)(i.code,{children:"CMake"})," configuration option."]}),"\n",(0,r.jsxs)(i.h5,{id:"for-qmake",children:["For ",(0,r.jsx)(i.code,{children:"qmake"})]}),"\n",(0,r.jsxs)(i.p,{children:["See ",(0,r.jsx)(i.a,{href:"/building/tinyorm#qmake-build-options",children:"qmake build options"}),", related ",(0,r.jsx)(i.code,{children:"qmake"})," configuration options are:",(0,r.jsx)("br",{}),(0,r.jsx)(i.a,{href:"/building/tinyorm#build_loadable_drivers",children:(0,r.jsx)(i.code,{children:"build_loadable_drivers"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_mysql_driver",children:(0,r.jsx)(i.code,{children:"build_mysql_driver"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_shared_drivers",children:(0,r.jsx)(i.code,{children:"build_shared_drivers"})}),", and ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_static_drivers",children:(0,r.jsx)(i.code,{children:"build_static_drivers"})})]}),"\n",(0,r.jsxs)(i.p,{children:["To control shared and static build use ",(0,r.jsx)(i.a,{href:"/building/tinyorm#qmake-static",children:(0,r.jsx)(i.code,{children:"static"})})," ",(0,r.jsx)(i.code,{children:"qmake"})," ",(0,r.jsx)(i.a,{href:"https://doc.qt.io/qt/qmake-variable-reference.html#config",children:"configuration option"}),"."]}),"\n",(0,r.jsx)(i.h3,{id:"performance",children:"Performance"}),"\n",(0,r.jsxs)(i.p,{children:["Performance is several milliseconds faster compared to ",(0,r.jsx)(i.code,{children:"QtSql"})," with the ",(0,r.jsx)(i.code,{children:"QMYSQL"})," driver. It was tuned using the ",(0,r.jsx)(i.code,{children:"KCacheGrind"})," to be so. It's ~40ms faster on ",(0,r.jsx)(i.a,{href:"https://github.com/silverqx/TinyOrmPlayground",children:(0,r.jsx)(i.code,{children:"TinyOrmPlayground"})})," project with ",(0,r.jsx)(i.strong,{children:"620"})," database queries compiled using ",(0,r.jsx)(i.code,{children:"GCC v13.2.1"})," Debug build on Linux. Similar results can be expected on other platforms but it's not guaranteed."]}),"\n",(0,r.jsxs)(i.p,{children:["This means performance is very similar to ",(0,r.jsx)(i.code,{children:"QtSql"}),". There is not much to speed up because ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," code is swift and 90% of the time is spent inside the ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/",children:(0,r.jsx)(i.code,{children:"MySQL C API"})})," because we always have to wait for the database server, especially when creating database connections using eg. ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-real-connect.html",children:(0,r.jsx)(i.code,{children:"mysql_real_connect()"})})," (this function is king among the slowest functions \ud83d\ude0e, which is understandable of course)."]}),"\n",(0,r.jsx)(i.h2,{id:"internals",children:"Internals"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," internal design can be divided into 3 different layers:"]}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:"Driver layer"}),"\n",(0,r.jsx)(i.li,{children:"SQL API layer"}),"\n",(0,r.jsx)(i.li,{children:"Public API layer"}),"\n"]}),"\n",(0,r.jsxs)(i.p,{children:["The Driver layer is eg. ",(0,r.jsx)(i.code,{children:"TinyMySql"})," library which is responsible for communicating with the underlying database driver (eg. ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/",children:(0,r.jsx)(i.code,{children:"MySQL C API"})}),")."]}),"\n",(0,r.jsx)(i.p,{children:"The SQL API layer is a semi-layer that glues everything up and sits between the Public interface API and the Driver layer."}),"\n",(0,r.jsxs)(i.p,{children:["The Public interface API layer are the end classes like ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," and ",(0,r.jsx)(i.code,{children:"SqlQuery"})," which are exposed to the end user."]}),"\n",(0,r.jsx)(i.h5,{id:"sqldatabase",children:"SqlDatabase"}),"\n",(0,r.jsxs)(i.p,{children:["One more thing worth mentioning is the ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," API. It's one class that has two responsibilities! All static methods act as the database connection manager and an instance of the ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," represents a physical database connection. It's not a good design because it breaks the ",(0,r.jsx)(i.a,{href:"https://en.wikipedia.org/wiki/Single_responsibility_principle",children:"Single Responsibility principle"}),", but it's what it is."]}),"\n",(0,r.jsx)(i.h5,{id:"namespaces",children:"Namespaces"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," classes are defined in the ",(0,r.jsx)(i.code,{children:"Orm::Drivers"})," namespace and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," classes in the ",(0,r.jsx)(i.code,{children:"Orm::Drivers::MySql"})," namespace."]}),"\n",(0,r.jsx)(i.h5,{id:"documentation",children:"Documentation"}),"\n",(0,r.jsxs)(i.p,{children:["For all other APIs you can follow the ",(0,r.jsx)(i.a,{href:"https://doc.qt.io/qt/qtsql-index.html",children:"QtSql documentation"})," as the API is 1:1. The exception is of course the build system, ",(0,r.jsx)(i.code,{children:"TinyOrm"})," has its own build system that doesn't follow the ",(0,r.jsx)(i.code,{children:"QtSql"})," module."]})]})}function u(e={}){const{wrapper:i}={...(0,s.R)(),...e.components};return i?(0,r.jsx)(i,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453:(e,i,n)=>{n.d(i,{R:()=>t,x:()=>l});var r=n(6540);const s={},d=r.createContext(s);function t(e){const i=r.useContext(d);return r.useMemo((function(){return"function"==typeof e?e(i):{...i,...e}}),[i,e])}function l(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:t(e.components),r.createElement(d.Provider,{value:i},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/cb1e72f9.d9a03d3d.js b/assets/js/cb1e72f9.d9a03d3d.js
new file mode 100644
index 000000000..76a9bccc5
--- /dev/null
+++ b/assets/js/cb1e72f9.d9a03d3d.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunktinyorm_org=self.webpackChunktinyorm_org||[]).push([[258],{6349:(e,i,n)=>{n.r(i),n.d(i,{assets:()=>c,contentTitle:()=>l,default:()=>u,frontMatter:()=>t,metadata:()=>a,toc:()=>o});var r=n(4848),s=n(8453),d=n(8774);const t={sidebar_position:0,sidebar_label:"Getting Started",description:"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 time, 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.",keywords:["c++ orm","database","getting started","tinydrivers","sql drivers"]},l="TinyDrivers: Getting Started",a={id:"tinydrivers/getting-started",title:"TinyDrivers: Getting Started",description:"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 time, 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.",source:"@site/docs/tinydrivers/getting-started.mdx",sourceDirName:"tinydrivers",slug:"/tinydrivers/getting-started",permalink:"/tinydrivers/getting-started",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:0,frontMatter:{sidebar_position:0,sidebar_label:"Getting Started",description:"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 time, 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.",keywords:["c++ orm","database","getting started","tinydrivers","sql drivers"]},sidebar:"tinyormSidebar",previous:{title:"Serialization",permalink:"/tinyorm/serialization"},next:{title:"TinyORM",permalink:"/building/tinyorm"}},c={},o=[{value:"Introduction",id:"introduction",level:2},{value:"Features summary",id:"features-summary",level:4},{value:"Differences from QtSql",id:"differences-from-qtsql",level:2},{value:"Naming conventions",id:"naming-conventions",level:5},{value:"MySQL driver",id:"mysql-driver",level:5},{value:"Removed features",id:"removed-features",level:5},{value:"Missing features",id:"missing-features",level:5},{value:"Build system",id:"build-system",level:3},{value:"The Shared
library build",id:"the-shared-library-build",level:5},{value:"The Static
build",id:"the-static-build",level:5},{value:"The Loadable
SQL drivers build",id:"the-loadable-sql-drivers-build",level:5},{value:"CMake
/qmake
build options",id:"cmakeqmake-build-options",level:4},{value:"For CMake
",id:"for-cmake",level:5},{value:"For qmake
",id:"for-qmake",level:5},{value:"Performance",id:"performance",level:3},{value:"Internals",id:"internals",level:2},{value:"SqlDatabase",id:"sqldatabase",level:5},{value:"Namespaces",id:"namespaces",level:5},{value:"Documentation",id:"documentation",level:5}];function h(e){const i={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",header:"header",li:"li",p:"p",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(i.header,{children:(0,r.jsx)(i.h1,{id:"tinydrivers-getting-started",children:"TinyDrivers: Getting Started"})}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.a,{href:"#introduction",children:"Introduction"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#features-summary",children:"Features summary"})}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.a,{href:"#differences-from-qtsql",children:"Differences from QtSql"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#build-system",children:"Build system"})}),"\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#performance",children:"Performance"})}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(i.li,{children:(0,r.jsx)(i.a,{href:"#internals",children:"Internals"})}),"\n"]}),"\n",(0,r.jsx)(i.h2,{id:"introduction",children:"Introduction"}),"\n",(0,r.jsx)("div",{className:"api-stability alert alert--success",children:(0,r.jsxs)(i.p,{children:[(0,r.jsx)(d.A,{to:"/stability#stability-indexes",children:(0,r.jsx)(i.strong,{children:"Stability: 2"})})," - Stable"]})}),"\n",(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," library is an underlying SQL database layer for ",(0,r.jsx)(i.code,{children:"TinyORM"}),". It can be used instead of the ",(0,r.jsx)(i.code,{children:"QtSql"})," module, can be ",(0,r.jsx)("u",{children:(0,r.jsx)(i.strong,{children:"swapped"})})," at compile time, and has ",(0,r.jsx)(i.strong,{children:"1:1"})," API as the ",(0,r.jsx)(i.code,{children:"QtSql"})," module. \ud83d\ude2e Swapping is controlled by the ",(0,r.jsx)(i.code,{children:"qmake"})," and ",(0,r.jsx)(i.code,{children:"CMake"})," build system options."]}),"\n",(0,r.jsxs)(i.p,{children:["It was designed to drop the ",(0,r.jsx)(i.code,{children:"QtSql"})," dependency while maintaining backward compatibility and without the need for any code changes after the swap."]}),"\n",(0,r.jsx)(i.h4,{id:"features-summary",children:"Features summary"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:"both, normal and prepared statements are supported"}),"\n",(0,r.jsxs)(i.li,{children:["TLS/SSL connections using ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:(0,r.jsx)(i.code,{children:"MYSQL_OPT_SSL_MODE"})})," (verify_ca, verify_identity) \ud83d\udd25"]}),"\n",(0,r.jsxs)(i.li,{children:["setting many other MySQL connection options (see ",(0,r.jsx)(i.a,{href:"https://github.com/silverqx/TinyORM/blob/main/drivers/mysql/src/orm/drivers/mysql/mysqldriver_p.cpp",children:(0,r.jsx)(i.code,{children:"mysqldriver_p.cpp"})}),")"]}),"\n",(0,r.jsxs)(i.li,{children:["building and linking against the ",(0,r.jsx)(i.a,{href:"https://mariadb.com/kb/en/mariadb-connector-c/",children:(0,r.jsx)(i.code,{children:"MariaDB Connector/C"})})," \ud83d\udd7a"]}),"\n",(0,r.jsx)(i.li,{children:"transactions"}),"\n",(0,r.jsxs)(i.li,{children:["re-using the current ",(0,r.jsx)(i.code,{children:"SqlQuery"})," instance to re-execute the same or another SQL query"]}),"\n",(0,r.jsx)(i.li,{children:"detaching from the result set (related to freeing/releasing memory)"}),"\n",(0,r.jsxs)(i.li,{children:["query size, number of affected rows, last inserted ID, testing ",(0,r.jsx)(i.code,{children:"isNull()"}),", ..."]}),"\n",(0,r.jsxs)(i.li,{children:["all ",(0,r.jsx)(i.strong,{children:"3378 unit tests"})," passed \ud83d\ude2e"]}),"\n",(0,r.jsxs)(i.li,{children:["strictly using ",(0,r.jsx)(i.strong,{children:"smart pointers"})," (no ",(0,r.jsx)(i.code,{children:"new"})," keyword in the whole ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," code base \ud83d\ude0e)"]}),"\n",(0,r.jsx)(i.li,{children:"clear code \ud83e\udd14"}),"\n"]}),"\n",(0,r.jsx)(i.admonition,{type:"info",children:(0,r.jsxs)(i.p,{children:["Currently, only the ",(0,r.jsx)(i.code,{children:"MySQL"})," database driver is supported and finished. \ud83d\ude1e"]})}),"\n",(0,r.jsx)(i.admonition,{type:"tip",children:(0,r.jsxs)(i.p,{children:["All database drivers described in the ",(0,r.jsx)(i.a,{href:"/database/getting-started#introduction",children:"Database"})," documentation are supported when linking against the ",(0,r.jsx)(i.a,{href:"https://doc.qt.io/qt/qtsql-index.html",children:(0,r.jsx)(i.code,{children:"QtSql"})})," module."]})}),"\n",(0,r.jsx)(i.admonition,{type:"note",children:(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," library supports both build systems ",(0,r.jsx)(i.code,{children:"qmake"})," and also ",(0,r.jsx)(i.code,{children:"CMake"}),"."]})}),"\n",(0,r.jsx)(i.h2,{id:"differences-from-qtsql",children:"Differences from QtSql"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," doesn't return errors the the same way as the ",(0,r.jsx)(i.code,{children:"QtSql"})," module, which means return a ",(0,r.jsx)(i.code,{children:"bool"})," and if it's the result ",(0,r.jsx)(i.code,{children:"false"})," then obtain the ",(0,r.jsx)(i.code,{children:"SqlError"})," instance using the ",(0,r.jsx)(i.code,{children:"lastError()"})," method from ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," or ",(0,r.jsx)(i.code,{children:"SqlQuery"})," instances. Instead, it throws exceptions, and methods returning a ",(0,r.jsx)(i.code,{children:"bool"})," type to report an error state always return ",(0,r.jsx)(i.code,{children:"true"}),"."]}),"\n",(0,r.jsx)(i.h5,{id:"naming-conventions",children:"Naming conventions"}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.code,{children:"QtSql"})," ",(0,r.jsx)("small",{children:"module"})," -> ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," ",(0,r.jsx)("small",{children:"library"})]}),"\n",(0,r.jsxs)(i.li,{children:[(0,r.jsx)(i.code,{children:"QMYSQL"})," ",(0,r.jsx)("small",{children:"driver"})," -> ",(0,r.jsx)(i.code,{children:"TinyMySql"})," ",(0,r.jsx)("small",{children:"driver"})]}),"\n"]}),"\n",(0,r.jsx)(i.h5,{id:"mysql-driver",children:"MySQL driver"}),"\n",(0,r.jsxs)(i.p,{children:["The following describes the differences between ",(0,r.jsx)(i.code,{children:"QMYSQL"})," and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," drivers."]}),"\n",(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"QMYSQL"})," driver doesn't support setting ",(0,r.jsx)(i.code,{children:"MySQL"})," non-flag ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:"connection options"})," like ",(0,r.jsx)(i.code,{children:"MYSQL_OPT_RECONNECT"})," without the value, it needs to be defined with value like ",(0,r.jsx)(i.code,{children:"=1"})," or ",(0,r.jsx)(i.code,{children:"=TRUE"})," (case-sensitive), only real flag options like ",(0,r.jsx)(i.code,{children:"CLIENT_INTERACTIVE"})," can be set without the value and ",(0,r.jsx)(i.code,{children:"="})," character."]}),"\n",(0,r.jsxs)(i.p,{children:["On the other hand, the ",(0,r.jsx)(i.code,{children:"TinyMySql"})," driver allows setting non-flag ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-options.html",children:"connection options"})," options without the value and ",(0,r.jsx)(i.code,{children:"="})," character, which are considered enabled (ON or TRUE)."]}),"\n",(0,r.jsx)(i.h5,{id:"removed-features",children:"Removed features"}),"\n",(0,r.jsxs)(i.p,{children:["Simulation of prepared statements while calling ",(0,r.jsx)(i.code,{children:"SqlQuery::exec(QString)"}),", this functionality is useless because you can call regular prepared statements using ",(0,r.jsx)(i.code,{children:"SqlQuery::prepare(QString)"})," and then ",(0,r.jsx)(i.code,{children:"SqlQuery::exec()"}),"."]}),"\n",(0,r.jsx)(i.h5,{id:"missing-features",children:"Missing features"}),"\n",(0,r.jsxs)(i.p,{children:["Fetching multiple result sets using ",(0,r.jsx)(i.code,{children:"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."]}),"\n",(0,r.jsx)(i.h3,{id:"build-system",children:"Build system"}),"\n",(0,r.jsxs)(i.p,{children:["Another difference is that you can build the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," and its SQL drivers (",(0,r.jsx)(i.code,{children:"TinyMySql"}),") in 3 different ways; ",(0,r.jsx)(i.code,{children:"Shared"}),", ",(0,r.jsx)(i.code,{children:"Static"}),", and as a ",(0,r.jsx)(i.code,{children:"Loadable"})," library at runtime using ",(0,r.jsx)(i.code,{children:"LoadLibrary()"})," on Windows or ",(0,r.jsx)(i.code,{children:"dlopen()"})," on Linux."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-shared-library-build",children:["The ",(0,r.jsx)(i.code,{children:"Shared"})," library build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds two shared libraries, the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library that contains the core/common code and the ",(0,r.jsx)(i.code,{children:"TinyMySql"})," shared library that contains ",(0,r.jsx)(i.code,{children:"MySQL"})," implementation. The ",(0,r.jsx)(i.code,{children:"TinyOrm"})," links only against the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," is a private implementation."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-static-build",children:["The ",(0,r.jsx)(i.code,{children:"Static"})," build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds one ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," static archive that contains the core/common code and SQL drivers (",(0,r.jsx)(i.code,{children:"TinyMySql"}),"). This static library is linked or merged into the ",(0,r.jsx)(i.code,{children:"TinyOrm"})," shared or static library (both variants are supported)."]}),"\n",(0,r.jsxs)(i.h5,{id:"the-loadable-sql-drivers-build",children:["The ",(0,r.jsx)(i.code,{children:"Loadable"})," SQL drivers build"]}),"\n",(0,r.jsxs)(i.p,{children:["It builds two shared libraries, the ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," shared library that contains the core/common code and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," shared library (module) that contains ",(0,r.jsx)(i.code,{children:"MySQL"})," implementation that is loaded at runtime using ",(0,r.jsx)(i.code,{children:"LoadLibrary()"})," on Windows or ",(0,r.jsx)(i.code,{children:"dlopen()"})," on Linux. The SQL driver library loader throws an exception if it cannot find this library at runtime."]}),"\n",(0,r.jsx)(i.admonition,{type:"info",children:(0,r.jsxs)(i.p,{children:["The ",(0,r.jsx)(i.code,{children:"TinyMySql"})," links directly against the ",(0,r.jsx)(i.code,{children:"MySQL C connector"})," (",(0,r.jsx)(i.code,{children:"libmysql"})," or ",(0,r.jsx)(i.code,{children:"mysqlclient"})," library)."]})}),"\n",(0,r.jsxs)(i.h4,{id:"cmakeqmake-build-options",children:[(0,r.jsx)(i.code,{children:"CMake"}),"/",(0,r.jsx)(i.code,{children:"qmake"})," build options"]}),"\n",(0,r.jsxs)(i.h5,{id:"for-cmake",children:["For ",(0,r.jsx)(i.code,{children:"CMake"})]}),"\n",(0,r.jsxs)(i.p,{children:["See ",(0,r.jsx)(i.a,{href:"/building/tinyorm#cmake-build-options",children:"CMake build options"}),", related ",(0,r.jsx)(i.code,{children:"CMake"})," build options are:",(0,r.jsx)("br",{}),(0,r.jsx)(i.a,{href:"/building/tinyorm#BUILD_DRIVERS",children:(0,r.jsx)(i.code,{children:"BUILD_DRIVERS"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#BUILD_MYSQL_DRIVER",children:(0,r.jsx)(i.code,{children:"BUILD_MYSQL_DRIVER"})}),", and ",(0,r.jsx)(i.a,{href:"/building/tinyorm#DRIVERS_TYPE",children:(0,r.jsx)(i.code,{children:"DRIVERS_TYPE"})})]}),"\n",(0,r.jsxs)(i.p,{children:["To control shared and static build use ",(0,r.jsx)(i.a,{href:"https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html",children:(0,r.jsx)(i.code,{children:"BUILD_SHARED_LIBS"})})," ",(0,r.jsx)(i.code,{children:"CMake"})," configuration option."]}),"\n",(0,r.jsxs)(i.h5,{id:"for-qmake",children:["For ",(0,r.jsx)(i.code,{children:"qmake"})]}),"\n",(0,r.jsxs)(i.p,{children:["See ",(0,r.jsx)(i.a,{href:"/building/tinyorm#qmake-build-options",children:"qmake build options"}),", related ",(0,r.jsx)(i.code,{children:"qmake"})," configuration options are:",(0,r.jsx)("br",{}),(0,r.jsx)(i.a,{href:"/building/tinyorm#build_loadable_drivers",children:(0,r.jsx)(i.code,{children:"build_loadable_drivers"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_mysql_driver",children:(0,r.jsx)(i.code,{children:"build_mysql_driver"})}),", ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_shared_drivers",children:(0,r.jsx)(i.code,{children:"build_shared_drivers"})}),", and ",(0,r.jsx)(i.a,{href:"/building/tinyorm#build_static_drivers",children:(0,r.jsx)(i.code,{children:"build_static_drivers"})})]}),"\n",(0,r.jsxs)(i.p,{children:["To control shared and static build use ",(0,r.jsx)(i.a,{href:"/building/tinyorm#qmake-static",children:(0,r.jsx)(i.code,{children:"static"})})," ",(0,r.jsx)(i.code,{children:"qmake"})," ",(0,r.jsx)(i.a,{href:"https://doc.qt.io/qt/qmake-variable-reference.html#config",children:"configuration option"}),"."]}),"\n",(0,r.jsx)(i.h3,{id:"performance",children:"Performance"}),"\n",(0,r.jsxs)(i.p,{children:["Performance is several milliseconds faster compared to ",(0,r.jsx)(i.code,{children:"QtSql"})," with the ",(0,r.jsx)(i.code,{children:"QMYSQL"})," driver. It was tuned using the ",(0,r.jsx)(i.code,{children:"KCacheGrind"})," to be so. It's ~40ms faster on ",(0,r.jsx)(i.a,{href:"https://github.com/silverqx/TinyOrmPlayground",children:(0,r.jsx)(i.code,{children:"TinyOrmPlayground"})})," project with ",(0,r.jsx)(i.strong,{children:"620"})," database queries compiled using ",(0,r.jsx)(i.code,{children:"GCC v13.2.1"})," Debug build on Linux. Similar results can be expected on other platforms but it's not guaranteed."]}),"\n",(0,r.jsxs)(i.p,{children:["This means performance is very similar to ",(0,r.jsx)(i.code,{children:"QtSql"}),". There is not much to speed up because ",(0,r.jsx)(i.code,{children:"TinyDrivers"})," code is swift and 90% of the time is spent inside the ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/",children:(0,r.jsx)(i.code,{children:"MySQL C API"})})," because we always have to wait for the database server, especially when creating database connections using eg. ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-real-connect.html",children:(0,r.jsx)(i.code,{children:"mysql_real_connect()"})})," (this function is king among the slowest functions \ud83d\ude0e, which is understandable of course)."]}),"\n",(0,r.jsx)(i.h2,{id:"internals",children:"Internals"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," internal design can be divided into 3 different layers:"]}),"\n",(0,r.jsxs)(i.ul,{children:["\n",(0,r.jsx)(i.li,{children:"Driver layer"}),"\n",(0,r.jsx)(i.li,{children:"SQL API layer"}),"\n",(0,r.jsx)(i.li,{children:"Public API layer"}),"\n"]}),"\n",(0,r.jsxs)(i.p,{children:["The Driver layer is eg. ",(0,r.jsx)(i.code,{children:"TinyMySql"})," library which is responsible for communicating with the underlying database driver (eg. ",(0,r.jsx)(i.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/",children:(0,r.jsx)(i.code,{children:"MySQL C API"})}),")."]}),"\n",(0,r.jsx)(i.p,{children:"The SQL API layer is a semi-layer that glues everything up and sits between the Public interface API and the Driver layer."}),"\n",(0,r.jsxs)(i.p,{children:["The Public interface API layer are the end classes like ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," and ",(0,r.jsx)(i.code,{children:"SqlQuery"})," which are exposed to the end user."]}),"\n",(0,r.jsx)(i.h5,{id:"sqldatabase",children:"SqlDatabase"}),"\n",(0,r.jsxs)(i.p,{children:["One more thing worth mentioning is the ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," API. It's one class that has two responsibilities! All static methods act as the database connection manager and an instance of the ",(0,r.jsx)(i.code,{children:"SqlDatabase"})," represents a physical database connection. It's not a good design because it breaks the ",(0,r.jsx)(i.a,{href:"https://en.wikipedia.org/wiki/Single_responsibility_principle",children:"Single Responsibility principle"}),", but it's what it is."]}),"\n",(0,r.jsx)(i.h5,{id:"namespaces",children:"Namespaces"}),"\n",(0,r.jsxs)(i.p,{children:[(0,r.jsx)(i.code,{children:"TinyDrivers"})," classes are defined in the ",(0,r.jsx)(i.code,{children:"Orm::Drivers"})," namespace and ",(0,r.jsx)(i.code,{children:"TinyMySql"})," classes in the ",(0,r.jsx)(i.code,{children:"Orm::Drivers::MySql"})," namespace."]}),"\n",(0,r.jsx)(i.h5,{id:"documentation",children:"Documentation"}),"\n",(0,r.jsxs)(i.p,{children:["For all other APIs you can follow the ",(0,r.jsx)(i.a,{href:"https://doc.qt.io/qt/qtsql-index.html",children:"QtSql documentation"})," as the API is 1:1. The exception is of course the build system, ",(0,r.jsx)(i.code,{children:"TinyOrm"})," has its own build system that doesn't follow the ",(0,r.jsx)(i.code,{children:"QtSql"})," module."]})]})}function u(e={}){const{wrapper:i}={...(0,s.R)(),...e.components};return i?(0,r.jsx)(i,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453:(e,i,n)=>{n.d(i,{R:()=>t,x:()=>l});var r=n(6540);const s={},d=r.createContext(s);function t(e){const i=r.useContext(d);return r.useMemo((function(){return"function"==typeof e?e(i):{...i,...e}}),[i,e])}function l(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:t(e.components),r.createElement(d.Provider,{value:i},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/e3ac21cb.ba171561.js b/assets/js/e3ac21cb.ba171561.js
deleted file mode 100644
index 1bf046f91..000000000
--- a/assets/js/e3ac21cb.ba171561.js
+++ /dev/null
@@ -1 +0,0 @@
-"use strict";(self.webpackChunktinyorm_org=self.webpackChunktinyorm_org||[]).push([[467],{348:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>p,frontMatter:()=>d,metadata:()=>o,toc:()=>c});var r=t(4848),i=t(8453),s=t(8774);const d={sidebar_position:1,sidebar_label:"\ud83d\udd27 Dependencies",hide_table_of_contents:!0,description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",keywords:["c++ orm","dependencies","tinyorm"]},a="Dependencies",o={id:"dependencies",title:"Dependencies",description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",source:"@site/docs/dependencies.mdx",sourceDirName:".",slug:"/dependencies",permalink:"/dependencies",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1,sidebar_label:"\ud83d\udd27 Dependencies",hide_table_of_contents:!0,description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",keywords:["c++ orm","dependencies","tinyorm"]},sidebar:"tinyormSidebar",previous:{title:"\ud83d\udd25 Prologue",permalink:"/"},next:{title:"\ud83d\ude80 Supported Compilers",permalink:"/supported-compilers"}},l={},c=[{value:"Required",id:"required",level:5},{value:"Optional",id:"optional",level:5},{value:"Install dependencies",id:"install-dependencies",level:3}];function h(e){const n={a:"a",admonition:"admonition",code:"code",del:"del",h1:"h1",h3:"h3",h5:"h5",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"dependencies",children:"Dependencies"})}),"\n",(0,r.jsxs)(n.p,{children:["The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18, so may be assumed it will work on future releases of these compilers. Minimum required ISO C++ standard is C++20.\nThe Qt framework version used during development was ",(0,r.jsx)(n.del,{children:"5.15.2"})," and >=6.2."]}),"\n",(0,r.jsx)(n.h5,{id:"required",children:"Required"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"minimum ISO C++ standard is C++20"}),"\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://www.qt.io/download-qt-installer",children:"Qt Framework 6.2"})," - ",(0,r.jsx)(n.a,{href:"https://doc.qt.io/qt-6/qtcore-module.html",children:(0,r.jsx)(n.code,{children:"QtCore"})})," and ",(0,r.jsx)(n.a,{href:"https://doc.qt.io/qt-6/qtsql-index.html",children:(0,r.jsx)(n.code,{children:"QtSql"})})," modules"]}),"\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://github.com/ericniebler/range-v3",children:"range-v3 0.11.0"})]}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"https://github.com/p-ranav/tabulate",children:"tabulate"})}),"\n"]}),"\n",(0,r.jsx)(n.admonition,{type:"danger",children:(0,r.jsxs)(n.p,{children:["Support for ",(0,r.jsx)(n.strong,{children:"Qt v5.15"})," was removed since ",(0,r.jsx)(n.strong,{children:"TinyORM v0.38.0"}),". \ud83c\udf89\ud83d\ude4c"]})}),"\n",(0,r.jsx)(n.admonition,{type:"warning",children:(0,r.jsxs)(n.p,{children:["Be aware that the standard support for the last release of the ",(0,r.jsx)(n.strong,{children:"Qt v5"})," series ended on ",(0,r.jsx)(n.strong,{children:"26. May 2023"}),". [",(0,r.jsx)(n.a,{href:"https://endoflife.date/qt",children:"1"}),"][",(0,r.jsx)(n.a,{href:"https://www.qt.io/blog/qt-5.15-support-ends",children:"2"}),"]"]})}),"\n",(0,r.jsx)(n.h5,{id:"optional",children:"Optional"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/downloads/c-api/",children:"MySQL Connector/C 8"})," - used only for the ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-ping.html",children:(0,r.jsx)(n.code,{children:"mysql_ping"})})," function and provided by ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/downloads/mysql/",children:"MySQL 8 Server"})]}),"\n"]}),"\n",(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"TinyORM"})," will support ",(0,r.jsx)(n.code,{children:"Qt"})," versions that aren't ",(0,r.jsx)(n.a,{href:"https://endoflife.date/qt",children:"end-of-life"}),"."]})}),"\n",(0,r.jsx)(n.admonition,{type:"note",children:(0,r.jsxs)(n.p,{children:["You can view the supported database servers in the ",(0,r.jsx)(n.a,{href:"/database/getting-started#introduction",children:"Database - Getting Started"})," section."]})}),"\n",(0,r.jsx)(n.h3,{id:"install-dependencies",children:"Install dependencies"}),"\n",(0,r.jsxs)(n.p,{children:["On ",(0,r.jsx)(n.code,{children:"Linux"}),", you can install dependencies with the package manager."]}),"\n",(0,r.jsxs)("small",{children:[(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='MySQL C library'",children:"Arch - pacman -S mariadb-libs\nGentoo - emerge dev-db/mysql (package.use: -server -perl)\nUbuntu - apt install libmysqlclient-dev\n"})}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='range-v3 library (header only)'",children:"Arch - pacman -S range-v3\nGentoo - emerge dev-cpp/range-v3\nUbuntu - apt install librange-v3-dev\n"})}),(0,r.jsx)(s.A,{id:"linux-installation-ccache"}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='ccache'",children:"Arch - pacman -S ccache\nGentoo - emerge dev-util/ccache\nUbuntu - apt install ccache\n"})})]})]})}function p(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>d,x:()=>a});var r=t(6540);const i={},s=r.createContext(i);function d(e){const n=r.useContext(s);return r.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),r.createElement(s.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/e3ac21cb.fc49fa7b.js b/assets/js/e3ac21cb.fc49fa7b.js
new file mode 100644
index 000000000..c4d8ee703
--- /dev/null
+++ b/assets/js/e3ac21cb.fc49fa7b.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunktinyorm_org=self.webpackChunktinyorm_org||[]).push([[467],{348:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>p,frontMatter:()=>d,metadata:()=>o,toc:()=>c});var r=t(4848),i=t(8453),s=t(8774);const d={sidebar_position:1,sidebar_label:"\ud83d\udd27 Dependencies",hide_table_of_contents:!0,description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",keywords:["c++ orm","dependencies","tinyorm"]},a="Dependencies",o={id:"dependencies",title:"Dependencies",description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",source:"@site/docs/dependencies.mdx",sourceDirName:".",slug:"/dependencies",permalink:"/dependencies",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1,sidebar_label:"\ud83d\udd27 Dependencies",hide_table_of_contents:!0,description:"Library dependencies are MySQL Connector/C 8, range-v3 >=0.11.0, tabulate and the Qt framework version used during development was 5.15.2 and >=6.2. The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18.",keywords:["c++ orm","dependencies","tinyorm"]},sidebar:"tinyormSidebar",previous:{title:"\ud83d\udd25 Prologue",permalink:"/"},next:{title:"\ud83d\ude80 Supported Compilers",permalink:"/supported-compilers"}},l={},c=[{value:"Required",id:"required",level:5},{value:"Optional",id:"optional",level:5},{value:"Install dependencies",id:"install-dependencies",level:3}];function h(e){const n={a:"a",admonition:"admonition",code:"code",del:"del",h1:"h1",h3:"h3",h5:"h5",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"dependencies",children:"Dependencies"})}),"\n",(0,r.jsxs)(n.p,{children:["The code was developed on MSVC 16.9-16.11, MSVC 17.2-17.9, GCC 11.2-14.2, and Clang 11-18, so may be assumed it will work on future releases of these compilers. Minimum required ISO C++ standard is C++20.\nThe Qt framework version used during development was ",(0,r.jsx)(n.del,{children:"5.15.2"})," and >=6.2."]}),"\n",(0,r.jsx)(n.h5,{id:"required",children:"Required"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"minimum ISO C++ standard is C++20"}),"\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://www.qt.io/download-qt-installer",children:"Qt Framework 6.2"})," - ",(0,r.jsx)(n.a,{href:"https://doc.qt.io/qt/qtcore-module.html",children:(0,r.jsx)(n.code,{children:"QtCore"})})," and ",(0,r.jsx)(n.a,{href:"https://doc.qt.io/qt/qtsql-index.html",children:(0,r.jsx)(n.code,{children:"QtSql"})})," modules"]}),"\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://github.com/ericniebler/range-v3",children:"range-v3 0.11.0"})]}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"https://github.com/p-ranav/tabulate",children:"tabulate"})}),"\n"]}),"\n",(0,r.jsx)(n.admonition,{type:"danger",children:(0,r.jsxs)(n.p,{children:["Support for ",(0,r.jsx)(n.strong,{children:"Qt v5.15"})," was removed since ",(0,r.jsx)(n.strong,{children:"TinyORM v0.38.0"}),". \ud83c\udf89\ud83d\ude4c"]})}),"\n",(0,r.jsx)(n.admonition,{type:"warning",children:(0,r.jsxs)(n.p,{children:["Be aware that the standard support for the last release of the ",(0,r.jsx)(n.strong,{children:"Qt v5"})," series ended on ",(0,r.jsx)(n.strong,{children:"26. May 2023"}),". [",(0,r.jsx)(n.a,{href:"https://endoflife.date/qt",children:"1"}),"][",(0,r.jsx)(n.a,{href:"https://www.qt.io/blog/qt-5.15-support-ends",children:"2"}),"]"]})}),"\n",(0,r.jsx)(n.h5,{id:"optional",children:"Optional"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[">= ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/downloads/c-api/",children:"MySQL Connector/C 8"})," - used only for the ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/doc/c-api/9.0/en/mysql-ping.html",children:(0,r.jsx)(n.code,{children:"mysql_ping"})})," function and provided by ",(0,r.jsx)(n.a,{href:"https://dev.mysql.com/downloads/mysql/",children:"MySQL 8 Server"})]}),"\n"]}),"\n",(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"TinyORM"})," will support ",(0,r.jsx)(n.code,{children:"Qt"})," versions that aren't ",(0,r.jsx)(n.a,{href:"https://endoflife.date/qt",children:"end-of-life"}),"."]})}),"\n",(0,r.jsx)(n.admonition,{type:"note",children:(0,r.jsxs)(n.p,{children:["You can view the supported database servers in the ",(0,r.jsx)(n.a,{href:"/database/getting-started#introduction",children:"Database - Getting Started"})," section."]})}),"\n",(0,r.jsx)(n.h3,{id:"install-dependencies",children:"Install dependencies"}),"\n",(0,r.jsxs)(n.p,{children:["On ",(0,r.jsx)(n.code,{children:"Linux"}),", you can install dependencies with the package manager."]}),"\n",(0,r.jsxs)("small",{children:[(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='MySQL C library'",children:"Arch - pacman -S mariadb-libs\nGentoo - emerge dev-db/mysql (package.use: -server -perl)\nUbuntu - apt install libmysqlclient-dev\n"})}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='range-v3 library (header only)'",children:"Arch - pacman -S range-v3\nGentoo - emerge dev-cpp/range-v3\nUbuntu - apt install librange-v3-dev\n"})}),(0,r.jsx)(s.A,{id:"linux-installation-ccache"}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:"title='ccache'",children:"Arch - pacman -S ccache\nGentoo - emerge dev-util/ccache\nUbuntu - apt install ccache\n"})})]})]})}function p(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>d,x:()=>a});var r=t(6540);const i={},s=r.createContext(i);function d(e){const n=r.useContext(s);return r.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),r.createElement(s.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/runtime~main.57ef49b5.js b/assets/js/runtime~main.04a383d2.js
similarity index 55%
rename from assets/js/runtime~main.57ef49b5.js
rename to assets/js/runtime~main.04a383d2.js
index fc7eb2fa3..f03f2501b 100644
--- a/assets/js/runtime~main.57ef49b5.js
+++ b/assets/js/runtime~main.04a383d2.js
@@ -1 +1 @@
-(()=>{"use strict";var e,a,t,r,o,n={},f={};function c(e){var a=f[e];if(void 0!==a)return a.exports;var t=f[e]={exports:{}};return n[e].call(t.exports,t,t.exports,c),t.exports}c.m=n,e=[],c.O=(a,t,r,o)=>{if(!t){var n=1/0;for(i=0;iQtCore
and QtSql
modulesQtCore
and QtSql
modulesCurrently, only the MySQL
database driver is supported and finished. 😞
TinyDrivers
library supports both build systems qmake
and also CMake
.
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
.