database: Add interface to handle transactions
[strongswan.git] / src / libstrongswan / database / database.h
1 /*
2 * Copyright (C) 2013 Tobias Brunner
3 * Copyright (C) 2008 Martin Willi
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup databasei database
19 * @{ @ingroup database
20 */
21
22 #ifndef DATABASE_H_
23 #define DATABASE_H_
24
25 typedef enum db_type_t db_type_t;
26 typedef enum db_driver_t db_driver_t;
27 typedef struct database_t database_t;
28
29 #include <collections/enumerator.h>
30
31 /**
32 * Database column types
33 */
34 enum db_type_t {
35 /** integer type, argument is an "int" */
36 DB_INT,
37 /** unsigned integer, argument is an "u_int" */
38 DB_UINT,
39 /** string type, argument is a "char*" */
40 DB_TEXT,
41 /** binary large object type, argument is a "chunk_t" */
42 DB_BLOB,
43 /** floating point, argument is a "double" */
44 DB_DOUBLE,
45 /** NULL, takes no argument */
46 DB_NULL,
47 };
48
49 /**
50 * Database implementation type.
51 */
52 enum db_driver_t {
53 /** matches to other databases */
54 DB_ANY = 0,
55 /** SQLite database */
56 DB_SQLITE,
57 /** MySQL database */
58 DB_MYSQL,
59 };
60
61 /**
62 * Names for db_driver_t
63 */
64 extern enum_name_t *db_driver_names;
65
66 /**
67 * Interface for a database implementation.
68 *
69 * @code
70 int affected, rowid, aint;
71 char *atext;
72 database_t *db;
73 enumerator_t *enumerator;
74
75 db = lib->database->create("mysql://user:pass@host/database");
76 affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
77 DB_INT, 77, DB_TEXT, "a text");
78 printf("inserted %d row, new row ID: %d\n", affected, rowid);
79
80 enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
81 DB_INT, 10, // 1 argument to SQL string
82 DB_INT, DB_TEXT); // 2 enumerated types in query
83 if (enumerator)
84 {
85 while (enumerator->enumerate(enumerator, &aint, &atext))
86 {
87 printf("%d: %s\n", aint, atext);
88 }
89 enumerator->destroy(enumerator);
90 }
91 @endcode
92 */
93 struct database_t {
94
95 /**
96 * Run a query which returns rows, such as a SELECT.
97 *
98 * @param sql sql query string, containing '?' placeholders
99 * @param ... list of sql placeholder db_type_t followed by its value,
100 * followed by enumerators arguments as db_type_t's
101 * @return enumerator as defined with arguments, NULL on failure
102 */
103 enumerator_t* (*query)(database_t *this, char *sql, ...);
104
105 /**
106 * Execute a query which does not return rows, such as INSERT.
107 *
108 * @param rowid pointer to write inserted AUTO_INCREMENT row ID, or NULL
109 * @param sql sql string, containing '?' placeholders
110 * @param ... list of sql placeholder db_type_t followed by its value
111 * @return number of affected rows, < 0 on failure
112 */
113 int (*execute)(database_t *this, int *rowid, char *sql, ...);
114
115 /**
116 * Start a transaction.
117 *
118 * @note Either commit() or rollback() has to be called to end the
119 * transaction.
120 * @note Transactions are thread-specific. So commit()/rollbak() has to be
121 * called from the same thread.
122 * @note While this method can be called multiple times (commit/rollback
123 * have to be called an equal number of times) real nested transactions are
124 * not supported. So if any if the "inner" transactions are rolled back
125 * the outer most transaction is rolled back.
126 *
127 * @return TRUE on success
128 */
129 bool (*transaction)(database_t *this);
130
131 /**
132 * Commit all changes made during the current transaction.
133 *
134 * @return TRUE on success
135 */
136 bool (*commit)(database_t *this);
137
138 /**
139 * Rollback/revert all changes made during the current transaction.
140 *
141 * @return TRUE on success
142 */
143 bool (*rollback)(database_t *this);
144
145 /**
146 * Get the database implementation type.
147 *
148 * To allow driver specific SQL or performance optimizations each database
149 * implementations can be queried for its type.
150 *
151 * @return database implementation type
152 */
153 db_driver_t (*get_driver)(database_t *this);
154
155 /**
156 * Destroy a database connection.
157 */
158 void (*destroy)(database_t *this);
159 };
160
161 #endif /** DATABASE_H_ @}*/