dex-connector-microsoft-sql-server 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1039 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """SQL Server Query and Mutation invocation and native-driver classification."""
4
+
5
+ import asyncio
6
+ import base64
7
+ import json
8
+ import math
9
+ import re
10
+ import socket
11
+ import ssl
12
+ import struct
13
+ import threading
14
+ import time as clock_time
15
+ import unicodedata
16
+ import uuid
17
+ from datetime import UTC, date, datetime, time
18
+ from decimal import Decimal, localcontext
19
+ from typing import Any
20
+
21
+ from dex_connectors.sdk import (
22
+ Call,
23
+ CallID,
24
+ Failure,
25
+ FailureKind,
26
+ IdempotencyKey,
27
+ MutationAttempt,
28
+ MutationDefinition,
29
+ QueryAttempt,
30
+ QueryDefinition,
31
+ ReauthorizationRequiredError,
32
+ Receipt,
33
+ )
34
+ from OpenSSL import SSL
35
+ from pytds import tds_base # type: ignore[import-untyped]
36
+
37
+ from ._generated.definitions import (
38
+ COMPLETED,
39
+ CONNECTOR_ID,
40
+ DEFECT,
41
+ EXECUTE_DEFINITION,
42
+ EXECUTE_OPERATION_ID,
43
+ INVALID_RESPONSE,
44
+ LIMIT_EXCEEDED,
45
+ PROVIDER_REJECTED,
46
+ QUERY_DEFINITION,
47
+ QUERY_OPERATION_ID,
48
+ TRUNCATED,
49
+ )
50
+ from .models import Column, ExecuteStatementInput, QueryRowsInput, RowSet, StatementExecution
51
+
52
+ _RETRY_CONFLICT = {1205, 1222, 3960, 3961}
53
+ _RETRY_AVAILABILITY = {
54
+ 615,
55
+ 701,
56
+ 926,
57
+ 1101,
58
+ 1105,
59
+ 4221,
60
+ 6005,
61
+ 8628,
62
+ 8645,
63
+ 8651,
64
+ 9002,
65
+ 10922,
66
+ 10928,
67
+ 10929,
68
+ 10936,
69
+ 18401,
70
+ 40197,
71
+ 40501,
72
+ 40613,
73
+ 49918,
74
+ 49919,
75
+ 49920,
76
+ }
77
+ _AUTHENTICATION = {18452, 18456, 18470, 18486, 18487, 18488, 40532, 40615}
78
+ _AUTHORIZATION = {229, 230, 262, 297, 916, 3906}
79
+ _NOT_FOUND = {207, 208, 2812, 4060, 4064, 4104}
80
+ _CONFLICT = {515, 547, 2601, 2627, 3902, 3903}
81
+ _VALIDATION = {102, 137, 156, 241, 242, 245, 266, 334, 574, 2628, 8003, 8114, 8115, 8134, 8152}
82
+ _SESSION_LIMIT = {40549, 40550, 40551, 40552, 40553}
83
+ _COMMIT_ROLLED_BACK = {1205, 3902, 3903}
84
+ _DENIED_WORDS = {
85
+ "BEGIN",
86
+ "COMMIT",
87
+ "ROLLBACK",
88
+ "SAVE",
89
+ "TRAN",
90
+ "TRANSACTION",
91
+ "DISTRIBUTED",
92
+ "EXEC",
93
+ "EXECUTE",
94
+ "USE",
95
+ "SETUSER",
96
+ "REVERT",
97
+ "IF",
98
+ "WHILE",
99
+ "GOTO",
100
+ "RETURN",
101
+ "BREAK",
102
+ "CONTINUE",
103
+ "WAITFOR",
104
+ "DECLARE",
105
+ "DEALLOCATE",
106
+ "CREATE",
107
+ "ALTER",
108
+ "DROP",
109
+ "TRUNCATE",
110
+ "GRANT",
111
+ "DENY",
112
+ "REVOKE",
113
+ "TRIGGER",
114
+ "STATISTICS",
115
+ "BACKUP",
116
+ "RESTORE",
117
+ "DBCC",
118
+ "KILL",
119
+ "SHUTDOWN",
120
+ "RECONFIGURE",
121
+ "CHECKPOINT",
122
+ "LOAD",
123
+ "DUMP",
124
+ "BULK",
125
+ "OPENROWSET",
126
+ "OPENDATASOURCE",
127
+ "OPENQUERY",
128
+ "ROWCOUNT",
129
+ "TEXTSIZE",
130
+ "IDENTITY_INSERT",
131
+ "PRINT",
132
+ "RAISERROR",
133
+ "READTEXT",
134
+ "WRITETEXT",
135
+ "UPDATETEXT",
136
+ }
137
+ _POSITIONAL = re.compile(r"@p([1-9][0-9]*)\Z")
138
+ _SQL_TYPES = {
139
+ 48: "TINYINT",
140
+ 52: "SMALLINT",
141
+ 56: "INT",
142
+ 127: "BIGINT",
143
+ 50: "BIT",
144
+ 59: "REAL",
145
+ 62: "FLOAT",
146
+ 106: "DECIMAL",
147
+ 108: "DECIMAL",
148
+ 60: "MONEY",
149
+ 122: "SMALLMONEY",
150
+ 39: "VARCHAR",
151
+ 47: "CHAR",
152
+ 167: "VARCHAR",
153
+ 175: "CHAR",
154
+ 231: "NVARCHAR",
155
+ 239: "NCHAR",
156
+ 35: "TEXT",
157
+ 99: "NTEXT",
158
+ 241: "XML",
159
+ 37: "VARBINARY",
160
+ 45: "BINARY",
161
+ 165: "VARBINARY",
162
+ 173: "BINARY",
163
+ 34: "IMAGE",
164
+ 36: "UNIQUEIDENTIFIER",
165
+ 40: "DATE",
166
+ 41: "TIME",
167
+ 42: "DATETIME2",
168
+ 43: "DATETIMEOFFSET",
169
+ 58: "SMALLDATETIME",
170
+ 61: "DATETIME",
171
+ 98: "SQL_VARIANT",
172
+ }
173
+
174
+
175
+ class _InvalidResponse(Exception):
176
+ pass
177
+
178
+
179
+ class _ReadBudgetExceeded(Exception):
180
+ pass
181
+
182
+
183
+ class _CommitNotSent(Exception):
184
+ pass
185
+
186
+
187
+ class _ReadBudgetTransport:
188
+ def __init__(self, transport: Any, byte_limit: int) -> None:
189
+ self.transport = transport
190
+ self.byte_limit = byte_limit
191
+ self.bytes_read = 0
192
+ self.is_poisoned = False
193
+
194
+ def recv_into(self, buffer: Any, length: int = 0) -> int:
195
+ if self.is_poisoned:
196
+ raise _ReadBudgetExceeded("SQL Server reply exceeded the read budget")
197
+ received = int(self.transport.recv_into(buffer, length))
198
+ self.bytes_read += received
199
+ if self.bytes_read > self.byte_limit:
200
+ self.is_poisoned = True
201
+ raise _ReadBudgetExceeded("SQL Server reply exceeded the read budget")
202
+ return received
203
+
204
+ def set_control_budget(self) -> None:
205
+ self.byte_limit = 4 << 20
206
+ self.bytes_read = 0
207
+
208
+ def __getattr__(self, name: str) -> Any:
209
+ return getattr(self.transport, name)
210
+
211
+
212
+ class _CommitWriteTransport:
213
+ def __init__(self, transport: Any) -> None:
214
+ self.transport = transport
215
+ self.bytes_sent = 0
216
+ self.has_unobservable_write = False
217
+
218
+ def sendall(self, data: Any, flags: int = 0) -> None:
219
+ if not callable(getattr(self.transport, "send", None)):
220
+ self.has_unobservable_write = True
221
+ self.transport.sendall(data, flags)
222
+ return
223
+ data_view = memoryview(data)
224
+ offset = 0
225
+ while offset < len(data_view):
226
+ sent = self.transport.send(data_view[offset:], flags)
227
+ if sent <= 0:
228
+ raise ConnectionError("SQL Server socket closed before COMMIT was sent")
229
+ self.bytes_sent += sent
230
+ offset += sent
231
+
232
+ def __getattr__(self, name: str) -> Any:
233
+ return getattr(self.transport, name)
234
+
235
+
236
+ class _AttemptDeadline:
237
+ def __init__(self, seconds: float) -> None:
238
+ self.expires_at = clock_time.monotonic() + seconds
239
+ self.connection: Any = None
240
+ self.sockets: list[socket.socket] = []
241
+ self.lock = threading.Lock()
242
+ self.expired = threading.Event()
243
+ self.timer = threading.Timer(seconds, self._expire)
244
+ self.timer.daemon = True
245
+ self.timer.start()
246
+
247
+ def _expire(self) -> None:
248
+ with self.lock:
249
+ self.expired.set()
250
+ sockets = tuple(self.sockets)
251
+ connection = self.connection
252
+ for connected_socket in sockets:
253
+ self._shutdown_socket(connected_socket)
254
+ if connection is not None:
255
+ self._shutdown_connection(connection)
256
+
257
+ @staticmethod
258
+ def _shutdown_socket(connected_socket: Any) -> None:
259
+ try:
260
+ connected_socket.shutdown(socket.SHUT_RDWR)
261
+ except (AttributeError, OSError):
262
+ pass
263
+
264
+ def _shutdown_connection(self, connection: Any) -> None:
265
+ tds_socket = getattr(connection, "_tds_socket", None)
266
+ encrypted_socket = getattr(tds_socket, "sock", None)
267
+ raw_socket = getattr(encrypted_socket, "_transport", encrypted_socket)
268
+ if raw_socket is not None:
269
+ self._shutdown_socket(raw_socket)
270
+
271
+ def attach_socket(self, connected_socket: socket.socket) -> None:
272
+ with self.lock:
273
+ self.sockets.append(connected_socket)
274
+ has_expired = self.expired.is_set()
275
+ if has_expired:
276
+ self._shutdown_socket(connected_socket)
277
+ self.check()
278
+
279
+ def attach_connection(self, connection: Any) -> None:
280
+ with self.lock:
281
+ self.connection = connection
282
+ has_expired = self.expired.is_set()
283
+ if has_expired:
284
+ self._shutdown_connection(connection)
285
+ self.check()
286
+
287
+ def check(self) -> None:
288
+ if self.expired.is_set():
289
+ raise TimeoutError("SQL Server attempt exceeded its deadline")
290
+
291
+ def remaining_seconds(self) -> float:
292
+ self.check()
293
+ remaining = self.expires_at - clock_time.monotonic()
294
+ if remaining <= 0:
295
+ raise TimeoutError("SQL Server attempt exceeded its deadline")
296
+ return remaining
297
+
298
+ def close(self) -> None:
299
+ self.timer.cancel()
300
+
301
+
302
+ def _is_sql_letter(character: str) -> bool:
303
+ return unicodedata.category(character).startswith("L")
304
+
305
+
306
+ def _is_sql_digit(character: str) -> bool:
307
+ return unicodedata.category(character) == "Nd"
308
+
309
+
310
+ def _is_sql_identifier_character(character: str) -> bool:
311
+ return _is_sql_letter(character) or _is_sql_digit(character) or character in "_#$@"
312
+
313
+
314
+ def _scan_sql(statement: str) -> list[tuple[str, str, int, int]]:
315
+ tokens: list[tuple[str, str, int, int]] = []
316
+ offset = 0
317
+ while offset < len(statement):
318
+ start = offset
319
+ character = statement[offset]
320
+ if character.isspace():
321
+ offset += 1
322
+ elif statement.startswith("--", offset):
323
+ newline = re.search(r"[\r\n]", statement[offset:])
324
+ offset = len(statement) if newline is None else offset + newline.start()
325
+ elif statement.startswith("/*", offset):
326
+ depth = 1
327
+ offset += 2
328
+ while depth and offset < len(statement):
329
+ if statement.startswith("/*", offset):
330
+ depth += 1
331
+ offset += 2
332
+ elif statement.startswith("*/", offset):
333
+ depth -= 1
334
+ offset += 2
335
+ else:
336
+ offset += 1
337
+ if depth:
338
+ raise ValueError("statement has an unterminated block comment")
339
+ elif character in ("'", '"', "[") or (
340
+ character in "Nn" and statement[offset + 1 : offset + 2] == "'"
341
+ ):
342
+ if character in "Nn":
343
+ offset += 1
344
+ character = "'"
345
+ closing = "]" if character == "[" else character
346
+ offset += 1
347
+ while offset < len(statement):
348
+ if statement[offset] == closing:
349
+ offset += 1
350
+ if statement[offset : offset + 1] == closing:
351
+ offset += 1
352
+ else:
353
+ break
354
+ else:
355
+ offset += 1
356
+ else:
357
+ raise ValueError("statement has an unterminated literal or identifier")
358
+ elif character == "@":
359
+ offset += 1
360
+ while offset < len(statement) and _is_sql_identifier_character(statement[offset]):
361
+ offset += 1
362
+ tokens.append(("variable", statement[start:offset], start, offset))
363
+ elif _is_sql_letter(character) or character in "_#$":
364
+ offset += 1
365
+ while offset < len(statement) and _is_sql_identifier_character(statement[offset]):
366
+ offset += 1
367
+ tokens.append(("word", statement[start:offset], start, offset))
368
+ elif character == ";":
369
+ offset += 1
370
+ tokens.append(("semicolon", ";", start, offset))
371
+ elif character == "(":
372
+ offset += 1
373
+ tokens.append(("open", "(", start, offset))
374
+ elif _is_sql_digit(character):
375
+ offset += 1
376
+ while offset < len(statement) and _is_sql_identifier_character(statement[offset]):
377
+ offset += 1
378
+ tokens.append(("other", statement[start:offset], start, offset))
379
+ else:
380
+ offset += 1
381
+ tokens.append(("other", character, start, offset))
382
+ return tokens
383
+
384
+
385
+ def _bind_statement(
386
+ statement: str, parameters: tuple[Any, ...], write: bool, key: str | None = None
387
+ ) -> tuple[str, dict[str, Any]]:
388
+ try:
389
+ statement_bytes = statement.encode("utf-8")
390
+ except UnicodeEncodeError as error:
391
+ raise ValueError("statement must be valid UTF-8") from error
392
+ if not statement.strip() or len(statement_bytes) > 1 << 20 or "\x00" in statement:
393
+ raise ValueError("statement is empty, oversized, or contains NUL")
394
+ if len(parameters) + (key is not None) > 2098:
395
+ raise ValueError("statement cannot bind more than 2098 parameters")
396
+ tokens = _scan_sql(statement)
397
+ first = next(
398
+ (text.upper() if kind == "word" else "" for kind, text, _, _ in tokens if kind != "open"),
399
+ "",
400
+ )
401
+ allowed = {"INSERT", "UPDATE", "DELETE", "MERGE", "WITH"} if write else {"SELECT", "WITH"}
402
+ if first not in allowed:
403
+ raise ValueError("statement starts with an operation this connector does not allow")
404
+ if re.fullmatch(r"[\w.#\[\]]+", statement):
405
+ raise ValueError("statement would be sent as a stored procedure call")
406
+ seen: set[int] = set()
407
+ final_semicolon = False
408
+ for index, (kind, text, _, _) in enumerate(tokens):
409
+ if kind == "semicolon":
410
+ final_semicolon = True
411
+ if any(next_kind != "semicolon" for next_kind, _, _, _ in tokens[index + 1 :]):
412
+ raise ValueError("statement holds more than one statement")
413
+ elif final_semicolon:
414
+ raise ValueError("statement holds more than one statement")
415
+ if kind == "word" and text.upper() in _DENIED_WORDS:
416
+ if (
417
+ text.upper() != "USE"
418
+ or index + 1 >= len(tokens)
419
+ or tokens[index + 1][1].upper() not in ("HINT", "PLAN")
420
+ ):
421
+ raise ValueError(f"statement uses reserved keyword {text.upper()}")
422
+ if kind == "variable" and not text.startswith("@@"):
423
+ match = _POSITIONAL.fullmatch(text)
424
+ if match is None:
425
+ raise ValueError("statement references a variable other than lowercase @pN")
426
+ position = int(match.group(1))
427
+ if position > len(parameters) + (key is not None):
428
+ raise ValueError("statement references an unbound parameter")
429
+ seen.add(position)
430
+ if seen != set(range(1, len(parameters) + (key is not None) + 1)):
431
+ raise ValueError("each bound parameter must be referenced in the statement")
432
+ values: dict[str, Any] = {}
433
+ total_bytes = 0
434
+ for index, parameter in enumerate((*parameters, *((key,) if key is not None else ())), 1):
435
+ if isinstance(parameter, bool) or parameter is None:
436
+ size = 1 if parameter is not None else 0
437
+ elif isinstance(parameter, int) and -(1 << 63) <= parameter < 1 << 63:
438
+ size = 8
439
+ elif isinstance(parameter, float) and math.isfinite(parameter):
440
+ size = 8
441
+ elif isinstance(parameter, (str, bytes)):
442
+ try:
443
+ size = len(parameter.encode("utf-8") if isinstance(parameter, str) else parameter)
444
+ except UnicodeEncodeError as error:
445
+ raise ValueError(f"parameter @p{index} must be valid UTF-8") from error
446
+ elif isinstance(parameter, datetime):
447
+ size = 10
448
+ else:
449
+ raise ValueError(f"parameter @p{index} has an unsupported type or value")
450
+ total_bytes += size
451
+ values[f"p{index}"] = parameter
452
+ if total_bytes > 16 << 20:
453
+ raise ValueError("parameters exceed 16777216 bytes combined")
454
+ # Escape literal percent signs for the DB-API pyformat parser, then insert named binds.
455
+ chunks: list[str] = []
456
+ offset = 0
457
+ for kind, text, start, end in tokens:
458
+ if kind == "variable" and not text.startswith("@@"):
459
+ chunks.append(statement[offset:start].replace("%", "%%"))
460
+ chunks.append(f"%({text[1:]})s")
461
+ offset = end
462
+ chunks.append(statement[offset:].replace("%", "%%"))
463
+ return "".join(chunks), values
464
+
465
+
466
+ def _classify(error: BaseException, phase: str) -> tuple[str, FailureKind, str, dict[str, str]]:
467
+ number = getattr(error, "number", 0)
468
+ if isinstance(number, int) and number != 0:
469
+ metadata = {
470
+ "errorNumber": str(number),
471
+ "errorState": str(getattr(error, "state", 0)),
472
+ "errorSeverity": str(getattr(error, "severity", 0)),
473
+ }
474
+ if phase == "commit" and number not in _COMMIT_ROLLED_BACK:
475
+ return "uncertain", FailureKind.AVAILABILITY, "SQL Server commit outcome is unknown", metadata
476
+ if number in _RETRY_CONFLICT:
477
+ return "retry", FailureKind.CONFLICT, "SQL Server transaction conflict; retry", metadata
478
+ if number in _RETRY_AVAILABILITY:
479
+ return "retry", FailureKind.AVAILABILITY, "SQL Server is temporarily unavailable", metadata
480
+ for numbers, failure_kind in (
481
+ (_AUTHENTICATION, FailureKind.AUTHENTICATION),
482
+ (_AUTHORIZATION, FailureKind.AUTHORIZATION),
483
+ (_NOT_FOUND, FailureKind.NOT_FOUND),
484
+ (_CONFLICT, FailureKind.CONFLICT),
485
+ (_VALIDATION, FailureKind.VALIDATION),
486
+ ({40544}, FailureKind.QUOTA_EXHAUSTED),
487
+ (_SESSION_LIMIT, FailureKind.AVAILABILITY),
488
+ ):
489
+ if number in numbers:
490
+ return "rejected", failure_kind, f"SQL Server rejected request with error {number}", metadata
491
+ if getattr(error, "severity", 0) >= 20:
492
+ return "retry", FailureKind.AVAILABILITY, "SQL Server is temporarily unavailable", metadata
493
+ return (
494
+ "rejected",
495
+ FailureKind.PROVIDER_REJECTION,
496
+ f"SQL Server rejected request with error {number}",
497
+ metadata,
498
+ )
499
+ if isinstance(error, _CommitNotSent):
500
+ return "retry", FailureKind.TRANSPORT, "SQL Server COMMIT was not sent", {}
501
+ if phase == "commit":
502
+ return "uncertain", FailureKind.TRANSPORT, "SQL Server commit outcome is unknown", {}
503
+ if isinstance(error, _InvalidResponse):
504
+ return "invalid", FailureKind.PROTOCOL, str(error), {}
505
+ error_text = str(error).lower()
506
+ if phase == "connect" and (
507
+ "you requested encryption but it is not supported by server" in error_text
508
+ or "server returned unexpected encrypt_on value" in error_text
509
+ ):
510
+ return "rejected", FailureKind.PROVIDER_REJECTION, "SQL Server does not accept required TLS", {}
511
+ if (
512
+ isinstance(error, ssl.SSLError)
513
+ or "certificate" in type(error).__name__.lower()
514
+ or "certificate does not match host name" in error_text
515
+ or "certificate verify failed" in error_text
516
+ ):
517
+ return "rejected", FailureKind.AUTHENTICATION, "SQL Server certificate was rejected", {}
518
+ if isinstance(error, ValueError):
519
+ return "defect", FailureKind.VALIDATION, str(error), {}
520
+ if isinstance(error, tds_base.DataError):
521
+ return "defect", FailureKind.VALIDATION, "SQL Server driver rejected a parameter value", {}
522
+ if isinstance(error, TimeoutError) and phase == "statement":
523
+ return (
524
+ "rejected",
525
+ FailureKind.AVAILABILITY,
526
+ "SQL Server statement timed out; nothing was committed",
527
+ {},
528
+ )
529
+ if phase == "connect":
530
+ cause: BaseException | None = error
531
+ while cause is not None:
532
+ if isinstance(cause, socket.gaierror) and cause.errno == socket.EAI_NONAME:
533
+ return "rejected", FailureKind.NOT_FOUND, "SQL Server host was not found", {}
534
+ cause = cause.__cause__ or cause.__context__
535
+ if isinstance(error, socket.gaierror) and error.errno == socket.EAI_NONAME:
536
+ return "rejected", FailureKind.NOT_FOUND, "SQL Server host was not found", {}
537
+ return "retry", FailureKind.AVAILABILITY, "SQL Server is unreachable or did not finish connecting", {}
538
+ if isinstance(error, tds_base.Error) and any(
539
+ phrase in error_text
540
+ for phrase in ("connection closed", "closed connection", "server closed connection")
541
+ ):
542
+ return "retry", FailureKind.TRANSPORT, "SQL Server connection failed before commit", {}
543
+ if isinstance(
544
+ error,
545
+ (
546
+ OSError,
547
+ EOFError,
548
+ ConnectionError,
549
+ TimeoutError,
550
+ tds_base.ClosedConnectionError,
551
+ SSL.SysCallError,
552
+ SSL.ZeroReturnError,
553
+ ),
554
+ ):
555
+ return "retry", FailureKind.TRANSPORT, "SQL Server connection failed before commit", {}
556
+ return "invalid", FailureKind.PROTOCOL, "SQL Server driver could not decode the reply", {}
557
+
558
+
559
+ def _receipt(call: Call, metadata: dict[str, str] | None = None, connection: Any = None) -> Receipt:
560
+ receipt_metadata = dict(getattr(connection, "_dex_receipt_metadata", {}))
561
+ receipt_metadata.update(metadata or {})
562
+ return Receipt(
563
+ CallID(str(call.id)),
564
+ CONNECTOR_ID,
565
+ datetime.now(UTC),
566
+ IdempotencyKey(str(call.idempotency_key)),
567
+ metadata=receipt_metadata,
568
+ )
569
+
570
+
571
+ def _row_value(value: Any, type_name: str, scale: int | None = None) -> Any:
572
+ if value is None:
573
+ return None
574
+ if type_name == "BIGINT" and isinstance(value, int):
575
+ return str(value)
576
+ if type_name in ("DECIMAL", "MONEY", "SMALLMONEY") and isinstance(value, (Decimal, str)):
577
+ if isinstance(value, str):
578
+ value = Decimal(value)
579
+ declared_scale = 4 if type_name in ("MONEY", "SMALLMONEY") else scale
580
+ if declared_scale is None or not 0 <= declared_scale <= 38:
581
+ raise _InvalidResponse("SQL Server decimal scale is unavailable")
582
+ with localcontext() as decimal_context:
583
+ decimal_context.prec = 50
584
+ return format(value.quantize(Decimal(1).scaleb(-declared_scale)), "f")
585
+ if type_name in ("TINYINT", "SMALLINT", "INT") and type(value) is int:
586
+ return value
587
+ if type_name == "BIT" and isinstance(value, bool):
588
+ return value
589
+ if type_name in ("CHAR", "VARCHAR", "TEXT", "NCHAR", "NVARCHAR", "NTEXT", "XML") and isinstance(
590
+ value, str
591
+ ):
592
+ return value
593
+ if type_name in ("REAL", "FLOAT") and isinstance(value, float):
594
+ if not math.isfinite(value):
595
+ raise _InvalidResponse("SQL Server returned a nonfinite number")
596
+ if type_name == "REAL":
597
+ packed = struct.pack("!f", value)
598
+ for digits in range(1, 10):
599
+ candidate = float(format(value, f".{digits}g"))
600
+ if struct.pack("!f", candidate) == packed:
601
+ return candidate
602
+ return value
603
+ if isinstance(value, bytes) and type_name in (
604
+ "BINARY",
605
+ "VARBINARY",
606
+ "IMAGE",
607
+ "GEOGRAPHY",
608
+ "GEOMETRY",
609
+ "HIERARCHYID",
610
+ ):
611
+ return base64.b64encode(value).decode("ascii")
612
+ if type_name == "UNIQUEIDENTIFIER" and isinstance(value, uuid.UUID):
613
+ return str(value)
614
+ if type_name in ("DATETIME", "SMALLDATETIME", "DATETIME2", "DATETIMEOFFSET") and isinstance(
615
+ value, datetime
616
+ ):
617
+ if type_name != "DATETIMEOFFSET" and value.tzinfo is not None:
618
+ value = value.replace(tzinfo=None)
619
+ formatted = value.isoformat(timespec="microseconds")
620
+ formatted = re.sub(r"(\.\d*?)0+(?=[+-]\d\d:\d\d$|$)", r"\1", formatted)
621
+ formatted = re.sub(r"\.(?=[+-]\d\d:\d\d$|$)", "", formatted)
622
+ return (
623
+ formatted[:-6] + "Z"
624
+ if type_name == "DATETIMEOFFSET" and formatted.endswith("+00:00")
625
+ else formatted
626
+ )
627
+ if type_name == "DATE" and isinstance(value, date):
628
+ return value.isoformat()
629
+ if type_name == "TIME" and isinstance(value, time):
630
+ return value.isoformat(timespec="microseconds").rstrip("0").rstrip(".")
631
+ raise _InvalidResponse("SQL Server returned a value the connector cannot decode")
632
+
633
+
634
+ def _read_rows(
635
+ cursor: Any, max_rows: int, max_bytes: int
636
+ ) -> tuple[tuple[Column, ...], tuple[dict[str, Any], ...], bool]:
637
+ description = cursor.description
638
+ if not description:
639
+ return (), (), False
640
+ columns: list[Column] = []
641
+ for field in description:
642
+ name = str(field[0])
643
+ if not name or any(column.name == name for column in columns):
644
+ raise ValueError("SQL Server returned duplicate or empty column names")
645
+ type_name = (
646
+ _SQL_TYPES.get(field[1], "UNKNOWN") if isinstance(field[1], int) else str(field[1]).upper()
647
+ )
648
+ if field[1] == 240:
649
+ native_columns = getattr(
650
+ getattr(getattr(cursor, "_session", None), "res_info", None), "columns", ()
651
+ )
652
+ serializer = (
653
+ getattr(native_columns[len(columns)], "serializer", None)
654
+ if len(native_columns) > len(columns)
655
+ else None
656
+ )
657
+ type_name = str(getattr(serializer, "type_name", "UNKNOWN")).upper()
658
+ if type_name not in ("GEOGRAPHY", "GEOMETRY", "HIERARCHYID"):
659
+ raise _InvalidResponse(f'column "{name}" has an unsupported SQL CLR type')
660
+ elif type_name == "UNKNOWN":
661
+ raise _InvalidResponse(f'column "{name}" has an unsupported SQL type')
662
+ if type_name in ("TIME", "DATETIME2", "DATETIMEOFFSET"):
663
+ temporal_scale = (
664
+ field[5]
665
+ if len(field) > 5 and isinstance(field[5], int)
666
+ else (field[4] if len(field) > 4 else None)
667
+ )
668
+ if temporal_scale == 7:
669
+ raise _InvalidResponse(
670
+ f'column "{name}" of type {type_name} uses scale 7; '
671
+ "the Python driver cannot decode it exactly"
672
+ )
673
+ columns.append(Column(name, type_name))
674
+ rows: list[dict[str, Any]] = []
675
+ reader = getattr(getattr(cursor, "_session", None), "_reader", None)
676
+ budget_transport = None
677
+ if reader is not None:
678
+ budget_transport = _ReadBudgetTransport(reader._transport, max_bytes + (64 << 10))
679
+ reader._transport = budget_transport
680
+ encoded_bytes = 2
681
+ try:
682
+ while True:
683
+ raw = cursor.fetchone()
684
+ if raw is None:
685
+ while callable(getattr(cursor, "nextset", None)) and cursor.nextset():
686
+ if cursor.description:
687
+ raise ValueError("statement returned more than one result set")
688
+ return tuple(columns), tuple(rows), False
689
+ if len(rows) >= max_rows:
690
+ return tuple(columns), tuple(rows), True
691
+ row = {
692
+ column.name: _row_value(
693
+ value,
694
+ column.type_name,
695
+ description[index][5]
696
+ if len(description[index]) > 5 and isinstance(description[index][5], int)
697
+ else None,
698
+ )
699
+ for index, (column, value) in enumerate(zip(columns, raw, strict=True))
700
+ }
701
+ encoded_row = json.dumps(row, separators=(",", ":"), sort_keys=True, ensure_ascii=False)
702
+ for character, escaped in (
703
+ ("<", "\\u003c"),
704
+ (">", "\\u003e"),
705
+ ("&", "\\u0026"),
706
+ ("\u2028", "\\u2028"),
707
+ ("\u2029", "\\u2029"),
708
+ ):
709
+ encoded_row = encoded_row.replace(character, escaped)
710
+ encoded_bytes += len(encoded_row.encode("utf-8")) + 1
711
+ if encoded_bytes > max_bytes:
712
+ return tuple(columns), tuple(rows), True
713
+ rows.append(row)
714
+ except _ReadBudgetExceeded:
715
+ return tuple(columns), tuple(rows), True
716
+ finally:
717
+ if budget_transport is not None:
718
+ budget_transport.set_control_budget()
719
+
720
+
721
+ class QueryRowsOperation:
722
+ """Run one read statement and roll back its transaction."""
723
+
724
+ def __init__(self, client: Any) -> None:
725
+ self.client = client
726
+
727
+ def definition(self) -> QueryDefinition:
728
+ """Return the manifest Query identity and branch contract."""
729
+ return QUERY_DEFINITION
730
+
731
+ async def invoke(self, call: Call, input: QueryRowsInput) -> QueryAttempt[RowSet]:
732
+ """Classify one native read attempt without persisting credentials."""
733
+ try:
734
+ statement, parameters = _bind_statement(input.statement, input.parameters, False)
735
+ except ValueError as error:
736
+ return QueryAttempt.branch_result(
737
+ DEFECT,
738
+ RowSet(),
739
+ Receipt(),
740
+ Failure(FailureKind.VALIDATION, CONNECTOR_ID, QUERY_OPERATION_ID, str(error)),
741
+ )
742
+ try:
743
+ credentials = await self.client.credentials.resolve(call)
744
+ password = credentials.password.reveal()
745
+ if not password:
746
+ raise ValueError("password is unavailable")
747
+ except (ValueError, LookupError, OSError, ReauthorizationRequiredError):
748
+ return QueryAttempt.branch_result(
749
+ DEFECT,
750
+ RowSet(),
751
+ Receipt(),
752
+ Failure(
753
+ FailureKind.AUTHENTICATION,
754
+ CONNECTOR_ID,
755
+ QUERY_OPERATION_ID,
756
+ "SQL Server connection credentials are unavailable",
757
+ ),
758
+ )
759
+ return await asyncio.to_thread(self._invoke_sync, call, statement, parameters, password)
760
+
761
+ def _invoke_sync(
762
+ self, call: Call, statement: str, parameters: dict[str, Any], password: str
763
+ ) -> QueryAttempt[RowSet]:
764
+ phase = "connect"
765
+ connection = None
766
+ statement_deadline: _AttemptDeadline | None = None
767
+ deadline = _AttemptDeadline(
768
+ self.client.config.connect_timeout_seconds + self.client.config.statement_timeout_seconds + 5
769
+ )
770
+ try:
771
+ connection = self.client.open_connection(password, deadline)
772
+ deadline.check()
773
+ phase = "statement"
774
+ statement_deadline = _AttemptDeadline(self.client.config.statement_timeout_seconds)
775
+ statement_deadline.attach_connection(connection)
776
+ cursor = connection.cursor()
777
+ cursor.execute(statement, parameters)
778
+ deadline.check()
779
+ statement_deadline.check()
780
+ columns, rows, truncated = _read_rows(
781
+ cursor, self.client.config.max_rows, self.client.config.max_response_bytes
782
+ )
783
+ deadline.check()
784
+ statement_deadline.check()
785
+ if not columns:
786
+ raise ValueError("query statement returned no result set")
787
+ value = RowSet(columns, rows, truncated)
788
+ if truncated:
789
+ failure = Failure(
790
+ FailureKind.RESPONSE_TOO_LARGE,
791
+ CONNECTOR_ID,
792
+ QUERY_OPERATION_ID,
793
+ "SQL Server rows exceeded maxRows or maxResponseBytes",
794
+ )
795
+ return QueryAttempt.branch_result(
796
+ TRUNCATED, value, _receipt(call, connection=connection), failure
797
+ )
798
+ return QueryAttempt.branch_result(COMPLETED, value, _receipt(call, connection=connection))
799
+ except Exception as error:
800
+ has_timed_out = deadline.expired.is_set() or (
801
+ statement_deadline is not None and statement_deadline.expired.is_set()
802
+ )
803
+ classified_error = TimeoutError("SQL Server statement timed out") if has_timed_out else error
804
+ disposition, kind, message, metadata = _classify(classified_error, phase)
805
+ failure = Failure(kind, CONNECTOR_ID, QUERY_OPERATION_ID, message)
806
+ if disposition in ("retry", "uncertain"):
807
+ return QueryAttempt.retry(failure)
808
+ branch = (
809
+ DEFECT
810
+ if disposition == "defect"
811
+ else INVALID_RESPONSE
812
+ if disposition == "invalid"
813
+ else PROVIDER_REJECTED
814
+ )
815
+ return QueryAttempt.branch_result(branch, RowSet(), _receipt(call, metadata, connection), failure)
816
+ finally:
817
+ if statement_deadline is not None:
818
+ statement_deadline.close()
819
+ if connection is not None:
820
+ try:
821
+ connection.close()
822
+ except Exception:
823
+ # The read outcome was already classified and the session cannot be reused.
824
+ pass
825
+ deadline.close()
826
+
827
+
828
+ class ExecuteStatementOperation:
829
+ """Run one bounded write and classify commit uncertainty separately."""
830
+
831
+ def __init__(self, client: Any) -> None:
832
+ self.client = client
833
+
834
+ def definition(self) -> MutationDefinition:
835
+ """Return the manifest Mutation identity and branch contract."""
836
+ return EXECUTE_DEFINITION
837
+
838
+ def idempotency_key(self, call_id: CallID, _input: ExecuteStatementInput) -> IdempotencyKey:
839
+ """Use the stable Dex Call ID for an optional final SQL placeholder."""
840
+ return IdempotencyKey(str(call_id))
841
+
842
+ async def invoke(self, call: Call, input: ExecuteStatementInput) -> MutationAttempt[StatementExecution]:
843
+ """Run one write, rolling back every precommit failure or limit excess."""
844
+ try:
845
+ if input.max_rows_affected is not None and input.max_rows_affected < 0:
846
+ raise ValueError("maxRowsAffected cannot be negative")
847
+ if input.idempotency_key_placeholder not in (0, len(input.parameters) + 1):
848
+ raise ValueError("idempotencyKeyPlaceholder must be the last placeholder")
849
+ key = str(call.idempotency_key) if input.idempotency_key_placeholder else None
850
+ statement, parameters = _bind_statement(input.statement, input.parameters, True, key)
851
+ except ValueError as error:
852
+ return MutationAttempt.branch_result(
853
+ DEFECT,
854
+ StatementExecution(),
855
+ Receipt(),
856
+ Failure(FailureKind.VALIDATION, CONNECTOR_ID, EXECUTE_OPERATION_ID, str(error)),
857
+ )
858
+ try:
859
+ credentials = await self.client.credentials.resolve(call)
860
+ password = credentials.password.reveal()
861
+ if not password:
862
+ raise ValueError("password is unavailable")
863
+ except (ValueError, LookupError, OSError, ReauthorizationRequiredError):
864
+ return MutationAttempt.branch_result(
865
+ DEFECT,
866
+ StatementExecution(),
867
+ Receipt(),
868
+ Failure(
869
+ FailureKind.AUTHENTICATION,
870
+ CONNECTOR_ID,
871
+ EXECUTE_OPERATION_ID,
872
+ "SQL Server connection credentials are unavailable",
873
+ ),
874
+ )
875
+ return await asyncio.to_thread(self._invoke_sync, call, input, statement, parameters, password)
876
+
877
+ def _invoke_sync(
878
+ self,
879
+ call: Call,
880
+ input: ExecuteStatementInput,
881
+ statement: str,
882
+ parameters: dict[str, Any],
883
+ password: str,
884
+ ) -> MutationAttempt[StatementExecution]:
885
+ phase = "connect"
886
+ connection = None
887
+ statement_deadline: _AttemptDeadline | None = None
888
+ deadline = _AttemptDeadline(
889
+ self.client.config.connect_timeout_seconds + self.client.config.statement_timeout_seconds + 5
890
+ )
891
+ try:
892
+ connection = self.client.open_connection(password, deadline)
893
+ deadline.check()
894
+ phase = "statement"
895
+ statement_deadline = _AttemptDeadline(self.client.config.statement_timeout_seconds)
896
+ statement_deadline.attach_connection(connection)
897
+ cursor = connection.cursor()
898
+ done_counts: list[int] = []
899
+ session = getattr(cursor, "_session", None)
900
+ if session is not None:
901
+ process_end = session.process_end
902
+
903
+ def capture_done_count(marker: int) -> None:
904
+ process_end(marker)
905
+ if session.done_flags & tds_base.TDS_DONE_COUNT:
906
+ done_counts.append(int(session.rows_affected))
907
+
908
+ session.process_end = capture_done_count
909
+ cursor.execute(statement, parameters)
910
+ deadline.check()
911
+ statement_deadline.check()
912
+ if input.returns_output_rows:
913
+ columns, rows, truncated = _read_rows(
914
+ cursor, self.client.config.max_rows, self.client.config.max_response_bytes
915
+ )
916
+ if truncated:
917
+ failure = Failure(
918
+ FailureKind.RESPONSE_TOO_LARGE,
919
+ CONNECTOR_ID,
920
+ EXECUTE_OPERATION_ID,
921
+ "SQL Server OUTPUT rows exceeded bounds",
922
+ )
923
+ return MutationAttempt.branch_result(
924
+ LIMIT_EXCEEDED, StatementExecution(), _receipt(call, connection=connection), failure
925
+ )
926
+ if not columns:
927
+ raise ValueError("returnsOutputRows is set but no OUTPUT result set was returned")
928
+ value = StatementExecution(len(rows), columns, rows)
929
+ else:
930
+ fallback_counts = [int(cursor.rowcount)] if session is None and cursor.rowcount >= 0 else []
931
+ reader = getattr(session, "_reader", None)
932
+ budget_transport = None
933
+ if reader is not None:
934
+ budget_transport = _ReadBudgetTransport(
935
+ reader._transport, self.client.config.max_response_bytes + (64 << 10)
936
+ )
937
+ reader._transport = budget_transport
938
+ try:
939
+ while cursor.nextset():
940
+ if session is None and cursor.rowcount >= 0:
941
+ fallback_counts.append(int(cursor.rowcount))
942
+ except _ReadBudgetExceeded:
943
+ failure = Failure(
944
+ FailureKind.RESPONSE_TOO_LARGE,
945
+ CONNECTOR_ID,
946
+ EXECUTE_OPERATION_ID,
947
+ "SQL Server statement reply exceeded the read budget",
948
+ )
949
+ return MutationAttempt.branch_result(
950
+ LIMIT_EXCEEDED, StatementExecution(), _receipt(call, connection=connection), failure
951
+ )
952
+ finally:
953
+ if budget_transport is not None:
954
+ budget_transport.set_control_budget()
955
+ counts = done_counts if session is not None else fallback_counts
956
+ rows_affected = sum(counts)
957
+ has_count = bool(counts)
958
+ if not has_count and input.max_rows_affected is not None:
959
+ raise _InvalidResponse("SQL Server did not report rows affected")
960
+ value = StatementExecution(rows_affected)
961
+ if input.max_rows_affected is not None and value.rows_affected > input.max_rows_affected:
962
+ failure = Failure(
963
+ FailureKind.CONFLICT,
964
+ CONNECTOR_ID,
965
+ EXECUTE_OPERATION_ID,
966
+ "SQL Server rows affected exceeded maxRowsAffected",
967
+ )
968
+ return MutationAttempt.branch_result(
969
+ LIMIT_EXCEEDED, StatementExecution(), _receipt(call, connection=connection), failure
970
+ )
971
+ statement_deadline.check()
972
+ statement_deadline.close()
973
+ try:
974
+ deadline.check()
975
+ except TimeoutError as error:
976
+ raise _CommitNotSent() from error
977
+ phase = "commit"
978
+ commit_session = getattr(getattr(connection, "_tds_socket", None), "main_session", None)
979
+ writer = getattr(commit_session, "_writer", None)
980
+ commit_transport = None
981
+ transport_owner = None
982
+ if writer is not None:
983
+ writer_transport = writer._transport
984
+ transport_owner = (
985
+ writer_transport if hasattr(writer_transport, "_transport") else writer
986
+ )
987
+ commit_transport = _CommitWriteTransport(transport_owner._transport)
988
+ transport_owner._transport = commit_transport
989
+ try:
990
+ connection.commit()
991
+ except Exception as error:
992
+ if (
993
+ commit_transport is not None
994
+ and commit_transport.bytes_sent == 0
995
+ and not commit_transport.has_unobservable_write
996
+ ):
997
+ raise _CommitNotSent() from error
998
+ raise
999
+ finally:
1000
+ if commit_transport is not None and transport_owner is not None:
1001
+ transport_owner._transport = commit_transport.transport
1002
+ return MutationAttempt.branch_result(COMPLETED, value, _receipt(call, connection=connection))
1003
+ except Exception as error:
1004
+ has_timed_out = deadline.expired.is_set() or (
1005
+ statement_deadline is not None and statement_deadline.expired.is_set()
1006
+ )
1007
+ classified_error = (
1008
+ TimeoutError("SQL Server statement timed out")
1009
+ if has_timed_out and not isinstance(error, _CommitNotSent) and phase != "commit"
1010
+ else error
1011
+ )
1012
+ disposition, kind, message, metadata = _classify(classified_error, phase)
1013
+ failure = Failure(kind, CONNECTOR_ID, EXECUTE_OPERATION_ID, message)
1014
+ if disposition == "retry":
1015
+ return MutationAttempt.retry(failure)
1016
+ if disposition == "uncertain":
1017
+ return MutationAttempt.uncertain(
1018
+ StatementExecution(), failure, _receipt(call, metadata, connection)
1019
+ )
1020
+ branch = (
1021
+ DEFECT
1022
+ if disposition == "defect"
1023
+ else INVALID_RESPONSE
1024
+ if disposition == "invalid"
1025
+ else PROVIDER_REJECTED
1026
+ )
1027
+ return MutationAttempt.branch_result(
1028
+ branch, StatementExecution(), _receipt(call, metadata, connection), failure
1029
+ )
1030
+ finally:
1031
+ if statement_deadline is not None:
1032
+ statement_deadline.close()
1033
+ if connection is not None:
1034
+ try:
1035
+ connection.close()
1036
+ except Exception:
1037
+ # Outcome was already classified and the native connection is unusable.
1038
+ pass
1039
+ deadline.close()