The Battle for Wesnoth  1.15.3+dev
connection.hpp
Go to the documentation of this file.
1 //
2 // M A R I A D B + +
3 //
4 // Copyright Sylvain Rochette Langlois 2013,
5 // Frantisek Boranek 2015,
6 // The ViaDuck Project 2016 - 2018.
7 // Distributed under the Boost Software License, Version 1.0.
8 // (See accompanying file LICENSE or copy at
9 // http://www.boost.org/LICENSE_1_0.txt)
10 
11 #ifndef _MARIADB_CONNECTION_HPP_
12 #define _MARIADB_CONNECTION_HPP_
13 
14 #include <string>
15 #include <mariadb++/account.hpp>
16 #include <mariadb++/statement.hpp>
18 #include <mariadb++/save_point.hpp>
19 #include <mariadb++/result_set.hpp>
20 
21 #include <mysql.h>
22 
23 namespace mariadb {
24 /**
25  * Wraps a Database connection.
26  */
27 class connection : public last_error {
28  friend class result_set;
29  friend class statement;
30  friend class transaction;
31  friend class save_point;
32 
33  public:
34  /**
35  * Destroys connection and automatically disconnects
36  */
37  virtual ~connection();
38 
39  /**
40  * Actually connects to the database using given account, sets SSL and additional options as
41  * well as auto commit
42  *
43  * @return True on success
44  */
45  bool connect();
46 
47  /**
48  * Disconnects from the database
49  */
50  void disconnect();
51 
52  /**
53  * Indicates whether the connection is active. Also detects stale connections
54  *
55  * @return True on active connection
56  */
57  bool connected() const;
58 
59  /**
60  * Gets the account associated with this connection
61  *
62  * @return Reference to the account
63  */
64  account_ref account() const;
65 
66  /**
67  * Gets the schema (database name)
68  *
69  * @return String containing the schema
70  */
71  const std::string& schema() const;
72 
73  /**
74  * Sets the schema (database name).
75  * The connection needs to be already established
76  *
77  * @param schema The new schema name
78  * @return True on success
79  */
80  bool set_schema(const std::string& schema);
81 
82  /**
83  * Gets the charset associated with this connection
84  *
85  * @return String containg the charset (see documentation of MariaDB for possible values)
86  */
87  const std::string& charset() const;
88 
89  /**
90  * Sets the charset.
91  * The connection needs to be already established
92  *
93  * @param value The new charset
94  * @return True on success
95  */
96  bool set_charset(const std::string& value);
97 
98  /**
99  * Execute a query without interest in a result.
100  * The connection needs to be established.
101  *
102  * @param query SQL query to execute
103  * @return The number of actually affected rows. 0 on error
104  */
105  u64 execute(const std::string& query);
106 
107  /**
108  * Execute a query (usually, but not limited to INSERT) with interest for the last row id.
109  * The connection needs to be established.
110  *
111  * @param query SQL query to execute
112  * @return Last row id of the inserted row. 0 on error
113  */
114  u64 insert(const std::string& query);
115 
116  /**
117  * Execute a query with an result (if no result is returned, the result_set will be empty).
118  * The connection needs to be established.
119  * Note: The result is only valid as long as the connection is valid.
120  *
121  * @param query SQL query to execute
122  * @return Result of the query as result_set.
123  */
125 
126  /**
127  * Gets the status of the auto_commit setting.
128  *
129  * @return True if auto_commit is enabled
130  */
131  bool auto_commit() const;
132 
133  /**
134  * Sets the auto_commit setting. Default MariaDB setting is TRUE.
135  * The connection needs to be established.
136  * This setting controls the default behavior of holding all changes back until a COMMIT is
137  * issued.
138  * See MariaDB documentation for further information on this setting.
139  *
140  * @return True on success
141  */
142  bool set_auto_commit(bool auto_commit);
143 
144  /**
145  * Create a prepared statement. Use "?" to issue bindings in the query which can then be filled
146  * in.
147  * For information on how to properly use prepared statements please refer to the MariaDB
148  * manual.
149  * The connection needs to be established.
150  * Note that "?" bindings can only be established at certain locations in a SQL statement.
151  * A misplaced "?" will result in an error when executing the statement.
152  * The statement is only valid as long as the connection is valid.
153  *
154  * @return Reference to the created statement.
155  */
157 
158  /**
159  * Create a transaction. Any change to the database will be held back until you COMMIT the
160  * transaction.
161  * A not committed transaction automatically rolls all changes back on destruction.
162  * Note: the transaction is only valid as long as this connection is valid.
163  *
164  * @param level The level of isolation to set while using this transaction. Defaults to
165  * repeatable read
166  * @param consistent_snapshot Indicates whether to require a consistent snapshot before entering
167  * the transaction.
168  * Note: refer to MariaDB manual for further information
169  *
170  * @return Reference to the created transaction.
171  */
173  bool consistent_snapshot = true);
174 
175  /**
176  * Creates a new connection using the given account
177  *
178  * @param account The account used to provide the connection information
179  * @return Reference to the newly created connection
180  */
181  static connection_ref create(const account_ref& account);
182 
183  private:
184  /**
185  * Private constructor used to create a connection with the given account
186  */
188 
189  private:
190  // internal database connection pointer
191  MYSQL* m_mysql;
192 
193  // state of auto_commit setting
195  // name of current schema
197  // current charset
199  // currently used account
201 };
202 }
203 
204 #endif
transaction_ref create_transaction(isolation::level level=isolation::repeatable_read, bool consistent_snapshot=true)
Create a transaction.
Definition: connection.cpp:196
bool set_schema(const std::string &schema)
Sets the schema (database name).
Definition: connection.cpp:36
std::shared_ptr< transaction > transaction_ref
Definition: transaction.hpp:78
std::shared_ptr< result_set > result_set_ref
Definition: result_set.hpp:219
std::shared_ptr< account > account_ref
Definition: account.hpp:19
Class representing a SQL transaction having automatic rollback functionality.
Definition: transaction.hpp:25
void disconnect()
Disconnects from the database.
Definition: connection.cpp:128
result_set_ref query(const std::string &query)
Execute a query with an result (if no result is returned, the result_set will be empty).
Definition: connection.cpp:137
account_ref m_account
Definition: connection.hpp:200
Class used to store account and connection information used by mariadb::connection when connecting...
Definition: account.hpp:46
Class used to represent a MariaDB savepoint having automatic rollback functionality.
Definition: save_point.hpp:22
u64 insert(const std::string &query)
Execute a query (usually, but not limited to INSERT) with interest for the last row id...
Definition: connection.cpp:180
std::string m_charset
Definition: connection.hpp:198
virtual ~connection()
Destroys connection and automatically disconnects.
Definition: connection.cpp:32
bool connected() const
Indicates whether the connection is active.
Definition: connection.cpp:56
account_ref account() const
Gets the account associated with this connection.
Definition: connection.cpp:63
bool connect()
Actually connects to the database using given account, sets SSL and additional options as well as aut...
Definition: connection.cpp:78
Class representing a prepared statement with binding functionality.
Definition: statement.hpp:39
static connection_ref create(const account_ref &account)
Creates a new connection using the given account.
Definition: connection.cpp:28
bool set_auto_commit(bool auto_commit)
Sets the auto_commit setting.
Definition: connection.cpp:67
Wraps a Database connection.
Definition: connection.hpp:27
std::string m_schema
Definition: connection.hpp:196
u64 execute(const std::string &query)
Execute a query without interest in a result.
Definition: connection.cpp:150
bool set_charset(const std::string &value)
Sets the charset.
Definition: connection.cpp:47
bool auto_commit() const
Gets the status of the auto_commit setting.
Definition: connection.cpp:65
unsigned long long u64
Definition: types.hpp:34
std::shared_ptr< connection > connection_ref
Definition: statement.hpp:33
connection(const account_ref &account)
Private constructor used to create a connection with the given account.
Definition: connection.cpp:25
const std::string & charset() const
Gets the charset associated with this connection.
Definition: connection.cpp:45
Class used to store query and statement results.
Definition: result_set.hpp:69
std::shared_ptr< statement > statement_ref
Definition: statement.hpp:109
const std::string & schema() const
Gets the schema (database name)
Definition: connection.cpp:34
statement_ref create_statement(const std::string &query)
Create a prepared statement.
Definition: connection.cpp:190