Debian Codegraph @

django/db/backends/base/operations.py

raw
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