| Index: trunk/phase3/maintenance/benchmarks/bench_delete_truncate.php |
| — | — | @@ -13,7 +13,7 @@ |
| 14 | 14 | $dbw = wfGetDB( DB_MASTER ); |
| 15 | 15 | |
| 16 | 16 | $test = $dbw->tableName( 'test' ); |
| 17 | | - $dbw->doQuery( "CREATE TABLE IF NOT EXISTS /*_*/$test ( |
| | 17 | + $dbw->query( "CREATE TABLE IF NOT EXISTS /*_*/$test ( |
| 18 | 18 | test_id int unsigned NOT NULL PRIMARY KEY AUTO_INCREMENT, |
| 19 | 19 | text varbinary(255) NOT NULL |
| 20 | 20 | );" ); |
| — | — | @@ -70,9 +70,9 @@ |
| 71 | 71 | */ |
| 72 | 72 | private function truncate( $dbw ) { |
| 73 | 73 | $test = $dbw->tableName( 'test' ); |
| 74 | | - $dbw->doQuery( "TRUNCATE TABLE $test" ); |
| | 74 | + $dbw->query( "TRUNCATE TABLE $test" ); |
| 75 | 75 | } |
| 76 | 76 | } |
| 77 | 77 | |
| 78 | 78 | $maintClass = "BenchmarkDeleteTruncate"; |
| 79 | | -require_once( RUN_MAINTENANCE_IF_MAIN ); |
| \ No newline at end of file |
| | 79 | +require_once( RUN_MAINTENANCE_IF_MAIN ); |
| Index: trunk/phase3/includes/db/Database.php |
| — | — | @@ -44,13 +44,11 @@ |
| 45 | 45 | |
| 46 | 46 | /** |
| 47 | 47 | * The DBMS-dependent part of query() |
| 48 | | - * @todo FIXME: Make this private someday |
| 49 | 48 | * |
| 50 | 49 | * @param $sql String: SQL query. |
| 51 | 50 | * @return Result object to feed to fetchObject, fetchRow, ...; or false on failure |
| 52 | | - * @private |
| 53 | 51 | */ |
| 54 | | - function doQuery( $sql ); |
| | 52 | + protected function doQuery( $sql ); |
| 55 | 53 | |
| 56 | 54 | /** |
| 57 | 55 | * Fetch the next row from the given result object, in object form. |
| — | — | @@ -251,17 +249,37 @@ |
| 252 | 250 | } |
| 253 | 251 | |
| 254 | 252 | /** |
| 255 | | - * Boolean, controls output of large amounts of debug information |
| | 253 | + * Boolean, controls output of large amounts of debug information. |
| | 254 | + * @param $debug: |
| | 255 | + * - true to enable debugging |
| | 256 | + * - false to disable debugging |
| | 257 | + * - omitted or null to do nothing |
| | 258 | + * |
| | 259 | + * @return The previous value of the flag |
| 256 | 260 | */ |
| 257 | 261 | function debug( $debug = null ) { |
| 258 | 262 | return wfSetBit( $this->mFlags, DBO_DEBUG, $debug ); |
| 259 | 263 | } |
| 260 | 264 | |
| 261 | 265 | /** |
| 262 | | - * Turns buffering of SQL result sets on (true) or off (false). |
| 263 | | - * Default is "on" and it should not be changed without good reasons. |
| | 266 | + * Turns buffering of SQL result sets on (true) or off (false). Default is |
| | 267 | + * "on". |
| 264 | 268 | * |
| 265 | | - * @return bool |
| | 269 | + * Unbuffered queries are very troublesome in MySQL: |
| | 270 | + * |
| | 271 | + * - If another query is executed while the first query is being read |
| | 272 | + * out, the first query is killed. This means you can't call normal |
| | 273 | + * MediaWiki functions while you are reading an unbuffered query result |
| | 274 | + * from a normal wfGetDB() connection. |
| | 275 | + * |
| | 276 | + * - Unbuffered queries cause the MySQL server to use large amounts of |
| | 277 | + * memory and to hold broad locks which block other queries. |
| | 278 | + * |
| | 279 | + * If you want to limit client-side memory, it's almost always better to |
| | 280 | + * split up queries into batches using a LIMIT clause than to switch off |
| | 281 | + * buffering. |
| | 282 | + * |
| | 283 | + * @return The previous value of the flag |
| 266 | 284 | */ |
| 267 | 285 | function bufferResults( $buffer = null ) { |
| 268 | 286 | if ( is_null( $buffer ) ) { |
| — | — | @@ -277,32 +295,50 @@ |
| 278 | 296 | * database errors. Default is on (false). When turned off, the |
| 279 | 297 | * code should use lastErrno() and lastError() to handle the |
| 280 | 298 | * situation as appropriate. |
| | 299 | + * |
| | 300 | + * @return The previous value of the flag. |
| 281 | 301 | */ |
| 282 | 302 | function ignoreErrors( $ignoreErrors = null ) { |
| 283 | 303 | return wfSetBit( $this->mFlags, DBO_IGNORE, $ignoreErrors ); |
| 284 | 304 | } |
| 285 | 305 | |
| 286 | 306 | /** |
| 287 | | - * The current depth of nested transactions |
| 288 | | - * @param $level Integer: , default NULL. |
| | 307 | + * Gets or sets the current transaction level. |
| | 308 | + * |
| | 309 | + * Historically, transactions were allowed to be "nested". This is no |
| | 310 | + * longer supported, so this function really only returns a boolean. |
| | 311 | + * |
| | 312 | + * @param $level An integer (0 or 1), or omitted to leave it unchanged. |
| | 313 | + * @return The previous value |
| 289 | 314 | */ |
| 290 | 315 | function trxLevel( $level = null ) { |
| 291 | 316 | return wfSetVar( $this->mTrxLevel, $level ); |
| 292 | 317 | } |
| 293 | 318 | |
| 294 | 319 | /** |
| 295 | | - * Number of errors logged, only useful when errors are ignored |
| | 320 | + * Get/set the number of errors logged. Only useful when errors are ignored |
| | 321 | + * @param $count The count to set, or omitted to leave it unchanged. |
| | 322 | + * @return The error count |
| 296 | 323 | */ |
| 297 | 324 | function errorCount( $count = null ) { |
| 298 | 325 | return wfSetVar( $this->mErrorCount, $count ); |
| 299 | 326 | } |
| 300 | 327 | |
| | 328 | + /** |
| | 329 | + * Get/set the table prefix. |
| | 330 | + * @param $prefix The table prefix to set, or omitted to leave it unchanged. |
| | 331 | + * @return The previous table prefix. |
| | 332 | + */ |
| 301 | 333 | function tablePrefix( $prefix = null ) { |
| 302 | 334 | return wfSetVar( $this->mTablePrefix, $prefix, true ); |
| 303 | 335 | } |
| 304 | 336 | |
| 305 | 337 | /** |
| 306 | | - * Properties passed down from the server info array of the load balancer |
| | 338 | + * Get properties passed down from the server info array of the load |
| | 339 | + * balancer. |
| | 340 | + * |
| | 341 | + * @param $name The entry of the info array to get, or null to get the |
| | 342 | + * whole array |
| 307 | 343 | */ |
| 308 | 344 | function getLBInfo( $name = null ) { |
| 309 | 345 | if ( is_null( $name ) ) { |
| — | — | @@ -317,6 +353,10 @@ |
| 318 | 354 | } |
| 319 | 355 | |
| 320 | 356 | /** |
| | 357 | + * Set the LB info array, or a member of it. If called with one parameter, |
| | 358 | + * the LB info array is set to that parameter. If it is called with two |
| | 359 | + * parameters, the member with the given name is set to the given value. |
| | 360 | + * |
| 321 | 361 | * @param $name |
| 322 | 362 | * @param $value |
| 323 | 363 | * @return void |
| — | — | @@ -655,15 +695,25 @@ |
| 656 | 696 | } |
| 657 | 697 | |
| 658 | 698 | /** |
| 659 | | - * Usually aborts on failure. If errors are explicitly ignored, returns success. |
| | 699 | + * Run an SQL query and return the result. Normally throws a DBQueryError |
| | 700 | + * on failure. If errors are ignored, returns false instead. |
| 660 | 701 | * |
| | 702 | + * In new code, the query wrappers select(), insert(), update(), delete(), |
| | 703 | + * etc. should be used where possible, since they give much better DBMS |
| | 704 | + * independence and automatically quote or validate user input in a variety |
| | 705 | + * of contexts. This function is generally only useful for queries which are |
| | 706 | + * explicitly DBMS-dependent and are unsupported by the query wrappers, such |
| | 707 | + * as CREATE TABLE. |
| | 708 | + * |
| | 709 | + * However, the query wrappers themselves should call this function. |
| | 710 | + * |
| 661 | 711 | * @param $sql String: SQL query |
| 662 | 712 | * @param $fname String: Name of the calling function, for profiling/SHOW PROCESSLIST |
| 663 | 713 | * comment (you can use __METHOD__ or add some extra info) |
| 664 | 714 | * @param $tempIgnore Boolean: Whether to avoid throwing an exception on errors... |
| 665 | 715 | * maybe best to catch the exception instead? |
| 666 | | - * @return boolean|ResultWrapper. true for a successful write query, ResultWrapper object for a successful read query, |
| 667 | | - * or false on failure if $tempIgnore set |
| | 716 | + * @return boolean|ResultWrapper. true for a successful write query, ResultWrapper object |
| | 717 | + * for a successful read query, or false on failure if $tempIgnore set |
| 668 | 718 | * @throws DBQueryError Thrown when the database returns an error of any kind |
| 669 | 719 | */ |
| 670 | 720 | public function query( $sql, $fname = '', $tempIgnore = false ) { |
| — | — | @@ -672,9 +722,6 @@ |
| 673 | 723 | # generalizeSQL will probably cut down the query to reasonable |
| 674 | 724 | # logging size most of the time. The substr is really just a sanity check. |
| 675 | 725 | |
| 676 | | - # Who's been wasting my precious column space? -- TS |
| 677 | | - # $profName = 'query: ' . $fname . ' ' . substr( DatabaseBase::generalizeSQL( $sql ), 0, 255 ); |
| 678 | | - |
| 679 | 726 | if ( $isMaster ) { |
| 680 | 727 | $queryProf = 'query-m: ' . substr( DatabaseBase::generalizeSQL( $sql ), 0, 255 ); |
| 681 | 728 | $totalProf = 'DatabaseBase::query-master'; |
| — | — | @@ -689,34 +736,30 @@ |
| 690 | 737 | |
| 691 | 738 | $this->mLastQuery = $sql; |
| 692 | 739 | if ( !$this->mDoneWrites && $this->isWriteQuery( $sql ) ) { |
| 693 | | - // Set a flag indicating that writes have been done |
| | 740 | + # Set a flag indicating that writes have been done |
| 694 | 741 | wfDebug( __METHOD__ . ": Writes done: $sql\n" ); |
| 695 | 742 | $this->mDoneWrites = true; |
| 696 | 743 | } |
| 697 | 744 | |
| 698 | 745 | # Add a comment for easy SHOW PROCESSLIST interpretation |
| 699 | | - # if ( $fname ) { |
| 700 | | - global $wgUser; |
| 701 | | - if ( is_object( $wgUser ) && $wgUser->isItemLoaded( 'name' ) ) { |
| 702 | | - $userName = $wgUser->getName(); |
| 703 | | - if ( mb_strlen( $userName ) > 15 ) { |
| 704 | | - $userName = mb_substr( $userName, 0, 15 ) . '...'; |
| 705 | | - } |
| 706 | | - $userName = str_replace( '/', '', $userName ); |
| 707 | | - } else { |
| 708 | | - $userName = ''; |
| | 746 | + global $wgUser; |
| | 747 | + if ( is_object( $wgUser ) && $wgUser->isItemLoaded( 'name' ) ) { |
| | 748 | + $userName = $wgUser->getName(); |
| | 749 | + if ( mb_strlen( $userName ) > 15 ) { |
| | 750 | + $userName = mb_substr( $userName, 0, 15 ) . '...'; |
| 709 | 751 | } |
| 710 | | - $commentedSql = preg_replace( '/\s/', " /* $fname $userName */ ", $sql, 1 ); |
| 711 | | - # } else { |
| 712 | | - # $commentedSql = $sql; |
| 713 | | - # } |
| | 752 | + $userName = str_replace( '/', '', $userName ); |
| | 753 | + } else { |
| | 754 | + $userName = ''; |
| | 755 | + } |
| | 756 | + $commentedSql = preg_replace( '/\s/', " /* $fname $userName */ ", $sql, 1 ); |
| 714 | 757 | |
| 715 | 758 | # If DBO_TRX is set, start a transaction |
| 716 | 759 | if ( ( $this->mFlags & DBO_TRX ) && !$this->trxLevel() && |
| 717 | 760 | $sql != 'BEGIN' && $sql != 'COMMIT' && $sql != 'ROLLBACK' ) { |
| 718 | | - // avoid establishing transactions for SHOW and SET statements too - |
| 719 | | - // that would delay transaction initializations to once connection |
| 720 | | - // is really used by application |
| | 761 | + # avoid establishing transactions for SHOW and SET statements too - |
| | 762 | + # that would delay transaction initializations to once connection |
| | 763 | + # is really used by application |
| 721 | 764 | $sqlstart = substr( $sql, 0, 10 ); // very much worth it, benchmark certified(tm) |
| 722 | 765 | if ( strpos( $sqlstart, "SHOW " ) !== 0 and strpos( $sqlstart, "SET " ) !== 0 ) |
| 723 | 766 | $this->begin(); |
| — | — | @@ -778,6 +821,9 @@ |
| 779 | 822 | } |
| 780 | 823 | |
| 781 | 824 | /** |
| | 825 | + * Report a query error. Log the error, and if neither the object ignore |
| | 826 | + * flag nor the $tempIgnore flag is set, throw a DBQueryError. |
| | 827 | + * |
| 782 | 828 | * @param $error String |
| 783 | 829 | * @param $errno Integer |
| 784 | 830 | * @param $sql String |
| — | — | @@ -809,6 +855,10 @@ |
| 810 | 856 | * & = filename; reads the file and inserts as a blob |
| 811 | 857 | * (we don't use this though...) |
| 812 | 858 | * |
| | 859 | + * This function should not be used directly by new code outside of the |
| | 860 | + * database classes. The query wrapper functions (select() etc.) should be |
| | 861 | + * used instead. |
| | 862 | + * |
| 813 | 863 | * @return array |
| 814 | 864 | */ |
| 815 | 865 | function prepare( $sql, $func = 'DatabaseBase::prepare' ) { |
| — | — | @@ -818,6 +868,9 @@ |
| 819 | 869 | return array( 'query' => $sql, 'func' => $func ); |
| 820 | 870 | } |
| 821 | 871 | |
| | 872 | + /** |
| | 873 | + * Free a prepared query, generated by prepare(). |
| | 874 | + */ |
| 822 | 875 | function freePrepared( $prepared ) { |
| 823 | 876 | /* No-op by default */ |
| 824 | 877 | } |
| — | — | @@ -844,6 +897,11 @@ |
| 845 | 898 | /** |
| 846 | 899 | * Prepare & execute an SQL statement, quoting and inserting arguments |
| 847 | 900 | * in the appropriate places. |
| | 901 | + * |
| | 902 | + * This function should not be used directly by new code outside of the |
| | 903 | + * database classes. The query wrapper functions (select() etc.) should be |
| | 904 | + * used instead. |
| | 905 | + * |
| 848 | 906 | * @param $query String |
| 849 | 907 | * @param $args ... |
| 850 | 908 | * |
| — | — | @@ -909,17 +967,18 @@ |
| 910 | 968 | } |
| 911 | 969 | |
| 912 | 970 | /** |
| 913 | | - * Free a result object |
| | 971 | + * Free a result object returned by query() or select(). It's usually not |
| | 972 | + * necessary to call this, just use unset() or let the variable holding |
| | 973 | + * the result object go out of scope. |
| | 974 | + * |
| 914 | 975 | * @param $res Mixed: A SQL result |
| 915 | 976 | */ |
| 916 | 977 | function freeResult( $res ) { |
| 917 | | - # Stub. Might not really need to be overridden, since results should |
| 918 | | - # be freed by PHP when the variable goes out of scope anyway. |
| 919 | 978 | } |
| 920 | 979 | |
| 921 | 980 | /** |
| 922 | | - * Simple UPDATE wrapper |
| 923 | | - * Usually aborts on failure |
| | 981 | + * Simple UPDATE wrapper. |
| | 982 | + * Usually throws a DBQueryError on failure. |
| 924 | 983 | * If errors are explicitly ignored, returns success |
| 925 | 984 | * |
| 926 | 985 | * This function exists for historical reasons, DatabaseBase::update() has a more standard |
| — | — | @@ -936,11 +995,25 @@ |
| 937 | 996 | } |
| 938 | 997 | |
| 939 | 998 | /** |
| 940 | | - * Simple SELECT wrapper, returns a single field, input must be encoded |
| 941 | | - * Usually aborts on failure |
| 942 | | - * If errors are explicitly ignored, returns FALSE on failure |
| | 999 | + * A SELECT wrapper which returns a single field from a single result row. |
| | 1000 | + * |
| | 1001 | + * Usually throws a DBQueryError on failure. If errors are explicitly |
| | 1002 | + * ignored, returns false on failure. |
| | 1003 | + * |
| | 1004 | + * If no result rows are returned from the query, false is returned. |
| | 1005 | + * |
| | 1006 | + * @param $table Table name. See DatabaseBase::select() for details. |
| | 1007 | + * @param $var The field name to select. This must be a valid SQL |
| | 1008 | + * fragment: do not use unvalidated user input. |
| | 1009 | + * @param $cond The condition array. See DatabaseBase::select() for details. |
| | 1010 | + * @param $fname The function name of the caller. |
| | 1011 | + * @param $options The query options. See DatabaseBase::select() for details. |
| | 1012 | + * |
| | 1013 | + * @return The value from the field, or false on failure. |
| 943 | 1014 | */ |
| 944 | | - function selectField( $table, $var, $cond = '', $fname = 'DatabaseBase::selectField', $options = array() ) { |
| | 1015 | + function selectField( $table, $var, $cond = '', $fname = 'DatabaseBase::selectField', |
| | 1016 | + $options = array() ) |
| | 1017 | + { |
| 945 | 1018 | if ( !is_array( $options ) ) { |
| 946 | 1019 | $options = array( $options ); |
| 947 | 1020 | } |
| — | — | @@ -964,15 +1037,14 @@ |
| 965 | 1038 | |
| 966 | 1039 | /** |
| 967 | 1040 | * Returns an optional USE INDEX clause to go after the table, and a |
| 968 | | - * string to go at the end of the query |
| | 1041 | + * string to go at the end of the query. |
| 969 | 1042 | * |
| 970 | | - * @private |
| 971 | | - * |
| 972 | 1043 | * @param $options Array: associative array of options to be turned into |
| 973 | 1044 | * an SQL query, valid keys are listed in the function. |
| 974 | 1045 | * @return Array |
| | 1046 | + * @see DatabaseBase::select() |
| 975 | 1047 | */ |
| 976 | | - function makeSelectOptions( $options ) { |
| | 1048 | + protected function makeSelectOptions( $options ) { |
| 977 | 1049 | $preLimitTail = $postLimitTail = ''; |
| 978 | 1050 | $startOpts = ''; |
| 979 | 1051 | |
| — | — | @@ -1063,37 +1135,165 @@ |
| 1064 | 1136 | } |
| 1065 | 1137 | |
| 1066 | 1138 | /** |
| 1067 | | - * SELECT wrapper |
| | 1139 | + * Execute a SELECT query constructed using the various parameters provided. |
| | 1140 | + * See below for full details of the parameters. |
| 1068 | 1141 | * |
| 1069 | | - * @param $table Mixed: Array or string, table name(s) (prefix auto-added) |
| 1070 | | - * @param $vars Mixed: Array or string, field name(s) to be retrieved |
| 1071 | | - * @param $conds Mixed: Array or string, condition(s) for WHERE |
| 1072 | | - * @param $fname String: Calling function name (use __METHOD__) for logs/profiling |
| 1073 | | - * @param $options Array: Associative array of options (e.g. array('GROUP BY' => 'page_title')), |
| 1074 | | - * see DatabaseBase::makeSelectOptions code for list of supported stuff |
| 1075 | | - * @param $join_conds Array: Associative array of table join conditions (optional) |
| 1076 | | - * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') ) |
| 1077 | | - * @return ResultWrapper|Bool Database result resource (feed to DatabaseBase::fetchObject |
| 1078 | | - * or whatever), or false on failure |
| | 1142 | + * @param $table Table name |
| | 1143 | + * @param $vars Field names |
| | 1144 | + * @param $conds Conditions |
| | 1145 | + * @param $fname Caller function name |
| | 1146 | + * @param $options Query options |
| | 1147 | + * @param $join_conds Join conditions |
| | 1148 | + * |
| | 1149 | + * |
| | 1150 | + * @b $table |
| | 1151 | + * |
| | 1152 | + * May be either an array of table names, or a single string holding a table |
| | 1153 | + * name. If an array is given, table aliases can be specified, for example: |
| | 1154 | + * |
| | 1155 | + * array( 'a' => 'user' ) |
| | 1156 | + * |
| | 1157 | + * This includes the user table in the query, with the alias "a" available |
| | 1158 | + * for use in field names (e.g. a.user_name). |
| | 1159 | + * |
| | 1160 | + * All of the table names given here are automatically run through |
| | 1161 | + * DatabaseBase::tableName(), which causes the table prefix (if any) to be |
| | 1162 | + * added, and various other table name mappings to be performed. |
| | 1163 | + * |
| | 1164 | + * |
| | 1165 | + * @b $vars |
| | 1166 | + * |
| | 1167 | + * May be either a field name or an array of field names. The field names |
| | 1168 | + * here are complete fragments of SQL, for direct inclusion into the SELECT |
| | 1169 | + * query. Expressions and aliases may be specified as in SQL, for example: |
| | 1170 | + * |
| | 1171 | + * array( 'MAX(rev_id) AS maxrev' ) |
| | 1172 | + * |
| | 1173 | + * If an expression is given, care must be taken to ensure that it is |
| | 1174 | + * DBMS-independent. |
| | 1175 | + * |
| | 1176 | + * |
| | 1177 | + * @b $conds |
| | 1178 | + * |
| | 1179 | + * May be either a string containing a single condition, or an array of |
| | 1180 | + * conditions. If an array is given, the conditions constructed from each |
| | 1181 | + * element are combined with AND. |
| | 1182 | + * |
| | 1183 | + * Array elements may take one of two forms: |
| | 1184 | + * |
| | 1185 | + * - Elements with a numeric key are interpreted as raw SQL fragments. |
| | 1186 | + * - Elements with a string key are interpreted as equality conditions, |
| | 1187 | + * where the key is the field name. |
| | 1188 | + * - If the value of such an array element is a scalar (such as a |
| | 1189 | + * string), it will be treated as data and thus quoted appropriately. |
| | 1190 | + * If it is null, an IS NULL clause will be added. |
| | 1191 | + * - If the value is an array, an IN(...) clause will be constructed, |
| | 1192 | + * such that the field name may match any of the elements in the |
| | 1193 | + * array. The elements of the array will be quoted. |
| | 1194 | + * - If the field name ends with "!", this is taken as a flag which |
| | 1195 | + * inverts the comparison, allowing NOT IN clauses to be constructed, |
| | 1196 | + * for example: array( 'user_id!' => array( 1, 2, 3 ) ) |
| | 1197 | + * |
| | 1198 | + * Note that expressions are often DBMS-dependent in their syntax. |
| | 1199 | + * DBMS-independent wrappers are provided for constructing several types of |
| | 1200 | + * expression commonly used in condition queries. See: |
| | 1201 | + * - DatabaseBase::buildLike() |
| | 1202 | + * - DatabaseBase::conditional() |
| | 1203 | + * |
| | 1204 | + * |
| | 1205 | + * @b $options |
| | 1206 | + * |
| | 1207 | + * Optional: Array of query options. Boolean options are specified by |
| | 1208 | + * including them in the array as a string value with a numeric key, for |
| | 1209 | + * example: |
| | 1210 | + * |
| | 1211 | + * array( 'FOR UPDATE' ) |
| | 1212 | + * |
| | 1213 | + * The supported options are: |
| | 1214 | + * |
| | 1215 | + * - OFFSET: Skip this many rows at the start of the result set. OFFSET |
| | 1216 | + * with LIMIT can theoretically be used for paging through a result set, |
| | 1217 | + * but this is discouraged in MediaWiki for performance reasons. |
| | 1218 | + * |
| | 1219 | + * - LIMIT: Integer: return at most this many rows. The rows are sorted |
| | 1220 | + * and then the first rows are taken until the limit is reached. LIMIT |
| | 1221 | + * is applied to a result set after OFFSET. |
| | 1222 | + * |
| | 1223 | + * - FOR UPDATE: Boolean: lock the returned rows so that they can't be |
| | 1224 | + * changed until the next COMMIT. |
| | 1225 | + * |
| | 1226 | + * - DISTINCT: Boolean: return only unique result rows. |
| | 1227 | + * |
| | 1228 | + * - GROUP BY: May be either an SQL fragment string naming a field or |
| | 1229 | + * expression to group by, or an array of such SQL fragments. |
| | 1230 | + * |
| | 1231 | + * - HAVING: A string containing a HAVING clause. |
| | 1232 | + * |
| | 1233 | + * - ORDER BY: May be either an SQL fragment giving a field name or |
| | 1234 | + * expression to order by, or an array of such SQL fragments. |
| | 1235 | + * |
| | 1236 | + * - USE INDEX: This may be either a string giving the index name to use |
| | 1237 | + * for the query, or an array. If it is an associative array, each key |
| | 1238 | + * gives the table name (or alias), each value gives the index name to |
| | 1239 | + * use for that table. All strings are SQL fragments and so should be |
| | 1240 | + * validated by the caller. |
| | 1241 | + * |
| | 1242 | + * - EXPLAIN: In MySQL, this causes an EXPLAIN SELECT query to be run, |
| | 1243 | + * instead of SELECT. |
| | 1244 | + * |
| | 1245 | + * And also the following boolean MySQL extensions, see the MySQL manual |
| | 1246 | + * for documentation: |
| | 1247 | + * |
| | 1248 | + * - LOCK IN SHARE MODE |
| | 1249 | + * - STRAIGHT_JOIN |
| | 1250 | + * - HIGH_PRIORITY |
| | 1251 | + * - SQL_BIG_RESULT |
| | 1252 | + * - SQL_BUFFER_RESULT |
| | 1253 | + * - SQL_SMALL_RESULT |
| | 1254 | + * - SQL_CALC_FOUND_ROWS |
| | 1255 | + * - SQL_CACHE |
| | 1256 | + * - SQL_NO_CACHE |
| | 1257 | + * |
| | 1258 | + * |
| | 1259 | + * @b $join_conds |
| | 1260 | + * |
| | 1261 | + * Optional associative array of table-specific join conditions. In the |
| | 1262 | + * most common case, this is unnecessary, since the join condition can be |
| | 1263 | + * in $conds. However, it is useful for doing a LEFT JOIN. |
| | 1264 | + * |
| | 1265 | + * The key of the array contains the table name or alias. The value is an |
| | 1266 | + * array with two elements, numbered 0 and 1. The first gives the type of |
| | 1267 | + * join, the second is an SQL fragment giving the join condition for that |
| | 1268 | + * table. For example: |
| | 1269 | + * |
| | 1270 | + * array( 'page' => array('LEFT JOIN','page_latest=rev_id') ) |
| | 1271 | + * |
| | 1272 | + * @return ResultWrapper. If the query returned no rows, a ResultWrapper |
| | 1273 | + * with no rows in it will be returned. If there was a query error, a |
| | 1274 | + * DBQueryError exception will be thrown, except if the "ignore errors" |
| | 1275 | + * option was set, in which case false will be returned. |
| 1079 | 1276 | */ |
| 1080 | | - function select( $table, $vars, $conds = '', $fname = 'DatabaseBase::select', $options = array(), $join_conds = array() ) { |
| | 1277 | + function select( $table, $vars, $conds = '', $fname = 'DatabaseBase::select', |
| | 1278 | + $options = array(), $join_conds = array() ) |
| | 1279 | + { |
| 1081 | 1280 | $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds ); |
| 1082 | 1281 | |
| 1083 | 1282 | return $this->query( $sql, $fname ); |
| 1084 | 1283 | } |
| 1085 | 1284 | |
| 1086 | 1285 | /** |
| 1087 | | - * SELECT wrapper |
| | 1286 | + * The equivalent of DatabaseBase::select() except that the constructed SQL |
| | 1287 | + * is returned, instead of being immediately executed. |
| 1088 | 1288 | * |
| 1089 | | - * @param $table Mixed: Array or string, table name(s) (prefix auto-added). Array keys are table aliases (optional) |
| 1090 | | - * @param $vars Mixed: Array or string, field name(s) to be retrieved |
| 1091 | | - * @param $conds Mixed: Array or string, condition(s) for WHERE |
| 1092 | | - * @param $fname String: Calling function name (use __METHOD__) for logs/profiling |
| 1093 | | - * @param $options Array: Associative array of options (e.g. array('GROUP BY' => 'page_title')), |
| 1094 | | - * see DatabaseBase::makeSelectOptions code for list of supported stuff |
| 1095 | | - * @param $join_conds Array: Associative array of table join conditions (optional) |
| 1096 | | - * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') ) |
| 1097 | | - * @return string, the SQL text |
| | 1289 | + * @param $table Table name |
| | 1290 | + * @param $vars Field names |
| | 1291 | + * @param $conds Conditions |
| | 1292 | + * @param $fname Caller function name |
| | 1293 | + * @param $options Query options |
| | 1294 | + * @param $join_conds Join conditions |
| | 1295 | + * |
| | 1296 | + * @return SQL query string. |
| | 1297 | + * @see DatabaseBase::select() |
| 1098 | 1298 | */ |
| 1099 | 1299 | function selectSQLText( $table, $vars, $conds = '', $fname = 'DatabaseBase::select', $options = array(), $join_conds = array() ) { |
| 1100 | 1300 | if ( is_array( $vars ) ) { |
| — | — | @@ -1144,24 +1344,22 @@ |
| 1145 | 1345 | } |
| 1146 | 1346 | |
| 1147 | 1347 | /** |
| 1148 | | - * Single row SELECT wrapper |
| 1149 | | - * Aborts or returns FALSE on error |
| | 1348 | + * Single row SELECT wrapper. Equivalent to DatabaseBase::select(), except |
| | 1349 | + * that a single row object is returned. If the query returns no rows, |
| | 1350 | + * false is returned. |
| 1150 | 1351 | * |
| 1151 | | - * @param $table String: table name |
| 1152 | | - * @param $vars String: the selected variables |
| 1153 | | - * @param $conds Array: a condition map, terms are ANDed together. |
| 1154 | | - * Items with numeric keys are taken to be literal conditions |
| 1155 | | - * Takes an array of selected variables, and a condition map, which is ANDed |
| 1156 | | - * e.g: selectRow( "page", array( "page_id" ), array( "page_namespace" => |
| 1157 | | - * NS_MAIN, "page_title" => "Astronomy" ) ) would return an object where |
| 1158 | | - * $obj- >page_id is the ID of the Astronomy article |
| 1159 | | - * @param $fname String: Calling function name |
| 1160 | | - * @param $options Array |
| 1161 | | - * @param $join_conds Array |
| | 1352 | + * @param $table Table name |
| | 1353 | + * @param $vars Field names |
| | 1354 | + * @param $conds Conditions |
| | 1355 | + * @param $fname Caller function name |
| | 1356 | + * @param $options Query options |
| | 1357 | + * @param $join_conds Join conditions |
| 1162 | 1358 | * |
| 1163 | | - * @return ResultWrapper|Bool |
| | 1359 | + * @return ResultWrapper or bool |
| 1164 | 1360 | */ |
| 1165 | | - function selectRow( $table, $vars, $conds, $fname = 'DatabaseBase::selectRow', $options = array(), $join_conds = array() ) { |
| | 1361 | + function selectRow( $table, $vars, $conds, $fname = 'DatabaseBase::selectRow', |
| | 1362 | + $options = array(), $join_conds = array() ) |
| | 1363 | + { |
| 1166 | 1364 | $options['LIMIT'] = 1; |
| 1167 | 1365 | $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds ); |
| 1168 | 1366 | |
| — | — | @@ -1179,11 +1377,18 @@ |
| 1180 | 1378 | } |
| 1181 | 1379 | |
| 1182 | 1380 | /** |
| 1183 | | - * Estimate rows in dataset |
| 1184 | | - * Returns estimated count - not necessarily an accurate estimate across different databases, |
| 1185 | | - * so use sparingly |
| 1186 | | - * Takes same arguments as DatabaseBase::select() |
| | 1381 | + * Estimate rows in dataset. |
| 1187 | 1382 | * |
| | 1383 | + * MySQL allows you to estimate the number of rows that would be returned |
| | 1384 | + * by a SELECT query, using EXPLAIN SELECT. The estimate is provided using |
| | 1385 | + * index cardinality statistics, and is notoriously inaccurate, especially |
| | 1386 | + * when large numbers of rows have recently been added or deleted. |
| | 1387 | + * |
| | 1388 | + * For DBMSs that don't support fast result size estimation, this function |
| | 1389 | + * will actually perform the SELECT COUNT(*). |
| | 1390 | + * |
| | 1391 | + * Takes the same arguments as DatabaseBase::select(). |
| | 1392 | + * |
| 1188 | 1393 | * @param $table String: table name |
| 1189 | 1394 | * @param $vars Array: unused |
| 1190 | 1395 | * @param $conds Array: filters on the table |
| — | — | @@ -1191,7 +1396,9 @@ |
| 1192 | 1397 | * @param $options Array: options for select |
| 1193 | 1398 | * @return Integer: row count |
| 1194 | 1399 | */ |
| 1195 | | - public function estimateRowCount( $table, $vars = '*', $conds = '', $fname = 'DatabaseBase::estimateRowCount', $options = array() ) { |
| | 1400 | + public function estimateRowCount( $table, $vars = '*', $conds = '', |
| | 1401 | + $fname = 'DatabaseBase::estimateRowCount', $options = array() ) |
| | 1402 | + { |
| 1196 | 1403 | $rows = 0; |
| 1197 | 1404 | $res = $this->select ( $table, 'COUNT(*) AS rowcount', $conds, $fname, $options ); |
| 1198 | 1405 | |
| — | — | @@ -1245,7 +1452,7 @@ |
| 1246 | 1453 | |
| 1247 | 1454 | /** |
| 1248 | 1455 | * Determines whether an index exists |
| 1249 | | - * Usually aborts on failure |
| | 1456 | + * Usually throws a DBQueryError on failure |
| 1250 | 1457 | * If errors are explicitly ignored, returns NULL on failure |
| 1251 | 1458 | * |
| 1252 | 1459 | * @return bool|null |
| — | — | @@ -1305,27 +1512,46 @@ |
| 1306 | 1513 | } |
| 1307 | 1514 | |
| 1308 | 1515 | /** |
| | 1516 | + * Helper for DatabaseBase::insert(). |
| | 1517 | + * |
| 1309 | 1518 | * @param $options array |
| 1310 | 1519 | * @return string |
| 1311 | 1520 | */ |
| 1312 | | - function makeInsertOptions( $options ) { |
| | 1521 | + protected function makeInsertOptions( $options ) { |
| 1313 | 1522 | return implode( ' ', $options ); |
| 1314 | 1523 | } |
| 1315 | 1524 | |
| 1316 | 1525 | /** |
| 1317 | | - * INSERT wrapper, inserts an array into a table |
| | 1526 | + * INSERT wrapper, inserts an array into a table. |
| 1318 | 1527 | * |
| 1319 | | - * $a may be a single associative array, or an array of these with numeric keys, for |
| 1320 | | - * multi-row insert. |
| | 1528 | + * $a may be either: |
| 1321 | 1529 | * |
| 1322 | | - * Usually aborts on failure |
| 1323 | | - * If errors are explicitly ignored, returns success |
| | 1530 | + * - A single associative array. The array keys are the field names, and |
| | 1531 | + * the values are the values to insert. The values are treated as data |
| | 1532 | + * and will be quoted appropriately. If NULL is inserted, this will be |
| | 1533 | + * converted to a database NULL. |
| | 1534 | + * - An array with numeric keys, holding a list of associative arrays. |
| | 1535 | + * This causes a multi-row INSERT on DBMSs that support it. The keys in |
| | 1536 | + * each subarray must be identical to each other, and in the same order. |
| 1324 | 1537 | * |
| 1325 | | - * @param $table String: table name (prefix auto-added) |
| 1326 | | - * @param $a Array: Array of rows to insert |
| 1327 | | - * @param $fname String: Calling function name (use __METHOD__) for logs/profiling |
| 1328 | | - * @param $options Mixed: Associative array of options |
| | 1538 | + * Usually throws a DBQueryError on failure. If errors are explicitly ignored, |
| | 1539 | + * returns success. |
| 1329 | 1540 | * |
| | 1541 | + * $options is an array of options, with boolean options encoded as values |
| | 1542 | + * with numeric keys, in the same style as $options in |
| | 1543 | + * DatabaseBase::select(). Supported options are: |
| | 1544 | + * |
| | 1545 | + * - IGNORE: Boolean: if present, duplicate key errors are ignored, and |
| | 1546 | + * any rows which cause duplicate key errors are not inserted. It's |
| | 1547 | + * possible to determine how many rows were successfully inserted using |
| | 1548 | + * DatabaseBase::affectedRows(). |
| | 1549 | + * |
| | 1550 | + * @param $table Table name. This will be passed through |
| | 1551 | + * DatabaseBase::tableName(). |
| | 1552 | + * @param $a Array of rows to insert |
| | 1553 | + * @param $fname Calling function name (use __METHOD__) for logs/profiling |
| | 1554 | + * @param $options Array of options |
| | 1555 | + * |
| 1330 | 1556 | * @return bool |
| 1331 | 1557 | */ |
| 1332 | 1558 | function insert( $table, $a, $fname = 'DatabaseBase::insert', $options = array() ) { |
| — | — | @@ -1373,11 +1599,10 @@ |
| 1374 | 1600 | /** |
| 1375 | 1601 | * Make UPDATE options for the DatabaseBase::update function |
| 1376 | 1602 | * |
| 1377 | | - * @private |
| 1378 | 1603 | * @param $options Array: The options passed to DatabaseBase::update |
| 1379 | 1604 | * @return string |
| 1380 | 1605 | */ |
| 1381 | | - function makeUpdateOptions( $options ) { |
| | 1606 | + protected function makeUpdateOptions( $options ) { |
| 1382 | 1607 | if ( !is_array( $options ) ) { |
| 1383 | 1608 | $options = array( $options ); |
| 1384 | 1609 | } |
| — | — | @@ -1396,15 +1621,26 @@ |
| 1397 | 1622 | } |
| 1398 | 1623 | |
| 1399 | 1624 | /** |
| 1400 | | - * UPDATE wrapper, takes a condition array and a SET array |
| | 1625 | + * UPDATE wrapper. Takes a condition array and a SET array. |
| 1401 | 1626 | * |
| 1402 | | - * @param $table String: The table to UPDATE |
| 1403 | | - * @param $values Array: An array of values to SET |
| 1404 | | - * @param $conds Array: An array of conditions (WHERE). Use '*' to update all rows. |
| 1405 | | - * @param $fname String: The Class::Function calling this function |
| 1406 | | - * (for the log) |
| 1407 | | - * @param $options Array: An array of UPDATE options, can be one or |
| 1408 | | - * more of IGNORE, LOW_PRIORITY |
| | 1627 | + * @param $table The name of the table to UPDATE. This will be passed through |
| | 1628 | + * DatabaseBase::tableName(). |
| | 1629 | + * |
| | 1630 | + * @param $values Array: An array of values to SET. For each array element, |
| | 1631 | + * the key gives the field name, and the value gives the data |
| | 1632 | + * to set that field to. The data will be quoted by |
| | 1633 | + * DatabaseBase::addQuotes(). |
| | 1634 | + * |
| | 1635 | + * @param $conds Array: An array of conditions (WHERE). See |
| | 1636 | + * DatabaseBase::select() for the details of the format of |
| | 1637 | + * condition arrays. Use '*' to update all rows. |
| | 1638 | + * |
| | 1639 | + * @param $fname String: The function name of the caller (from __METHOD__), |
| | 1640 | + * for logging and profiling. |
| | 1641 | + * |
| | 1642 | + * @param $options Array: An array of UPDATE options, can be: |
| | 1643 | + * - IGNORE: Ignore unique key conflicts |
| | 1644 | + * - LOW_PRIORITY: MySQL-specific, see MySQL manual. |
| 1409 | 1645 | * @return Boolean |
| 1410 | 1646 | */ |
| 1411 | 1647 | function update( $table, $values, $conds, $fname = 'DatabaseBase::update', $options = array() ) { |
| — | — | @@ -1421,18 +1657,21 @@ |
| 1422 | 1658 | |
| 1423 | 1659 | /** |
| 1424 | 1660 | * Makes an encoded list of strings from an array |
| 1425 | | - * @param $a Array |
| 1426 | | - * @param $mode int |
| 1427 | | - * LIST_COMMA - comma separated, no field names |
| 1428 | | - * LIST_AND - ANDed WHERE clause (without the WHERE) |
| 1429 | | - * LIST_OR - ORed WHERE clause (without the WHERE) |
| 1430 | | - * LIST_SET - comma separated with field names, like a SET clause |
| 1431 | | - * LIST_NAMES - comma separated field names |
| | 1661 | + * @param $a Array containing the data |
| | 1662 | + * @param $mode: |
| | 1663 | + * - LIST_COMMA: comma separated, no field names |
| | 1664 | + * - LIST_AND: ANDed WHERE clause (without the WHERE). See |
| | 1665 | + * the documentation for $conds in DatabaseBase::select(). |
| | 1666 | + * - LIST_OR: ORed WHERE clause (without the WHERE) |
| | 1667 | + * - LIST_SET: comma separated with field names, like a SET clause |
| | 1668 | + * - LIST_NAMES: comma separated field names |
| 1432 | 1669 | * |
| 1433 | 1670 | * In LIST_AND or LIST_OR modes, you can suffix a field with an exclamation |
| 1434 | 1671 | * mark to generate a 'NOT IN' structure. |
| | 1672 | + * |
| 1435 | 1673 | * Example: |
| 1436 | 1674 | * $db->makeList( array( 'field!' => array( 1,2,3 ) ); |
| | 1675 | + * |
| 1437 | 1676 | * outputs: |
| 1438 | 1677 | * 'field' NOT IN ('1', '2', '3' ); |
| 1439 | 1678 | |
| — | — | @@ -1510,7 +1749,8 @@ |
| 1511 | 1750 | * Build a partial where clause from a 2-d array such as used for LinkBatch. |
| 1512 | 1751 | * The keys on each level may be either integers or strings. |
| 1513 | 1752 | * |
| 1514 | | - * @param $data Array: organized as 2-d array(baseKeyVal => array(subKeyVal => <ignored>, ...), ...) |
| | 1753 | + * @param $data Array: organized as 2-d |
| | 1754 | + * array(baseKeyVal => array(subKeyVal => <ignored>, ...), ...) |
| 1515 | 1755 | * @param $baseKey String: field name to match the base-level keys to (eg 'pl_namespace') |
| 1516 | 1756 | * @param $subKey String: field name to match the sub-level keys to (eg 'pl_title') |
| 1517 | 1757 | * @return Mixed: string SQL fragment, or false if no items in array. |
| — | — | @@ -2003,24 +2243,31 @@ |
| 2004 | 2244 | } |
| 2005 | 2245 | |
| 2006 | 2246 | /** |
| 2007 | | - * DELETE where the condition is a join |
| 2008 | | - * MySQL overrides this to use a multi-table DELETE syntax, in other databases we use sub-selects |
| | 2247 | + * DELETE where the condition is a join. |
| 2009 | 2248 | * |
| 2010 | | - * For safety, an empty $conds will not delete everything. If you want to delete all rows where the |
| 2011 | | - * join condition matches, set $conds='*' |
| | 2249 | + * MySQL overrides this to use a multi-table DELETE syntax, in other databases |
| | 2250 | + * we use sub-selects |
| 2012 | 2251 | * |
| 2013 | | - * DO NOT put the join condition in $conds |
| | 2252 | + * For safety, an empty $conds will not delete everything. If you want to |
| | 2253 | + * delete all rows where the join condition matches, set $conds='*'. |
| 2014 | 2254 | * |
| 2015 | | - * @param $delTable String: The table to delete from. |
| 2016 | | - * @param $joinTable String: The other table. |
| 2017 | | - * @param $delVar String: The variable to join on, in the first table. |
| 2018 | | - * @param $joinVar String: The variable to join on, in the second table. |
| 2019 | | - * @param $conds Array: Condition array of field names mapped to variables, ANDed together in the WHERE clause |
| 2020 | | - * @param $fname String: Calling function name (use __METHOD__) for logs/profiling |
| | 2255 | + * DO NOT put the join condition in $conds. |
| | 2256 | + * |
| | 2257 | + * @param $delTable String: The table to delete from. |
| | 2258 | + * @param $joinTable String: The other table. |
| | 2259 | + * @param $delVar String: The variable to join on, in the first table. |
| | 2260 | + * @param $joinVar String: The variable to join on, in the second table. |
| | 2261 | + * @param $conds Array: Condition array of field names mapped to variables, |
| | 2262 | + * ANDed together in the WHERE clause |
| | 2263 | + * @param $fname String: Calling function name (use __METHOD__) for |
| | 2264 | + * logs/profiling |
| 2021 | 2265 | */ |
| 2022 | | - function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = 'DatabaseBase::deleteJoin' ) { |
| | 2266 | + function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, |
| | 2267 | + $fname = 'DatabaseBase::deleteJoin' ) |
| | 2268 | + { |
| 2023 | 2269 | if ( !$conds ) { |
| 2024 | | - throw new DBUnexpectedError( $this, 'DatabaseBase::deleteJoin() called with empty $conds' ); |
| | 2270 | + throw new DBUnexpectedError( $this, |
| | 2271 | + 'DatabaseBase::deleteJoin() called with empty $conds' ); |
| 2025 | 2272 | } |
| 2026 | 2273 | |
| 2027 | 2274 | $delTable = $this->tableName( $delTable ); |
| — | — | @@ -2059,16 +2306,21 @@ |
| 2060 | 2307 | * MySQL's LOW_PRIORITY. If no such feature exists, return an empty |
| 2061 | 2308 | * string and nothing bad should happen. |
| 2062 | 2309 | * |
| 2063 | | - * @return string Returns the text of the low priority option if it is supported, or a blank string otherwise |
| | 2310 | + * @return string Returns the text of the low priority option if it is |
| | 2311 | + * supported, or a blank string otherwise |
| 2064 | 2312 | */ |
| 2065 | 2313 | function lowPriorityOption() { |
| 2066 | 2314 | return ''; |
| 2067 | 2315 | } |
| 2068 | 2316 | |
| 2069 | 2317 | /** |
| 2070 | | - * DELETE query wrapper |
| | 2318 | + * DELETE query wrapper. |
| 2071 | 2319 | * |
| 2072 | | - * Use $conds == "*" to delete all rows |
| | 2320 | + * @param $table Table name |
| | 2321 | + * @param $conds Condition array. See $conds in DatabaseBase::select() for |
| | 2322 | + * the format. Use $conds == "*" to delete all rows |
| | 2323 | + * |
| | 2324 | + * @return bool |
| 2073 | 2325 | */ |
| 2074 | 2326 | function delete( $table, $conds, $fname = 'DatabaseBase::delete' ) { |
| 2075 | 2327 | if ( !$conds ) { |
| — | — | @@ -2086,15 +2338,33 @@ |
| 2087 | 2339 | } |
| 2088 | 2340 | |
| 2089 | 2341 | /** |
| 2090 | | - * INSERT SELECT wrapper |
| 2091 | | - * $varMap must be an associative array of the form array( 'dest1' => 'source1', ...) |
| 2092 | | - * Source items may be literals rather than field names, but strings should be quoted with DatabaseBase::addQuotes() |
| 2093 | | - * $conds may be "*" to copy the whole table |
| 2094 | | - * srcTable may be an array of tables. |
| | 2342 | + * INSERT SELECT wrapper. Takes data from a SELECT query and inserts it |
| | 2343 | + * into another table. |
| 2095 | 2344 | * |
| | 2345 | + * @param $destTable The table name to insert into |
| | 2346 | + * @param $srcTable May be either a table name, or an array of table names |
| | 2347 | + * to include in a join. |
| | 2348 | + * |
| | 2349 | + * @param $varMap must be an associative array of the form |
| | 2350 | + * array( 'dest1' => 'source1', ...). Source items may be literals |
| | 2351 | + * rather than field names, but strings should be quoted with |
| | 2352 | + * DatabaseBase::addQuotes() |
| | 2353 | + * |
| | 2354 | + * @param $conds Condition array. See $conds in DatabaseBase::select() for |
| | 2355 | + * the details of the format of condition arrays. May be "*" to copy the |
| | 2356 | + * whole table. |
| | 2357 | + * |
| | 2358 | + * @param $fname The function name of the caller, from __METHOD__ |
| | 2359 | + * |
| | 2360 | + * @param $insertOptions Options for the INSERT part of the query, see |
| | 2361 | + * DatabaseBase::insert() for details. |
| | 2362 | + * @param $selectOptions Options for the SELECT part of the query, see |
| | 2363 | + * DatabaseBase::select() for details. |
| | 2364 | + * |
| 2096 | 2365 | * @return ResultWrapper |
| 2097 | 2366 | */ |
| 2098 | | - function insertSelect( $destTable, $srcTable, $varMap, $conds, $fname = 'DatabaseBase::insertSelect', |
| | 2367 | + function insertSelect( $destTable, $srcTable, $varMap, $conds, |
| | 2368 | + $fname = 'DatabaseBase::insertSelect', |
| 2099 | 2369 | $insertOptions = array(), $selectOptions = array() ) |
| 2100 | 2370 | { |
| 2101 | 2371 | $destTable = $this->tableName( $destTable ); |
| — | — | @@ -2436,8 +2706,11 @@ |
| 2437 | 2707 | * @param $fname String: calling function name |
| 2438 | 2708 | * @return Boolean: true if operation was successful |
| 2439 | 2709 | */ |
| 2440 | | - function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = 'DatabaseBase::duplicateTableStructure' ) { |
| 2441 | | - throw new MWException( 'DatabaseBase::duplicateTableStructure is not implemented in descendant class' ); |
| | 2710 | + function duplicateTableStructure( $oldName, $newName, $temporary = false, |
| | 2711 | + $fname = 'DatabaseBase::duplicateTableStructure' ) |
| | 2712 | + { |
| | 2713 | + throw new MWException( |
| | 2714 | + 'DatabaseBase::duplicateTableStructure is not implemented in descendant class' ); |
| 2442 | 2715 | } |
| 2443 | 2716 | |
| 2444 | 2717 | /** |
| — | — | @@ -2451,8 +2724,12 @@ |
| 2452 | 2725 | } |
| 2453 | 2726 | |
| 2454 | 2727 | /** |
| 2455 | | - * Return MW-style timestamp used for MySQL schema |
| | 2728 | + * Convert a timestamp in one of the formats accepted by wfTimestamp() |
| | 2729 | + * to the format used for inserting into timestamp fields in this DBMS. |
| 2456 | 2730 | * |
| | 2731 | + * The result is unquoted, and needs to be passed through addQuotes() |
| | 2732 | + * before it can be included in raw SQL. |
| | 2733 | + * |
| 2457 | 2734 | * @return string |
| 2458 | 2735 | */ |
| 2459 | 2736 | function timestamp( $ts = 0 ) { |
| — | — | @@ -2460,8 +2737,14 @@ |
| 2461 | 2738 | } |
| 2462 | 2739 | |
| 2463 | 2740 | /** |
| 2464 | | - * Local database timestamp format or null |
| | 2741 | + * Convert a timestamp in one of the formats accepted by wfTimestamp() |
| | 2742 | + * to the format used for inserting into timestamp fields in this DBMS. If |
| | 2743 | + * NULL is input, it is passed through, allowing NULL values to be inserted |
| | 2744 | + * into timestamp fields. |
| 2465 | 2745 | * |
| | 2746 | + * The result is unquoted, and needs to be passed through addQuotes() |
| | 2747 | + * before it can be included in raw SQL. |
| | 2748 | + * |
| 2466 | 2749 | * @return string |
| 2467 | 2750 | */ |
| 2468 | 2751 | function timestampOrNull( $ts = null ) { |
| — | — | @@ -2473,11 +2756,12 @@ |
| 2474 | 2757 | } |
| 2475 | 2758 | |
| 2476 | 2759 | /** |
| 2477 | | - * @todo document |
| 2478 | | - * |
| 2479 | | - * @return ResultWrapper |
| | 2760 | + * Take the result from a query, and wrap it in a ResultWrapper if |
| | 2761 | + * necessary. Boolean values are passed through as is, to indicate success |
| | 2762 | + * of write queries or failure. ResultWrapper objects are also passed |
| | 2763 | + * through. |
| 2480 | 2764 | */ |
| 2481 | | - function resultObject( $result ) { |
| | 2765 | + protected function resultObject( $result ) { |
| 2482 | 2766 | if ( empty( $result ) ) { |
| 2483 | 2767 | return false; |
| 2484 | 2768 | } elseif ( $result instanceof ResultWrapper ) { |
| — | — | @@ -2541,10 +2825,21 @@ |
| 2542 | 2826 | return 0; |
| 2543 | 2827 | } |
| 2544 | 2828 | |
| | 2829 | + /** |
| | 2830 | + * Some DBMSs have a special format for inserting into blob fields, they |
| | 2831 | + * don't allow simple quoted strings to be inserted. To insert into such |
| | 2832 | + * a field, pass the data through this function before passing it to |
| | 2833 | + * DatabaseBase::insert(). |
| | 2834 | + */ |
| 2545 | 2835 | function encodeBlob( $b ) { |
| 2546 | 2836 | return $b; |
| 2547 | 2837 | } |
| 2548 | 2838 | |
| | 2839 | + /** |
| | 2840 | + * Some DBMSs return a special placeholder object representing blob fields |
| | 2841 | + * in result objects. Pass the object through this function to return the |
| | 2842 | + * original string. |
| | 2843 | + */ |
| 2549 | 2844 | function decodeBlob( $b ) { |
| 2550 | 2845 | return $b; |
| 2551 | 2846 | } |
| — | — | @@ -2561,12 +2856,15 @@ |
| 2562 | 2857 | |
| 2563 | 2858 | /** |
| 2564 | 2859 | * Read and execute SQL commands from a file. |
| 2565 | | - * Returns true on success, error string or exception on failure (depending on object's error ignore settings) |
| | 2860 | + * |
| | 2861 | + * Returns true on success, error string or exception on failure (depending |
| | 2862 | + * on object's error ignore settings). |
| | 2863 | + * |
| 2566 | 2864 | * @param $filename String: File name to open |
| 2567 | 2865 | * @param $lineCallback Callback: Optional function called before reading each line |
| 2568 | 2866 | * @param $resultCallback Callback: Optional function called for each MySQL result |
| 2569 | | - * @param $fname String: Calling function name or false if name should be generated dynamically |
| 2570 | | - * using $filename |
| | 2867 | + * @param $fname String: Calling function name or false if name should be |
| | 2868 | + * generated dynamically using $filename |
| 2571 | 2869 | */ |
| 2572 | 2870 | function sourceFile( $filename, $lineCallback = false, $resultCallback = false, $fname = false ) { |
| 2573 | 2871 | wfSuppressWarnings(); |
| — | — | @@ -2625,14 +2923,19 @@ |
| 2626 | 2924 | } |
| 2627 | 2925 | |
| 2628 | 2926 | /** |
| 2629 | | - * Read and execute commands from an open file handle |
| 2630 | | - * Returns true on success, error string or exception on failure (depending on object's error ignore settings) |
| | 2927 | + * Read and execute commands from an open file handle. |
| | 2928 | + * |
| | 2929 | + * Returns true on success, error string or exception on failure (depending |
| | 2930 | + * on object's error ignore settings). |
| | 2931 | + * |
| 2631 | 2932 | * @param $fp Resource: File handle |
| 2632 | 2933 | * @param $lineCallback Callback: Optional function called before reading each line |
| 2633 | 2934 | * @param $resultCallback Callback: Optional function called for each MySQL result |
| 2634 | 2935 | * @param $fname String: Calling function name |
| 2635 | 2936 | */ |
| 2636 | | - function sourceStream( $fp, $lineCallback = false, $resultCallback = false, $fname = 'DatabaseBase::sourceStream' ) { |
| | 2937 | + function sourceStream( $fp, $lineCallback = false, $resultCallback = false, |
| | 2938 | + $fname = 'DatabaseBase::sourceStream' ) |
| | 2939 | + { |
| 2637 | 2940 | $cmd = ""; |
| 2638 | 2941 | $done = false; |
| 2639 | 2942 | $dollarquote = false; |
| — | — | @@ -2699,16 +3002,19 @@ |
| 2700 | 3003 | } |
| 2701 | 3004 | |
| 2702 | 3005 | /** |
| 2703 | | - * Database independent variable replacement, replaces a set of variables |
| 2704 | | - * in a sql statement with their contents as given by $this->getSchemaVars(). |
| 2705 | | - * Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables |
| | 3006 | + * Database independent variable replacement. Replaces a set of variables |
| | 3007 | + * in an SQL statement with their contents as given by $this->getSchemaVars(). |
| 2706 | 3008 | * |
| 2707 | | - * '{$var}' should be used for text and is passed through the database's addQuotes method |
| 2708 | | - * `{$var}` should be used for identifiers (eg: table and database names), it is passed through |
| 2709 | | - * the database's addIdentifierQuotes method which can be overridden if the database |
| 2710 | | - * uses something other than backticks. |
| 2711 | | - * / *$var* / is just encoded, besides traditional dbprefix and tableoptions it's use should be avoided |
| | 3009 | + * Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables. |
| 2712 | 3010 | * |
| | 3011 | + * - '{$var}' should be used for text and is passed through the database's |
| | 3012 | + * addQuotes method. |
| | 3013 | + * - `{$var}` should be used for identifiers (eg: table and database names), |
| | 3014 | + * it is passed through the database's addIdentifierQuotes method which |
| | 3015 | + * can be overridden if the database uses something other than backticks. |
| | 3016 | + * - / *$var* / is just encoded, besides traditional table prefix and |
| | 3017 | + * table options its use should be avoided. |
| | 3018 | + * |
| 2713 | 3019 | * @param $ins String: SQL statement to replace variables in |
| 2714 | 3020 | * @return String The new SQL statement with variables replaced |
| 2715 | 3021 | */ |
| — | — | @@ -2756,6 +3062,7 @@ |
| 2757 | 3063 | |
| 2758 | 3064 | /** |
| 2759 | 3065 | * Get schema variables to use if none have been set via setSchemaVars(). |
| | 3066 | + * |
| 2760 | 3067 | * Override this in derived classes to provide variables for tables.sql |
| 2761 | 3068 | * and SQL patch files. |
| 2762 | 3069 | */ |
| — | — | @@ -2892,7 +3199,8 @@ |
| 2893 | 3200 | * |
| 2894 | 3201 | * This is a MySQL-specific feature. |
| 2895 | 3202 | * |
| 2896 | | - * @param $value Mixed: true for allow, false for deny, or "default" to restore the initial value |
| | 3203 | + * @param $value Mixed: true for allow, false for deny, or "default" to |
| | 3204 | + * restore the initial value |
| 2897 | 3205 | */ |
| 2898 | 3206 | public function setBigSelects( $value = true ) { |
| 2899 | 3207 | // no-op |