| 1 |
import datetime |
| 2 |
import decimal |
| 3 |
import json |
| 4 |
import warnings |
| 5 |
from importlib import import_module |
| 6 |
|
| 7 |
import sqlparse |
| 8 |
|
| 9 |
from django.conf import settings |
| 10 |
from django.db import NotSupportedError, transaction |
| 11 |
from django.db.models.expressions import Col |
| 12 |
from django.utils import timezone |
| 13 |
from django.utils.deprecation import RemovedInDjango60Warning |
| 14 |
from django.utils.encoding import force_str |
| 15 |
|
| 16 |
|
| 17 |
class BaseDatabaseOperations: |
| 18 |
""" |
| 19 |
Encapsulate backend-specific differences, such as the way a backend |
| 20 |
performs ordering or calculates the ID of a recently-inserted row. |
| 21 |
""" |
| 22 |
|
| 23 |
compiler_module = "django.db.models.sql.compiler" |
| 24 |
|
| 25 |
# Integer field safe ranges by `internal_type` as documented |
| 26 |
# in docs/ref/models/fields.txt. |
| 27 |
integer_field_ranges = { |
| 28 |
"SmallIntegerField": (-32768, 32767), |
| 29 |
"IntegerField": (-2147483648, 2147483647), |
| 30 |
"BigIntegerField": (-9223372036854775808, 9223372036854775807), |
| 31 |
"PositiveBigIntegerField": (0, 9223372036854775807), |
| 32 |
"PositiveSmallIntegerField": (0, 32767), |
| 33 |
"PositiveIntegerField": (0, 2147483647), |
| 34 |
"SmallAutoField": (-32768, 32767), |
| 35 |
"AutoField": (-2147483648, 2147483647), |
| 36 |
"BigAutoField": (-9223372036854775808, 9223372036854775807), |
| 37 |
} |
| 38 |
set_operators = { |
| 39 |
"union": "UNION", |
| 40 |
"intersection": "INTERSECT", |
| 41 |
"difference": "EXCEPT", |
| 42 |
} |
| 43 |
# Mapping of Field.get_internal_type() (typically the model field's class |
| 44 |
# name) to the data type to use for the Cast() function, if different from |
| 45 |
# DatabaseWrapper.data_types. |
| 46 |
cast_data_types = {} |
| 47 |
# CharField data type if the max_length argument isn't provided. |
| 48 |
cast_char_field_without_max_length = None |
| 49 |
|
| 50 |
# Start and end points for window expressions. |
| 51 |
PRECEDING = "PRECEDING" |
| 52 |
FOLLOWING = "FOLLOWING" |
| 53 |
UNBOUNDED_PRECEDING = "UNBOUNDED " + PRECEDING |
| 54 |
UNBOUNDED_FOLLOWING = "UNBOUNDED " + FOLLOWING |
| 55 |
CURRENT_ROW = "CURRENT ROW" |
| 56 |
|
| 57 |
# Prefix for EXPLAIN queries, or None EXPLAIN isn't supported. |
| 58 |
explain_prefix = None |
| 59 |
|
| 60 |
def __init__(self, connection): |
| 61 |
self.connection = connection |
| 62 |
self._cache = None |
| 63 |
|
| 64 |
def autoinc_sql(self, table, column): |
| 65 |
""" |
| 66 |
Return any SQL needed to support auto-incrementing primary keys, or |
| 67 |
None if no SQL is necessary. |
| 68 |
|
| 69 |
This SQL is executed when a table is created. |
| 70 |
""" |
| 71 |
return None |
| 72 |
|
| 73 |
def bulk_batch_size(self, fields, objs): |
| 74 |
""" |
| 75 |
Return the maximum allowed batch size for the backend. The fields |
| 76 |
are the fields going to be inserted in the batch, the objs contains |
| 77 |
all the objects to be inserted. |
| 78 |
""" |
| 79 |
return len(objs) |
| 80 |
|
| 81 |
def format_for_duration_arithmetic(self, sql): |
| 82 |
raise NotImplementedError( |
| 83 |
"subclasses of BaseDatabaseOperations may require a " |
| 84 |
"format_for_duration_arithmetic() method." |
| 85 |
) |
| 86 |
|
| 87 |
def cache_key_culling_sql(self): |
| 88 |
""" |
| 89 |
Return an SQL query that retrieves the first cache key greater than the |
| 90 |
n smallest. |
| 91 |
|
| 92 |
This is used by the 'db' cache backend to determine where to start |
| 93 |
culling. |
| 94 |
""" |
| 95 |
cache_key = self.quote_name("cache_key") |
| 96 |
return f"SELECT {cache_key} FROM %s ORDER BY {cache_key} LIMIT 1 OFFSET %%s" |
| 97 |
|
| 98 |
def unification_cast_sql(self, output_field): |
| 99 |
""" |
| 100 |
Given a field instance, return the SQL that casts the result of a union |
| 101 |
to that type. The resulting string should contain a '%s' placeholder |
| 102 |
for the expression being cast. |
| 103 |
""" |
| 104 |
return "%s" |
| 105 |
|
| 106 |
def date_extract_sql(self, lookup_type, sql, params): |
| 107 |
""" |
| 108 |
Given a lookup_type of 'year', 'month', or 'day', return the SQL that |
| 109 |
extracts a value from the given date field field_name. |
| 110 |
""" |
| 111 |
raise NotImplementedError( |
| 112 |
"subclasses of BaseDatabaseOperations may require a date_extract_sql() " |
| 113 |
"method" |
| 114 |
) |
| 115 |
|
| 116 |
def date_trunc_sql(self, lookup_type, sql, params, tzname=None): |
| 117 |
""" |
| 118 |
Given a lookup_type of 'year', 'month', or 'day', return the SQL that |
| 119 |
truncates the given date or datetime field field_name to a date object |
| 120 |
with only the given specificity. |
| 121 |
|
| 122 |
If `tzname` is provided, the given value is truncated in a specific |
| 123 |
timezone. |
| 124 |
""" |
| 125 |
raise NotImplementedError( |
| 126 |
"subclasses of BaseDatabaseOperations may require a date_trunc_sql() " |
| 127 |
"method." |
| 128 |
) |
| 129 |
|
| 130 |
def datetime_cast_date_sql(self, sql, params, tzname): |
| 131 |
""" |
| 132 |
Return the SQL to cast a datetime value to date value. |
| 133 |
""" |
| 134 |
raise NotImplementedError( |
| 135 |
"subclasses of BaseDatabaseOperations may require a " |
| 136 |
"datetime_cast_date_sql() method." |
| 137 |
) |
| 138 |
|
| 139 |
def datetime_cast_time_sql(self, sql, params, tzname): |
| 140 |
""" |
| 141 |
Return the SQL to cast a datetime value to time value. |
| 142 |
""" |
| 143 |
raise NotImplementedError( |
| 144 |
"subclasses of BaseDatabaseOperations may require a " |
| 145 |
"datetime_cast_time_sql() method" |
| 146 |
) |
| 147 |
|
| 148 |
def datetime_extract_sql(self, lookup_type, sql, params, tzname): |
| 149 |
""" |
| 150 |
Given a lookup_type of 'year', 'month', 'day', 'hour', 'minute', or |
| 151 |
'second', return the SQL that extracts a value from the given |
| 152 |
datetime field field_name. |
| 153 |
""" |
| 154 |
raise NotImplementedError( |
| 155 |
"subclasses of BaseDatabaseOperations may require a datetime_extract_sql() " |
| 156 |
"method" |
| 157 |
) |
| 158 |
|
| 159 |
def datetime_trunc_sql(self, lookup_type, sql, params, tzname): |
| 160 |
""" |
| 161 |
Given a lookup_type of 'year', 'month', 'day', 'hour', 'minute', or |
| 162 |
'second', return the SQL that truncates the given datetime field |
| 163 |
field_name to a datetime object with only the given specificity. |
| 164 |
""" |
| 165 |
raise NotImplementedError( |
| 166 |
"subclasses of BaseDatabaseOperations may require a datetime_trunc_sql() " |
| 167 |
"method" |
| 168 |
) |
| 169 |
|
| 170 |
def time_trunc_sql(self, lookup_type, sql, params, tzname=None): |
| 171 |
""" |
| 172 |
Given a lookup_type of 'hour', 'minute' or 'second', return the SQL |
| 173 |
that truncates the given time or datetime field field_name to a time |
| 174 |
object with only the given specificity. |
| 175 |
|
| 176 |
If `tzname` is provided, the given value is truncated in a specific |
| 177 |
timezone. |
| 178 |
""" |
| 179 |
raise NotImplementedError( |
| 180 |
"subclasses of BaseDatabaseOperations may require a time_trunc_sql() method" |
| 181 |
) |
| 182 |
|
| 183 |
def time_extract_sql(self, lookup_type, sql, params): |
| 184 |
""" |
| 185 |
Given a lookup_type of 'hour', 'minute', or 'second', return the SQL |
| 186 |
that extracts a value from the given time field field_name. |
| 187 |
""" |
| 188 |
return self.date_extract_sql(lookup_type, sql, params) |
| 189 |
|
| 190 |
def deferrable_sql(self): |
| 191 |
""" |
| 192 |
Return the SQL to make a constraint "initially deferred" during a |
| 193 |
CREATE TABLE statement. |
| 194 |
""" |
| 195 |
return "" |
| 196 |
|
| 197 |
def distinct_sql(self, fields, params): |
| 198 |
""" |
| 199 |
Return an SQL DISTINCT clause which removes duplicate rows from the |
| 200 |
result set. If any fields are given, only check the given fields for |
| 201 |
duplicates. |
| 202 |
""" |
| 203 |
if fields: |
| 204 |
raise NotSupportedError( |
| 205 |
"DISTINCT ON fields is not supported by this database backend" |
| 206 |
) |
| 207 |
else: |
| 208 |
return ["DISTINCT"], [] |
| 209 |
|
| 210 |
def fetch_returned_insert_columns(self, cursor, returning_params): |
| 211 |
""" |
| 212 |
Given a cursor object that has just performed an INSERT...RETURNING |
| 213 |
statement into a table, return the newly created data. |
| 214 |
""" |
| 215 |
return cursor.fetchone() |
| 216 |
|
| 217 |
def field_cast_sql(self, db_type, internal_type): |
| 218 |
""" |
| 219 |
Given a column type (e.g. 'BLOB', 'VARCHAR') and an internal type |
| 220 |
(e.g. 'GenericIPAddressField'), return the SQL to cast it before using |
| 221 |
it in a WHERE statement. The resulting string should contain a '%s' |
| 222 |
placeholder for the column being searched against. |
| 223 |
""" |
| 224 |
warnings.warn( |
| 225 |
( |
| 226 |
"DatabaseOperations.field_cast_sql() is deprecated use " |
| 227 |
"DatabaseOperations.lookup_cast() instead." |
| 228 |
), |
| 229 |
RemovedInDjango60Warning, |
| 230 |
stacklevel=2, |
| 231 |
) |
| 232 |
return "%s" |
| 233 |
|
| 234 |
def force_group_by(self): |
| 235 |
""" |
| 236 |
Return a GROUP BY clause to use with a HAVING clause when no grouping |
| 237 |
is specified. |
| 238 |
""" |
| 239 |
return [] |
| 240 |
|
| 241 |
def force_no_ordering(self): |
| 242 |
""" |
| 243 |
Return a list used in the "ORDER BY" clause to force no ordering at |
| 244 |
all. Return an empty list to include nothing in the ordering. |
| 245 |
""" |
| 246 |
return [] |
| 247 |
|
| 248 |
def for_update_sql(self, nowait=False, skip_locked=False, of=(), no_key=False): |
| 249 |
""" |
| 250 |
Return the FOR UPDATE SQL clause to lock rows for an update operation. |
| 251 |
""" |
| 252 |
return "FOR%s UPDATE%s%s%s" % ( |
| 253 |
" NO KEY" if no_key else "", |
| 254 |
" OF %s" % ", ".join(of) if of else "", |
| 255 |
" NOWAIT" if nowait else "", |
| 256 |
" SKIP LOCKED" if skip_locked else "", |
| 257 |
) |
| 258 |
|
| 259 |
def _get_limit_offset_params(self, low_mark, high_mark): |
| 260 |
offset = low_mark or 0 |
| 261 |
if high_mark is not None: |
| 262 |
return (high_mark - offset), offset |
| 263 |
elif offset: |
| 264 |
return self.connection.ops.no_limit_value(), offset |
| 265 |
return None, offset |
| 266 |
|
| 267 |
def limit_offset_sql(self, low_mark, high_mark): |
| 268 |
"""Return LIMIT/OFFSET SQL clause.""" |
| 269 |
limit, offset = self._get_limit_offset_params(low_mark, high_mark) |
| 270 |
return " ".join( |
| 271 |
sql |
| 272 |
for sql in ( |
| 273 |
("LIMIT %d" % limit) if limit else None, |
| 274 |
("OFFSET %d" % offset) if offset else None, |
| 275 |
) |
| 276 |
if sql |
| 277 |
) |
| 278 |
|
| 279 |
def bulk_insert_sql(self, fields, placeholder_rows): |
| 280 |
placeholder_rows_sql = (", ".join(row) for row in placeholder_rows) |
| 281 |
values_sql = ", ".join([f"({sql})" for sql in placeholder_rows_sql]) |
| 282 |
return f"VALUES {values_sql}" |
| 283 |
|
| 284 |
def last_executed_query(self, cursor, sql, params): |
| 285 |
""" |
| 286 |
Return a string of the query last executed by the given cursor, with |
| 287 |
placeholders replaced with actual values. |
| 288 |
|
| 289 |
`sql` is the raw query containing placeholders and `params` is the |
| 290 |
sequence of parameters. These are used by default, but this method |
| 291 |
exists for database backends to provide a better implementation |
| 292 |
according to their own quoting schemes. |
| 293 |
""" |
| 294 |
|
| 295 |
# Convert params to contain string values. |
| 296 |
def to_string(s): |
| 297 |
return force_str(s, strings_only=True, errors="replace") |
| 298 |
|
| 299 |
if isinstance(params, (list, tuple)): |
| 300 |
u_params = tuple(to_string(val) for val in params) |
| 301 |
elif params is None: |
| 302 |
u_params = () |
| 303 |
else: |
| 304 |
u_params = {to_string(k): to_string(v) for k, v in params.items()} |
| 305 |
|
| 306 |
return "QUERY = %r - PARAMS = %r" % (sql, u_params) |
| 307 |
|
| 308 |
def last_insert_id(self, cursor, table_name, pk_name): |
| 309 |
""" |
| 310 |
Given a cursor object that has just performed an INSERT statement into |
| 311 |
a table that has an auto-incrementing ID, return the newly created ID. |
| 312 |
|
| 313 |
`pk_name` is the name of the primary-key column. |
| 314 |
""" |
| 315 |
return cursor.lastrowid |
| 316 |
|
| 317 |
def lookup_cast(self, lookup_type, internal_type=None): |
| 318 |
""" |
| 319 |
Return the string to use in a query when performing lookups |
| 320 |
("contains", "like", etc.). It should contain a '%s' placeholder for |
| 321 |
the column being searched against. |
| 322 |
""" |
| 323 |
return "%s" |
| 324 |
|
| 325 |
def max_in_list_size(self): |
| 326 |
""" |
| 327 |
Return the maximum number of items that can be passed in a single 'IN' |
| 328 |
list condition, or None if the backend does not impose a limit. |
| 329 |
""" |
| 330 |
return None |
| 331 |
|
| 332 |
def max_name_length(self): |
| 333 |
""" |
| 334 |
Return the maximum length of table and column names, or None if there |
| 335 |
is no limit. |
| 336 |
""" |
| 337 |
return None |
| 338 |
|
| 339 |
def no_limit_value(self): |
| 340 |
""" |
| 341 |
Return the value to use for the LIMIT when we are wanting "LIMIT |
| 342 |
infinity". Return None if the limit clause can be omitted in this case. |
| 343 |
""" |
| 344 |
raise NotImplementedError( |
| 345 |
"subclasses of BaseDatabaseOperations may require a no_limit_value() method" |
| 346 |
) |
| 347 |
|
| 348 |
def pk_default_value(self): |
| 349 |
""" |
| 350 |
Return the value to use during an INSERT statement to specify that |
| 351 |
the field should use its default value. |
| 352 |
""" |
| 353 |
return "DEFAULT" |
| 354 |
|
| 355 |
def prepare_sql_script(self, sql): |
| 356 |
""" |
| 357 |
Take an SQL script that may contain multiple lines and return a list |
| 358 |
of statements to feed to successive cursor.execute() calls. |
| 359 |
|
| 360 |
Since few databases are able to process raw SQL scripts in a single |
| 361 |
cursor.execute() call and PEP 249 doesn't talk about this use case, |
| 362 |
the default implementation is conservative. |
| 363 |
""" |
| 364 |
return [ |
| 365 |
sqlparse.format(statement, strip_comments=True) |
| 366 |
for statement in sqlparse.split(sql) |
| 367 |
if statement |
| 368 |
] |
| 369 |
|
| 370 |
def process_clob(self, value): |
| 371 |
""" |
| 372 |
Return the value of a CLOB column, for backends that return a locator |
| 373 |
object that requires additional processing. |
| 374 |
""" |
| 375 |
return value |
| 376 |
|
| 377 |
def return_insert_columns(self, fields): |
| 378 |
""" |
| 379 |
For backends that support returning columns as part of an insert query, |
| 380 |
return the SQL and params to append to the INSERT query. The returned |
| 381 |
fragment should contain a format string to hold the appropriate column. |
| 382 |
""" |
| 383 |
pass |
| 384 |
|
| 385 |
def compiler(self, compiler_name): |
| 386 |
""" |
| 387 |
Return the SQLCompiler class corresponding to the given name, |
| 388 |
in the namespace corresponding to the `compiler_module` attribute |
| 389 |
on this backend. |
| 390 |
""" |
| 391 |
if self._cache is None: |
| 392 |
self._cache = import_module(self.compiler_module) |
| 393 |
return getattr(self._cache, compiler_name) |
| 394 |
|
| 395 |
def quote_name(self, name): |
| 396 |
""" |
| 397 |
Return a quoted version of the given table, index, or column name. Do |
| 398 |
not quote the given name if it's already been quoted. |
| 399 |
""" |
| 400 |
raise NotImplementedError( |
| 401 |
"subclasses of BaseDatabaseOperations may require a quote_name() method" |
| 402 |
) |
| 403 |
|
| 404 |
def regex_lookup(self, lookup_type): |
| 405 |
""" |
| 406 |
Return the string to use in a query when performing regular expression |
| 407 |
lookups (using "regex" or "iregex"). It should contain a '%s' |
| 408 |
placeholder for the column being searched against. |
| 409 |
|
| 410 |
If the feature is not supported (or part of it is not supported), raise |
| 411 |
NotImplementedError. |
| 412 |
""" |
| 413 |
raise NotImplementedError( |
| 414 |
"subclasses of BaseDatabaseOperations may require a regex_lookup() method" |
| 415 |
) |
| 416 |
|
| 417 |
def savepoint_create_sql(self, sid): |
| 418 |
""" |
| 419 |
Return the SQL for starting a new savepoint. Only required if the |
| 420 |
"uses_savepoints" feature is True. The "sid" parameter is a string |
| 421 |
for the savepoint id. |
| 422 |
""" |
| 423 |
return "SAVEPOINT %s" % self.quote_name(sid) |
| 424 |
|
| 425 |
def savepoint_commit_sql(self, sid): |
| 426 |
""" |
| 427 |
Return the SQL for committing the given savepoint. |
| 428 |
""" |
| 429 |
return "RELEASE SAVEPOINT %s" % self.quote_name(sid) |
| 430 |
|
| 431 |
def savepoint_rollback_sql(self, sid): |
| 432 |
""" |
| 433 |
Return the SQL for rolling back the given savepoint. |
| 434 |
""" |
| 435 |
return "ROLLBACK TO SAVEPOINT %s" % self.quote_name(sid) |
| 436 |
|
| 437 |
def set_time_zone_sql(self): |
| 438 |
""" |
| 439 |
Return the SQL that will set the connection's time zone. |
| 440 |
|
| 441 |
Return '' if the backend doesn't support time zones. |
| 442 |
""" |
| 443 |
return "" |
| 444 |
|
| 445 |
def sql_flush(self, style, tables, *, reset_sequences=False, allow_cascade=False): |
| 446 |
""" |
| 447 |
Return a list of SQL statements required to remove all data from |
| 448 |
the given database tables (without actually removing the tables |
| 449 |
themselves). |
| 450 |
|
| 451 |
The `style` argument is a Style object as returned by either |
| 452 |
color_style() or no_style() in django.core.management.color. |
| 453 |
|
| 454 |
If `reset_sequences` is True, the list includes SQL statements required |
| 455 |
to reset the sequences. |
| 456 |
|
| 457 |
The `allow_cascade` argument determines whether truncation may cascade |
| 458 |
to tables with foreign keys pointing the tables being truncated. |
| 459 |
PostgreSQL requires a cascade even if these tables are empty. |
| 460 |
""" |
| 461 |
raise NotImplementedError( |
| 462 |
"subclasses of BaseDatabaseOperations must provide an sql_flush() method" |
| 463 |
) |
| 464 |
|
| 465 |
def execute_sql_flush(self, sql_list): |
| 466 |
"""Execute a list of SQL statements to flush the database.""" |
| 467 |
with transaction.atomic( |
| 468 |
using=self.connection.alias, |
| 469 |
savepoint=self.connection.features.can_rollback_ddl, |
| 470 |
): |
| 471 |
with self.connection.cursor() as cursor: |
| 472 |
for sql in sql_list: |
| 473 |
cursor.execute(sql) |
| 474 |
|
| 475 |
def sequence_reset_by_name_sql(self, style, sequences): |
| 476 |
""" |
| 477 |
Return a list of the SQL statements required to reset sequences |
| 478 |
passed in `sequences`. |
| 479 |
|
| 480 |
The `style` argument is a Style object as returned by either |
| 481 |
color_style() or no_style() in django.core.management.color. |
| 482 |
""" |
| 483 |
return [] |
| 484 |
|
| 485 |
def sequence_reset_sql(self, style, model_list): |
| 486 |
""" |
| 487 |
Return a list of the SQL statements required to reset sequences for |
| 488 |
the given models. |
| 489 |
|
| 490 |
The `style` argument is a Style object as returned by either |
| 491 |
color_style() or no_style() in django.core.management.color. |
| 492 |
""" |
| 493 |
return [] # No sequence reset required by default. |
| 494 |
|
| 495 |
def start_transaction_sql(self): |
| 496 |
"""Return the SQL statement required to start a transaction.""" |
| 497 |
return "BEGIN;" |
| 498 |
|
| 499 |
def end_transaction_sql(self, success=True): |
| 500 |
"""Return the SQL statement required to end a transaction.""" |
| 501 |
if not success: |
| 502 |
return "ROLLBACK;" |
| 503 |
return "COMMIT;" |
| 504 |
|
| 505 |
def tablespace_sql(self, tablespace, inline=False): |
| 506 |
""" |
| 507 |
Return the SQL that will be used in a query to define the tablespace. |
| 508 |
|
| 509 |
Return '' if the backend doesn't support tablespaces. |
| 510 |
|
| 511 |
If `inline` is True, append the SQL to a row; otherwise append it to |
| 512 |
the entire CREATE TABLE or CREATE INDEX statement. |
| 513 |
""" |
| 514 |
return "" |
| 515 |
|
| 516 |
def prep_for_like_query(self, x): |
| 517 |
"""Prepare a value for use in a LIKE query.""" |
| 518 |
return str(x).replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_") |
| 519 |
|
| 520 |
# Same as prep_for_like_query(), but called for "iexact" matches, which |
| 521 |
# need not necessarily be implemented using "LIKE" in the backend. |
| 522 |
prep_for_iexact_query = prep_for_like_query |
| 523 |
|
| 524 |
def validate_autopk_value(self, value): |
| 525 |
""" |
| 526 |
Certain backends do not accept some values for "serial" fields |
| 527 |
(for example zero in MySQL). Raise a ValueError if the value is |
| 528 |
invalid, otherwise return the validated value. |
| 529 |
""" |
| 530 |
return value |
| 531 |
|
| 532 |
def adapt_unknown_value(self, value): |
| 533 |
""" |
| 534 |
Transform a value to something compatible with the backend driver. |
| 535 |
|
| 536 |
This method only depends on the type of the value. It's designed for |
| 537 |
cases where the target type isn't known, such as .raw() SQL queries. |
| 538 |
As a consequence it may not work perfectly in all circumstances. |
| 539 |
""" |
| 540 |
if isinstance(value, datetime.datetime): # must be before date |
| 541 |
return self.adapt_datetimefield_value(value) |
| 542 |
elif isinstance(value, datetime.date): |
| 543 |
return self.adapt_datefield_value(value) |
| 544 |
elif isinstance(value, datetime.time): |
| 545 |
return self.adapt_timefield_value(value) |
| 546 |
elif isinstance(value, decimal.Decimal): |
| 547 |
return self.adapt_decimalfield_value(value) |
| 548 |
else: |
| 549 |
return value |
| 550 |
|
| 551 |
def adapt_integerfield_value(self, value, internal_type): |
| 552 |
return value |
| 553 |
|
| 554 |
def adapt_datefield_value(self, value): |
| 555 |
""" |
| 556 |
Transform a date value to an object compatible with what is expected |
| 557 |
by the backend driver for date columns. |
| 558 |
""" |
| 559 |
if value is None: |
| 560 |
return None |
| 561 |
return str(value) |
| 562 |
|
| 563 |
def adapt_datetimefield_value(self, value): |
| 564 |
""" |
| 565 |
Transform a datetime value to an object compatible with what is expected |
| 566 |
by the backend driver for datetime columns. |
| 567 |
""" |
| 568 |
if value is None: |
| 569 |
return None |
| 570 |
return str(value) |
| 571 |
|
| 572 |
def adapt_timefield_value(self, value): |
| 573 |
""" |
| 574 |
Transform a time value to an object compatible with what is expected |
| 575 |
by the backend driver for time columns. |
| 576 |
""" |
| 577 |
if value is None: |
| 578 |
return None |
| 579 |
if timezone.is_aware(value): |
| 580 |
raise ValueError("Django does not support timezone-aware times.") |
| 581 |
return str(value) |
| 582 |
|
| 583 |
def adapt_decimalfield_value(self, value, max_digits=None, decimal_places=None): |
| 584 |
""" |
| 585 |
Transform a decimal.Decimal value to an object compatible with what is |
| 586 |
expected by the backend driver for decimal (numeric) columns. |
| 587 |
""" |
| 588 |
return value |
| 589 |
|
| 590 |
def adapt_ipaddressfield_value(self, value): |
| 591 |
""" |
| 592 |
Transform a string representation of an IP address into the expected |
| 593 |
type for the backend driver. |
| 594 |
""" |
| 595 |
return value or None |
| 596 |
|
| 597 |
def adapt_json_value(self, value, encoder): |
| 598 |
return json.dumps(value, cls=encoder) |
| 599 |
|
| 600 |
def year_lookup_bounds_for_date_field(self, value, iso_year=False): |
| 601 |
""" |
| 602 |
Return a two-elements list with the lower and upper bound to be used |
| 603 |
with a BETWEEN operator to query a DateField value using a year |
| 604 |
lookup. |
| 605 |
|
| 606 |
`value` is an int, containing the looked-up year. |
| 607 |
If `iso_year` is True, return bounds for ISO-8601 week-numbering years. |
| 608 |
""" |
| 609 |
if iso_year: |
| 610 |
first = datetime.date.fromisocalendar(value, 1, 1) |
| 611 |
second = datetime.date.fromisocalendar( |
| 612 |
value + 1, 1, 1 |
| 613 |
) - datetime.timedelta(days=1) |
| 614 |
else: |
| 615 |
first = datetime.date(value, 1, 1) |
| 616 |
second = datetime.date(value, 12, 31) |
| 617 |
first = self.adapt_datefield_value(first) |
| 618 |
second = self.adapt_datefield_value(second) |
| 619 |
return [first, second] |
| 620 |
|
| 621 |
def year_lookup_bounds_for_datetime_field(self, value, iso_year=False): |
| 622 |
""" |
| 623 |
Return a two-elements list with the lower and upper bound to be used |
| 624 |
with a BETWEEN operator to query a DateTimeField value using a year |
| 625 |
lookup. |
| 626 |
|
| 627 |
`value` is an int, containing the looked-up year. |
| 628 |
If `iso_year` is True, return bounds for ISO-8601 week-numbering years. |
| 629 |
""" |
| 630 |
if iso_year: |
| 631 |
first = datetime.datetime.fromisocalendar(value, 1, 1) |
| 632 |
second = datetime.datetime.fromisocalendar( |
| 633 |
value + 1, 1, 1 |
| 634 |
) - datetime.timedelta(microseconds=1) |
| 635 |
else: |
| 636 |
first = datetime.datetime(value, 1, 1) |
| 637 |
second = datetime.datetime(value, 12, 31, 23, 59, 59, 999999) |
| 638 |
if settings.USE_TZ: |
| 639 |
tz = timezone.get_current_timezone() |
| 640 |
first = timezone.make_aware(first, tz) |
| 641 |
second = timezone.make_aware(second, tz) |
| 642 |
first = self.adapt_datetimefield_value(first) |
| 643 |
second = self.adapt_datetimefield_value(second) |
| 644 |
return [first, second] |
| 645 |
|
| 646 |
def get_db_converters(self, expression): |
| 647 |
""" |
| 648 |
Return a list of functions needed to convert field data. |
| 649 |
|
| 650 |
Some field types on some backends do not provide data in the correct |
| 651 |
format, this is the hook for converter functions. |
| 652 |
""" |
| 653 |
return [] |
| 654 |
|
| 655 |
def convert_durationfield_value(self, value, expression, connection): |
| 656 |
if value is not None: |
| 657 |
return datetime.timedelta(0, 0, value) |
| 658 |
|
| 659 |
def check_expression_support(self, expression): |
| 660 |
""" |
| 661 |
Check that the backend supports the provided expression. |
| 662 |
|
| 663 |
This is used on specific backends to rule out known expressions |
| 664 |
that have problematic or nonexistent implementations. If the |
| 665 |
expression has a known problem, the backend should raise |
| 666 |
NotSupportedError. |
| 667 |
""" |
| 668 |
pass |
| 669 |
|
| 670 |
def conditional_expression_supported_in_where_clause(self, expression): |
| 671 |
""" |
| 672 |
Return True, if the conditional expression is supported in the WHERE |
| 673 |
clause. |
| 674 |
""" |
| 675 |
return True |
| 676 |
|
| 677 |
def combine_expression(self, connector, sub_expressions): |
| 678 |
""" |
| 679 |
Combine a list of subexpressions into a single expression, using |
| 680 |
the provided connecting operator. This is required because operators |
| 681 |
can vary between backends (e.g., Oracle with %% and &) and between |
| 682 |
subexpression types (e.g., date expressions). |
| 683 |
""" |
| 684 |
conn = " %s " % connector |
| 685 |
return conn.join(sub_expressions) |
| 686 |
|
| 687 |
def combine_duration_expression(self, connector, sub_expressions): |
| 688 |
return self.combine_expression(connector, sub_expressions) |
| 689 |
|
| 690 |
def binary_placeholder_sql(self, value): |
| 691 |
""" |
| 692 |
Some backends require special syntax to insert binary content (MySQL |
| 693 |
for example uses '_binary %s'). |
| 694 |
""" |
| 695 |
return "%s" |
| 696 |
|
| 697 |
def modify_insert_params(self, placeholder, params): |
| 698 |
""" |
| 699 |
Allow modification of insert parameters. Needed for Oracle Spatial |
| 700 |
backend due to #10888. |
| 701 |
""" |
| 702 |
return params |
| 703 |
|
| 704 |
def integer_field_range(self, internal_type): |
| 705 |
""" |
| 706 |
Given an integer field internal type (e.g. 'PositiveIntegerField'), |
| 707 |
return a tuple of the (min_value, max_value) form representing the |
| 708 |
range of the column type bound to the field. |
| 709 |
""" |
| 710 |
return self.integer_field_ranges[internal_type] |
| 711 |
|
| 712 |
def subtract_temporals(self, internal_type, lhs, rhs): |
| 713 |
if self.connection.features.supports_temporal_subtraction: |
| 714 |
lhs_sql, lhs_params = lhs |
| 715 |
rhs_sql, rhs_params = rhs |
| 716 |
return "(%s - %s)" % (lhs_sql, rhs_sql), (*lhs_params, *rhs_params) |
| 717 |
raise NotSupportedError( |
| 718 |
"This backend does not support %s subtraction." % internal_type |
| 719 |
) |
| 720 |
|
| 721 |
def window_frame_value(self, value): |
| 722 |
if isinstance(value, int): |
| 723 |
if value == 0: |
| 724 |
return self.CURRENT_ROW |
| 725 |
elif value < 0: |
| 726 |
return "%d %s" % (abs(value), self.PRECEDING) |
| 727 |
else: |
| 728 |
return "%d %s" % (value, self.FOLLOWING) |
| 729 |
|
| 730 |
def window_frame_rows_start_end(self, start=None, end=None): |
| 731 |
""" |
| 732 |
Return SQL for start and end points in an OVER clause window frame. |
| 733 |
""" |
| 734 |
if isinstance(start, int) and isinstance(end, int) and start > end: |
| 735 |
raise ValueError("start cannot be greater than end.") |
| 736 |
if start is not None and not isinstance(start, int): |
| 737 |
raise ValueError( |
| 738 |
f"start argument must be an integer, zero, or None, but got '{start}'." |
| 739 |
) |
| 740 |
if end is not None and not isinstance(end, int): |
| 741 |
raise ValueError( |
| 742 |
f"end argument must be an integer, zero, or None, but got '{end}'." |
| 743 |
) |
| 744 |
start_ = self.window_frame_value(start) or self.UNBOUNDED_PRECEDING |
| 745 |
end_ = self.window_frame_value(end) or self.UNBOUNDED_FOLLOWING |
| 746 |
return start_, end_ |
| 747 |
|
| 748 |
def window_frame_range_start_end(self, start=None, end=None): |
| 749 |
if (start is not None and not isinstance(start, int)) or ( |
| 750 |
isinstance(start, int) and start > 0 |
| 751 |
): |
| 752 |
raise ValueError( |
| 753 |
"start argument must be a negative integer, zero, or None, " |
| 754 |
"but got '%s'." % start |
| 755 |
) |
| 756 |
if (end is not None and not isinstance(end, int)) or ( |
| 757 |
isinstance(end, int) and end < 0 |
| 758 |
): |
| 759 |
raise ValueError( |
| 760 |
"end argument must be a positive integer, zero, or None, but got '%s'." |
| 761 |
% end |
| 762 |
) |
| 763 |
start_ = self.window_frame_value(start) or self.UNBOUNDED_PRECEDING |
| 764 |
end_ = self.window_frame_value(end) or self.UNBOUNDED_FOLLOWING |
| 765 |
features = self.connection.features |
| 766 |
if features.only_supports_unbounded_with_preceding_and_following and ( |
| 767 |
(start and start < 0) or (end and end > 0) |
| 768 |
): |
| 769 |
raise NotSupportedError( |
| 770 |
"%s only supports UNBOUNDED together with PRECEDING and " |
| 771 |
"FOLLOWING." % self.connection.display_name |
| 772 |
) |
| 773 |
return start_, end_ |
| 774 |
|
| 775 |
def explain_query_prefix(self, format=None, **options): |
| 776 |
if not self.connection.features.supports_explaining_query_execution: |
| 777 |
raise NotSupportedError( |
| 778 |
"This backend does not support explaining query execution." |
| 779 |
) |
| 780 |
if format: |
| 781 |
supported_formats = self.connection.features.supported_explain_formats |
| 782 |
normalized_format = format.upper() |
| 783 |
if normalized_format not in supported_formats: |
| 784 |
msg = "%s is not a recognized format." % normalized_format |
| 785 |
if supported_formats: |
| 786 |
msg += " Allowed formats: %s" % ", ".join(sorted(supported_formats)) |
| 787 |
else: |
| 788 |
msg += ( |
| 789 |
f" {self.connection.display_name} does not support any formats." |
| 790 |
) |
| 791 |
raise ValueError(msg) |
| 792 |
if options: |
| 793 |
raise ValueError("Unknown options: %s" % ", ".join(sorted(options.keys()))) |
| 794 |
return self.explain_prefix |
| 795 |
|
| 796 |
def insert_statement(self, on_conflict=None): |
| 797 |
return "INSERT INTO" |
| 798 |
|
| 799 |
def on_conflict_suffix_sql(self, fields, on_conflict, update_fields, unique_fields): |
| 800 |
return "" |
| 801 |
|
| 802 |
def prepare_join_on_clause(self, lhs_table, lhs_field, rhs_table, rhs_field): |
| 803 |
lhs_expr = Col(lhs_table, lhs_field) |
| 804 |
rhs_expr = Col(rhs_table, rhs_field) |
| 805 |
|
| 806 |
return lhs_expr, rhs_expr |