Lightweight 0.20250904.0
Loading...
Searching...
No Matches
SqlConnection.hpp
1// SPDX-License-Identifier: Apache-2.0
2
3#pragma once
4
5#if defined(_WIN32) || defined(_WIN64)
6 #include <Windows.h>
7#endif
8
9#include "Api.hpp"
10#include "SqlConnectInfo.hpp"
11#include "SqlError.hpp"
12#include "SqlLogger.hpp"
13#include "SqlServerType.hpp"
14
15#include <atomic>
16#include <chrono>
17#include <expected>
18#include <format>
19#include <functional>
20#include <memory>
21#include <optional>
22#include <string>
23#include <string_view>
24#include <system_error>
25
26#include <sql.h>
27#include <sqlext.h>
28#include <sqlspi.h>
29#include <sqltypes.h>
30
31namespace Lightweight
32{
33
34class SqlQueryBuilder;
35class SqlMigrationQueryBuilder;
36class SqlQueryFormatter;
37
38/// @brief Represents a connection to a SQL database.
39class SqlConnection final
40{
41 public:
42 /// @brief Constructs a new SQL connection to the default connection.
43 ///
44 /// The default connection is set via SetDefaultConnectInfo.
45 /// In case the default connection is not set, the connection will fail.
46 /// And in case the connection fails, the last error will be set.
47 LIGHTWEIGHT_API SqlConnection();
48
49 /// @brief Constructs a new SQL connection to the given connect informaton.
50 ///
51 /// @param connectInfo The connection information to use. If not provided,
52 /// no connection will be established.
53 LIGHTWEIGHT_API explicit SqlConnection(std::optional<SqlConnectionString> connectInfo);
54
55 LIGHTWEIGHT_API SqlConnection(SqlConnection&& /*other*/) noexcept;
56 LIGHTWEIGHT_API SqlConnection& operator=(SqlConnection&& /*other*/) noexcept;
57 SqlConnection(SqlConnection const& /*other*/) = delete;
58 SqlConnection& operator=(SqlConnection const& /*other*/) = delete;
59
60 /// Destructs this SQL connection object,
61 LIGHTWEIGHT_API ~SqlConnection() noexcept;
62
63 /// Retrieves the default connection information.
64 LIGHTWEIGHT_API static SqlConnectionString const& DefaultConnectionString() noexcept;
65
66 /// Sets the default connection information.
67 ///
68 /// @param connectionString The connection information to use.
69 LIGHTWEIGHT_API static void SetDefaultConnectionString(SqlConnectionString const& connectionString) noexcept;
70
71 /// Sets the default connection information as SqlConnectionDataSource.
72 LIGHTWEIGHT_API static void SetDefaultDataSource(SqlConnectionDataSource const& dataSource) noexcept;
73
74 /// Sets a callback to be called after each connection being established.
75 LIGHTWEIGHT_API static void SetPostConnectedHook(std::function<void(SqlConnection&)> hook);
76
77 /// Resets the post connected hook.
78 LIGHTWEIGHT_API static void ResetPostConnectedHook();
79
80 /// @brief Retrieves the connection ID.
81 ///
82 /// This is a unique identifier for the connection, which is useful for debugging purposes.
83 /// Note, this ID will not change if the connection is moved nor when it is reused via the connection pool.
84 [[nodiscard]] uint64_t ConnectionId() const noexcept
85 {
86 return m_connectionId;
87 }
88
89 /// Closes the connection (attempting to put it back into the connect[[ion pool).
90 LIGHTWEIGHT_API void Close() noexcept;
91
92 /// Connects to the given database with the given username and password.
93 ///
94 /// @retval true if the connection was successful.
95 /// @retval false if the connection failed. Use LastError() to retrieve the error information.
96 LIGHTWEIGHT_API bool Connect(SqlConnectionDataSource const& info) noexcept;
97
98 /// Connects to the given database with the given username and password.
99 ///
100 /// @retval true if the connection was successful.
101 /// @retval false if the connection failed. Use LastError() to retrieve the error information.
102 LIGHTWEIGHT_API bool Connect(SqlConnectionString sqlConnectionString) noexcept;
103
104 /// Retrieves the last error information with respect to this SQL connection handle.
105 [[nodiscard]] LIGHTWEIGHT_API SqlErrorInfo LastError() const;
106
107 /// Retrieves the name of the database in use.
108 [[nodiscard]] LIGHTWEIGHT_API std::string DatabaseName() const;
109
110 /// Retrieves the name of the user.
111 [[nodiscard]] LIGHTWEIGHT_API std::string UserName() const;
112
113 /// Retrieves the name of the server.
114 [[nodiscard]] LIGHTWEIGHT_API std::string ServerName() const;
115
116 /// Retrieves the reported server version.
117 [[nodiscard]] LIGHTWEIGHT_API std::string ServerVersion() const;
118
119 /// Retrieves the type of the server.
120 [[nodiscard]] SqlServerType ServerType() const noexcept;
121
122 /// Retrieves the name of the driver used for this connection.
123 [[nodiscard]] std::string const& DriverName() const noexcept;
124
125 /// Retrieves a query formatter suitable for the SQL server being connected.
126 [[nodiscard]] SqlQueryFormatter const& QueryFormatter() const noexcept;
127
128 /// Creates a new query builder for the given table, compatible with the current connection.
129 ///
130 /// @param table The table to query.
131 /// If not provided, the query will be a generic query builder.
132 [[nodiscard]] LIGHTWEIGHT_API SqlQueryBuilder Query(std::string_view const& table = {}) const;
133
134 /// Creates a new query builder for the given table with an alias, compatible with the current connection.
135 ///
136 /// @param table The table to query.
137 /// @param tableAlias The alias to use for the table.
138 [[nodiscard]] LIGHTWEIGHT_API SqlQueryBuilder QueryAs(std::string_view const& table,
139 std::string_view const& tableAlias) const;
140
141 /// Creates a new migration query builder, compatible the current connection.
142 [[nodiscard]] LIGHTWEIGHT_API SqlMigrationQueryBuilder Migration() const;
143
144 /// Tests if a transaction is active.
145 [[nodiscard]] LIGHTWEIGHT_API bool TransactionActive() const noexcept;
146
147 /// Tests if transactions are allowed.
148 [[nodiscard]] LIGHTWEIGHT_API bool TransactionsAllowed() const noexcept;
149
150 /// Tests if the connection is still active.
151 [[nodiscard]] LIGHTWEIGHT_API bool IsAlive() const noexcept;
152
153 /// Retrieves the connection information.
154 [[nodiscard]] LIGHTWEIGHT_API SqlConnectionString const& ConnectionString() const noexcept;
155
156 /// Retrieves the native handle.
157 [[nodiscard]] SQLHDBC NativeHandle() const noexcept
158 {
159 return m_hDbc;
160 }
161
162 /// Retrieves the last time the connection was used.
163 [[nodiscard]] LIGHTWEIGHT_API std::chrono::steady_clock::time_point LastUsed() const noexcept;
164
165 /// Sets the last time the connection was used.
166 LIGHTWEIGHT_API void SetLastUsed(std::chrono::steady_clock::time_point lastUsed) noexcept;
167
168 /// Checks the result of an SQL operation, and throws an exception if it is not successful.
169 LIGHTWEIGHT_API void RequireSuccess(SQLRETURN sqlResult,
170 std::source_location sourceLocation = std::source_location::current()) const;
171
172 private:
173 void PostConnect();
174
175 // Private data members
176 SQLHENV m_hEnv {};
177 SQLHDBC m_hDbc {};
178 uint64_t m_connectionId;
179 SqlServerType m_serverType = SqlServerType::UNKNOWN;
180 SqlQueryFormatter const* m_queryFormatter {};
181 std::string m_driverName;
182
183 struct Data;
184 Data* m_data {};
185};
186
187inline SqlServerType SqlConnection::ServerType() const noexcept
188{
189 return m_serverType;
190}
191
192inline std::string const& SqlConnection::DriverName() const noexcept
193{
194 return m_driverName;
195}
196
198{
199 return *m_queryFormatter;
200}
201
202} // namespace Lightweight
Represents a connection to a SQL database.
LIGHTWEIGHT_API void RequireSuccess(SQLRETURN sqlResult, std::source_location sourceLocation=std::source_location::current()) const
Checks the result of an SQL operation, and throws an exception if it is not successful.
static LIGHTWEIGHT_API void ResetPostConnectedHook()
Resets the post connected hook.
LIGHTWEIGHT_API std::string ServerName() const
Retrieves the name of the server.
SqlServerType ServerType() const noexcept
Retrieves the type of the server.
LIGHTWEIGHT_API SqlMigrationQueryBuilder Migration() const
Creates a new migration query builder, compatible the current connection.
LIGHTWEIGHT_API bool TransactionActive() const noexcept
Tests if a transaction is active.
LIGHTWEIGHT_API bool IsAlive() const noexcept
Tests if the connection is still active.
LIGHTWEIGHT_API SqlQueryBuilder Query(std::string_view const &table={}) const
LIGHTWEIGHT_API SqlQueryBuilder QueryAs(std::string_view const &table, std::string_view const &tableAlias) const
LIGHTWEIGHT_API SqlConnection(std::optional< SqlConnectionString > connectInfo)
Constructs a new SQL connection to the given connect informaton.
LIGHTWEIGHT_API bool TransactionsAllowed() const noexcept
Tests if transactions are allowed.
uint64_t ConnectionId() const noexcept
Retrieves the connection ID.
SqlQueryFormatter const & QueryFormatter() const noexcept
Retrieves a query formatter suitable for the SQL server being connected.
LIGHTWEIGHT_API void SetLastUsed(std::chrono::steady_clock::time_point lastUsed) noexcept
Sets the last time the connection was used.
LIGHTWEIGHT_API void Close() noexcept
Closes the connection (attempting to put it back into the connect[[ion pool).
static LIGHTWEIGHT_API void SetDefaultDataSource(SqlConnectionDataSource const &dataSource) noexcept
Sets the default connection information as SqlConnectionDataSource.
static LIGHTWEIGHT_API SqlConnectionString const & DefaultConnectionString() noexcept
Retrieves the default connection information.
LIGHTWEIGHT_API SqlErrorInfo LastError() const
Retrieves the last error information with respect to this SQL connection handle.
LIGHTWEIGHT_API SqlConnection()
Constructs a new SQL connection to the default connection.
static LIGHTWEIGHT_API void SetDefaultConnectionString(SqlConnectionString const &connectionString) noexcept
LIGHTWEIGHT_API std::string DatabaseName() const
Retrieves the name of the database in use.
LIGHTWEIGHT_API std::chrono::steady_clock::time_point LastUsed() const noexcept
Retrieves the last time the connection was used.
SQLHDBC NativeHandle() const noexcept
Retrieves the native handle.
LIGHTWEIGHT_API std::string ServerVersion() const
Retrieves the reported server version.
LIGHTWEIGHT_API SqlConnectionString const & ConnectionString() const noexcept
Retrieves the connection information.
std::string const & DriverName() const noexcept
Retrieves the name of the driver used for this connection.
LIGHTWEIGHT_API std::string UserName() const
Retrieves the name of the user.
static LIGHTWEIGHT_API void SetPostConnectedHook(std::function< void(SqlConnection &)> hook)
Sets a callback to be called after each connection being established.
LIGHTWEIGHT_API bool Connect(SqlConnectionDataSource const &info) noexcept
Query builder for building SQL migration queries.
Definition Migrate.hpp:185
API Entry point for building SQL queries.
Definition SqlQuery.hpp:29
API to format SQL queries for different SQL dialects.
Represents a connection data source as a DSN, username, password, and timeout.
Represents an ODBC connection string.
Represents an ODBC SQL error.
Definition SqlError.hpp:33