1<?php
2/**
3 * Copyright 2007 Maintainable Software, LLC
4 * Copyright 2008-2017 Horde LLC (http://www.horde.org/)
5 *
6 * @author     Mike Naberezny <mike@maintainable.com>
7 * @author     Derek DeVries <derek@maintainable.com>
8 * @author     Chuck Hagenbuch <chuck@horde.org>
9 * @license    http://www.horde.org/licenses/bsd
10 * @category   Horde
11 * @package    Db
12 * @subpackage Adapter
13 */
14
15/**
16 * @author     Mike Naberezny <mike@maintainable.com>
17 * @author     Derek DeVries <derek@maintainable.com>
18 * @author     Chuck Hagenbuch <chuck@horde.org>
19 * @license    http://www.horde.org/licenses/bsd
20 * @category   Horde
21 * @package    Db
22 * @subpackage Adapter
23 */
24interface Horde_Db_Adapter
25{
26    /**
27     * Returns the human-readable name of the adapter.  Use mixed case - one
28     * can always use downcase if needed.
29     *
30     * @return string
31     */
32    public function adapterName();
33
34    /**
35     * Does this adapter support migrations?  Backend specific, as the
36     * abstract adapter always returns +false+.
37     *
38     * @return boolean
39     */
40    public function supportsMigrations();
41
42    /**
43     * Does this adapter support using DISTINCT within COUNT?  This is +true+
44     * for all adapters except sqlite.
45     *
46     * @return boolean
47     */
48    public function supportsCountDistinct();
49
50    /**
51     * Should primary key values be selected from their corresponding
52     * sequence before the insert statement?  If true, next_sequence_value
53     * is called before each insert to set the record's primary key.
54     * This is false for all adapters but Firebird.
55     *
56     * @return boolean
57     */
58    public function prefetchPrimaryKey($tableName = null);
59
60
61    /*##########################################################################
62    # Connection Management
63    ##########################################################################*/
64
65    /**
66     * Connect to the db.
67     */
68    public function connect();
69
70    /**
71     * Is the connection active?
72     *
73     * @return boolean
74     */
75    public function isActive();
76
77    /**
78     * Reconnect to the db.
79     */
80    public function reconnect();
81
82    /**
83     * Disconnect from db.
84     */
85    public function disconnect();
86
87    /**
88     * Provides access to the underlying database connection. Useful for when
89     * you need to call a proprietary method such as postgresql's
90     * lo_* methods.
91     *
92     * @return resource
93     */
94    public function rawConnection();
95
96
97    /*##########################################################################
98    # Quoting
99    ##########################################################################*/
100
101    /**
102     * Quotes a string, escaping any special characters.
103     *
104     * @param   string  $string
105     * @return  string
106     */
107    public function quoteString($string);
108
109
110    /*##########################################################################
111    # Database Statements
112    ##########################################################################*/
113
114    /**
115     * Returns an array of records with the column names as keys, and
116     * column values as values.
117     *
118     * @param string  $sql   SQL statement.
119     * @param mixed $arg1    Either an array of bound parameters or a query
120     *                       name.
121     * @param string $arg2   If $arg1 contains bound parameters, the query
122     *                       name.
123     *
124     * @return Horde_Db_Adapter_Base_Result
125     * @throws Horde_Db_Exception
126     */
127    public function select($sql, $arg1 = null, $arg2 = null);
128
129    /**
130     * Returns an array of record hashes with the column names as keys and
131     * column values as values.
132     *
133     * @param string $sql   SQL statement.
134     * @param mixed $arg1   Either an array of bound parameters or a query
135     *                      name.
136     * @param string $arg2  If $arg1 contains bound parameters, the query
137     *                      name.
138     *
139     * @return array
140     * @throws Horde_Db_Exception
141     */
142    public function selectAll($sql, $arg1 = null, $arg2 = null);
143
144    /**
145     * Returns a record hash with the column names as keys and column values
146     * as values.
147     *
148     * @param string $sql   SQL statement.
149     * @param mixed $arg1   Either an array of bound parameters or a query
150     *                      name.
151     * @param string $arg2  If $arg1 contains bound parameters, the query
152     *                      name.
153     *
154     * @return array
155     * @throws Horde_Db_Exception
156     */
157    public function selectOne($sql, $arg1 = null, $arg2 = null);
158
159    /**
160     * Returns a single value from a record
161     *
162     * @param string $sql   SQL statement.
163     * @param mixed $arg1   Either an array of bound parameters or a query
164     *                      name.
165     * @param string $arg2  If $arg1 contains bound parameters, the query
166     *                      name.
167     *
168     * @return string
169     * @throws Horde_Db_Exception
170     */
171    public function selectValue($sql, $arg1 = null, $arg2 = null);
172
173    /**
174     * Returns an array of the values of the first column in a select:
175     *   selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]
176     *
177     * @param string $sql   SQL statement.
178     * @param mixed $arg1   Either an array of bound parameters or a query
179     *                      name.
180     * @param string $arg2  If $arg1 contains bound parameters, the query
181     *                      name.
182     *
183     * @return array
184     * @throws Horde_Db_Exception
185     */
186    public function selectValues($sql, $arg1 = null, $arg2 = null);
187
188    /**
189     * Returns an array where the keys are the first column of a select, and the
190     * values are the second column:
191     *
192     *   selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler']
193     *
194     * @param string $sql   SQL statement.
195     * @param mixed $arg1   Either an array of bound parameters or a query
196     *                      name.
197     * @param string $arg2  If $arg1 contains bound parameters, the query
198     *                      name.
199     *
200     * @return array
201     * @throws Horde_Db_Exception
202     */
203    public function selectAssoc($sql, $arg1 = null, $arg2 = null);
204
205    /**
206     * Executes the SQL statement in the context of this connection.
207     *
208     * @deprecated  Deprecated for external usage. Use select() instead.
209     *
210     * @param string $sql   SQL statement.
211     * @param mixed $arg1   Either an array of bound parameters or a query
212     *                      name.
213     * @param string $arg2  If $arg1 contains bound parameters, the query
214     *                      name.
215     *
216     * @return mixed
217     * @throws Horde_Db_Exception
218     */
219    public function execute($sql, $arg1 = null, $arg2 = null);
220
221    /**
222     * Inserts a row into a table.
223     *
224     * @param string $sql           SQL statement.
225     * @param array|string $arg1    Either an array of bound parameters or a
226     *                              query name.
227     * @param string $arg2          If $arg1 contains bound parameters, the
228     *                              query name.
229     * @param string $pk            The primary key column.
230     * @param integer $idValue      The primary key value. This parameter is
231     *                              required if the primary key is inserted
232     *                              manually.
233     * @param string $sequenceName  The sequence name.
234     *
235     * @return integer  Last inserted ID.
236     * @throws Horde_Db_Exception
237     */
238    public function insert($sql, $arg1 = null, $arg2 = null, $pk = null,
239                           $idValue = null, $sequenceName = null);
240
241    /**
242     * Inserts a row including BLOBs into a table.
243     *
244     * @since Horde_Db 2.1.0
245     *
246     * @param string $table     The table name.
247     * @param array $fields     A hash of column names and values. BLOB columns
248     *                          must be provided as Horde_Db_Value_Binary
249     *                          objects.
250     * @param string $pk        The primary key column.
251     * @param integer $idValue  The primary key value. This parameter is
252     *                          required if the primary key is inserted
253     *                          manually.
254     *
255     * @return integer  Last inserted ID.
256     * @throws Horde_Db_Exception
257     */
258    public function insertBlob($table, $fields, $pk = null, $idValue = null);
259
260    /**
261     * Executes the update statement and returns the number of rows affected.
262     *
263     * @param string $sql   SQL statement.
264     * @param mixed $arg1   Either an array of bound parameters or a query
265     *                      name.
266     * @param string $arg2  If $arg1 contains bound parameters, the query
267     *                      name.
268     *
269     * @return integer  Number of rows affected.
270     * @throws Horde_Db_Exception
271     */
272    public function update($sql, $arg1 = null, $arg2 = null);
273
274    /**
275     * Updates rows including BLOBs into a table.
276     *
277     * @since Horde_Db 2.2.0
278     *
279     * @param string $table  The table name.
280     * @param array $fields  A hash of column names and values. BLOB columns
281     *                       must be provided as Horde_Db_Value_Binary objects.
282     * @param string $where  A WHERE clause.
283     *
284     * @throws Horde_Db_Exception
285     */
286    public function updateBlob($table, $fields, $where = '');
287
288    /**
289     * Executes the delete statement and returns the number of rows affected.
290     *
291     * @param string $sql   SQL statement.
292     * @param mixed $arg1   Either an array of bound parameters or a query
293     *                      name.
294     * @param string $arg2  If $arg1 contains bound parameters, the query
295     *                      name.
296     *
297     * @return integer  Number of rows affected.
298     * @throws Horde_Db_Exception
299     */
300    public function delete($sql, $arg1 = null, $arg2 = null);
301
302    /**
303     * Check if a transaction has been started.
304     *
305     * @return boolean  True if transaction has been started.
306     */
307    public function transactionStarted();
308
309    /**
310     * Begins the transaction (and turns off auto-committing).
311     */
312    public function beginDbTransaction();
313
314    /**
315     * Commits the transaction (and turns on auto-committing).
316     */
317    public function commitDbTransaction();
318
319    /**
320     * Rolls back the transaction (and turns on auto-committing). Must be
321     * done if the transaction block raises an exception or returns false.
322     */
323    public function rollbackDbTransaction();
324
325    /**
326     * Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
327     *
328     * @param string $sql     SQL statement.
329     * @param array $options  TODO
330     *
331     * @return string
332     */
333    public function addLimitOffset($sql, $options);
334
335    /**
336     * Appends a locking clause to an SQL statement.
337     * This method *modifies* the +sql+ parameter.
338     *
339     *   # SELECT * FROM suppliers FOR UPDATE
340     *   add_lock! 'SELECT * FROM suppliers', :lock => true
341     *   add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
342     *
343     * @param string &$sql    SQL statment.
344     * @param array $options  TODO.
345     */
346    public function addLock(&$sql, array $options = array());
347}
348