1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<?php
/**
* @copyright Copyright (c) 2016, ownCloud, Inc.
*
* @author Bart Visscher <bartv@thisnet.nl>
* @author Joas Schilling <coding@schilljs.com>
* @author Morris Jobke <hey@morrisjobke.de>
* @author Robin Appelman <icewind@owncloud.com>
* @author Robin McCorkell <robin@mccorkell.me.uk>
* @author Thomas Müller <thomas.mueller@tmit.eu>
*
* @license AGPL-3.0
*
* This code is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License, version 3,
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License, version 3,
* along with this program. If not, see <http://www.gnu.org/licenses/>
*
*/
/**
* Public interface of ownCloud for apps to use.
* DBConnection interface
*
*/
// use OCP namespace for all classes that are considered public.
// This means that they should be used by apps instead of the internal ownCloud classes
namespace OCP;
use OCP\DB\QueryBuilder\IQueryBuilder;
/**
* Interface IDBConnection
*
* @package OCP
* @since 6.0.0
*/
interface IDBConnection {
/**
* Gets the QueryBuilder for the connection.
*
* @return \OCP\DB\QueryBuilder\IQueryBuilder
* @since 8.2.0
*/
public function getQueryBuilder();
/**
* Used to abstract the ownCloud database access away
* @param string $sql the sql query with ? placeholder for params
* @param int $limit the maximum number of rows
* @param int $offset from which row we want to start
* @return \Doctrine\DBAL\Driver\Statement The prepared statement.
* @since 6.0.0
*/
public function prepare($sql, $limit=null, $offset=null);
/**
* Executes an, optionally parameterized, SQL query.
*
* If the query is parameterized, a prepared statement is used.
* If an SQLLogger is configured, the execution is logged.
*
* @param string $query The SQL query to execute.
* @param string[] $params The parameters to bind to the query, if any.
* @param array $types The types the previous parameters are in.
* @return \Doctrine\DBAL\Driver\Statement The executed statement.
* @since 8.0.0
*/
public function executeQuery($query, array $params = array(), $types = array());
/**
* Executes an SQL INSERT/UPDATE/DELETE query with the given parameters
* and returns the number of affected rows.
*
* This method supports PDO binding types as well as DBAL mapping types.
*
* @param string $query The SQL query.
* @param array $params The query parameters.
* @param array $types The parameter types.
* @return integer The number of affected rows.
* @since 8.0.0
*/
public function executeUpdate($query, array $params = array(), array $types = array());
/**
* Used to get the id of the just inserted element
* @param string $table the name of the table where we inserted the item
* @return int the id of the inserted element
* @since 6.0.0
*/
public function lastInsertId($table = null);
/**
* Insert a row if the matching row does not exists.
*
* @param string $table The table name (will replace *PREFIX* with the actual prefix)
* @param array $input data that should be inserted into the table (column name => value)
* @param array|null $compare List of values that should be checked for "if not exists"
* If this is null or an empty array, all keys of $input will be compared
* Please note: text fields (clob) must not be used in the compare array
* @return int number of inserted rows
* @throws \Doctrine\DBAL\DBALException
* @since 6.0.0 - parameter $compare was added in 8.1.0, return type changed from boolean in 8.1.0
*/
public function insertIfNotExist($table, $input, array $compare = null);
/**
* Insert or update a row value
*
* @param string $table
* @param array $keys (column name => value)
* @param array $values (column name => value)
* @param array $updatePreconditionValues ensure values match preconditions (column name => value)
* @return int number of new rows
* @throws \Doctrine\DBAL\DBALException
* @throws PreconditionNotMetException
* @since 9.0.0
*/
public function setValues($table, array $keys, array $values, array $updatePreconditionValues = []);
/**
* Create an exclusive read+write lock on a table
*
* Important Note: Due to the nature how locks work on different DBs, it is
* only possible to lock one table at a time. You should also NOT start a
* transaction while holding a lock.
*
* @param string $tableName
* @since 9.1.0
*/
public function lockTable($tableName);
/**
* Release a previous acquired lock again
*
* @since 9.1.0
*/
public function unlockTable();
/**
* Start a transaction
* @since 6.0.0
*/
public function beginTransaction();
/**
* Check if a transaction is active
*
* @return bool
* @since 8.2.0
*/
public function inTransaction();
/**
* Commit the database changes done during a transaction that is in progress
* @since 6.0.0
*/
public function commit();
/**
* Rollback the database changes done during a transaction that is in progress
* @since 6.0.0
*/
public function rollBack();
/**
* Gets the error code and message as a string for logging
* @return string
* @since 6.0.0
*/
public function getError();
/**
* Fetch the SQLSTATE associated with the last database operation.
*
* @return integer The last error code.
* @since 8.0.0
*/
public function errorCode();
/**
* Fetch extended error information associated with the last database operation.
*
* @return array The last error information.
* @since 8.0.0
*/
public function errorInfo();
/**
* Establishes the connection with the database.
*
* @return bool
* @since 8.0.0
*/
public function connect();
/**
* Close the database connection
* @since 8.0.0
*/
public function close();
/**
* Quotes a given input parameter.
*
* @param mixed $input Parameter to be quoted.
* @param int $type Type of the parameter.
* @return string The quoted parameter.
* @since 8.0.0
*/
public function quote($input, $type = IQueryBuilder::PARAM_STR);
/**
* Gets the DatabasePlatform instance that provides all the metadata about
* the platform this driver connects to.
*
* @return \Doctrine\DBAL\Platforms\AbstractPlatform The database platform.
* @since 8.0.0
*/
public function getDatabasePlatform();
/**
* Drop a table from the database if it exists
*
* @param string $table table name without the prefix
* @since 8.0.0
*/
public function dropTable($table);
/**
* Check if a table exists
*
* @param string $table table name without the prefix
* @return bool
* @since 8.0.0
*/
public function tableExists($table);
/**
* Escape a parameter to be used in a LIKE query
*
* @param string $param
* @return string
* @since 9.0.0
*/
public function escapeLikeParameter($param);
}
|
