dex-connector-microsoft-sql-server 0.1.0__tar.gz → 0.2.0__tar.gz

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.
Files changed (39) hide show
  1. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/.gitignore +5 -0
  2. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/PKG-INFO +20 -8
  3. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/README.md +18 -6
  4. dex_connector_microsoft_sql_server-0.2.0/examples/record_refund/README.md +27 -0
  5. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/flow.py +46 -2
  6. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/integration_test.py +5 -0
  7. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/schema.sql +5 -0
  8. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/pyproject.toml +2 -2
  9. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/__init__.py +4 -2
  10. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/definitions.py +22 -1
  11. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/mock.py +58 -1
  12. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/steps.py +58 -0
  13. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/client.py +13 -2
  14. dex_connector_microsoft_sql_server-0.2.0/src/dex_connectors/microsoft_sql_server/connection.py +193 -0
  15. dex_connector_microsoft_sql_server-0.2.0/src/dex_connectors/microsoft_sql_server/dex-connector.json +222 -0
  16. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/operations.py +273 -103
  17. dex_connector_microsoft_sql_server-0.2.0/src/dex_connectors/microsoft_sql_server/steps.py +7 -0
  18. dex_connector_microsoft_sql_server-0.2.0/tests/test_connection.py +78 -0
  19. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/tests/test_operations.py +331 -23
  20. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/uv.lock +7 -5
  21. dex_connector_microsoft_sql_server-0.1.0/examples/record_refund/README.md +0 -22
  22. dex_connector_microsoft_sql_server-0.1.0/src/dex_connectors/microsoft_sql_server/_generated/connection.py +0 -173
  23. dex_connector_microsoft_sql_server-0.1.0/src/dex_connectors/microsoft_sql_server/connection.py +0 -12
  24. dex_connector_microsoft_sql_server-0.1.0/src/dex_connectors/microsoft_sql_server/dex-connector.json +0 -92
  25. dex_connector_microsoft_sql_server-0.1.0/src/dex_connectors/microsoft_sql_server/steps.py +0 -7
  26. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/LICENSE +0 -0
  27. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/__init__.py +0 -0
  28. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/__init__.py +0 -0
  29. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/sample-input.json +0 -0
  30. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/start.py +0 -0
  31. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/examples/record_refund/worker.py +0 -0
  32. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/__init__.py +0 -0
  33. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/config.py +0 -0
  34. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/_generated/models.py +0 -0
  35. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/models.py +0 -0
  36. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/py.typed +0 -0
  37. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/src/dex_connectors/microsoft_sql_server/sqlservermock/__init__.py +0 -0
  38. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/tests/integration/test_database.py +0 -0
  39. {dex_connector_microsoft_sql_server-0.1.0 → dex_connector_microsoft_sql_server-0.2.0}/tests/test_tds_identity.py +0 -0
@@ -5,9 +5,14 @@ node_modules/
5
5
  dist/
6
6
  sdkpython/dist/dex_connectors_sdk-0.1.0-py3-none-any.whl
7
7
  /.bin/dexcli
8
+ /dexcli
9
+ /dex-server-zd
8
10
  /.bin/dex-server-zd
11
+ /connectorsmcp/examples/hackernews_agent/.bin/
12
+ /connectorsmcp/examples/hackernews_agent/.venv/
9
13
  /sdkpython/.dexcli-data/
10
14
  site/.catalog.yaml
15
+ site/.catalog-language-tags
11
16
  coverage/
12
17
  *.out
13
18
  *.test
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: dex-connector-microsoft-sql-server
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Microsoft SQL Server connector for Dex Flows
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
7
7
  Requires-Python: >=3.11
8
8
  Requires-Dist: certifi>=2024.2.2
9
9
  Requires-Dist: cryptography<51,>=42
10
- Requires-Dist: dex-connectors-sdk==0.1.0
10
+ Requires-Dist: dex-connectors-sdk<1,>=0.12.0
11
11
  Requires-Dist: dex-python-sdk>=1.28.0
12
12
  Requires-Dist: httpx>=0.27
13
13
  Requires-Dist: pyopenssl<27,>=24
@@ -16,14 +16,14 @@ Description-Content-Type: text/markdown
16
16
 
17
17
  # Microsoft SQL Server Python connector
18
18
 
19
- The Python package exposes the manifest's `query` and `execute` operations through native
19
+ The Python package exposes the manifest's `query`, `execute`, and `executeNonIdempotent` operations through native
20
20
  `python-tds` sessions. Each attempt resolves the current private password, opens one SQL
21
21
  Server connection, pins session settings, and closes it. It never persists the password in
22
22
  Flow input, output, a receipt, or an Attribute.
23
23
 
24
24
  ## Install and configure
25
25
 
26
- Install `dex-connector-microsoft-sql-server==0.1.0`. Create a Dex Web connection named
26
+ Install `dex-connector-microsoft-sql-server==0.2.0`. Create a Dex Web connection named
27
27
  `sqlserver-refunds` for the [runnable example](examples/record_refund/README.md), following
28
28
  the authorization guide in the [connector README](../README.md#connection-setup).
29
29
  The connection needs a host, database, SQL authentication user and secret password. Port,
@@ -62,9 +62,21 @@ failures retry.
62
62
  `new_execute_step` runs one parameterized `INSERT`, `UPDATE`, `DELETE`, `MERGE`, or `WITH`
63
63
  statement in its own transaction. The optional final `@pN` idempotency-key placeholder
64
64
  binds Dex's stable Call ID. A write that exceeds `maxRowsAffected` or an OUTPUT bound
65
- rolls back and selects `limitExceeded`. A failed COMMIT whose outcome is unknown selects
66
- `uncertain`; a COMMIT failure retries only when no bytes were sent. Failures before COMMIT
67
- retry only when safe. Make every write statement idempotent across retries and Worker replacement.
65
+ rolls back and selects `limitExceeded`. `execute` is `repeatOnUnknown: safe`: a failed
66
+ COMMIT whose outcome is unknown returns Retry and the statement runs again, so it never
67
+ selects `uncertain`. Failures before COMMIT retry only when safe. Make every `execute`
68
+ statement repeat-safe across retries and Worker replacement.
69
+
70
+ `new_execute_non_idempotent_step` takes the same input for a statement that must not run
71
+ twice, such as a relative balance update. `executeNonIdempotent` is `repeatOnUnknown:
72
+ unsafe`: it records a single-dispatch claim in the sync Step heartbeat before COMMIT,
73
+ selects `uncertain` when COMMIT bytes may have reached the server, and selects `uncertain`
74
+ without connecting on a later attempt after such a COMMIT or a lost Worker. A COMMIT that
75
+ sent no bytes, or a proven rollback such as a deadlock victim, returns Retry; an unreadable
76
+ checkpoint returns Retry without connecting. `new_connection_with_operations` keeps its
77
+ `(query, execute, reference)` order and accepts the new operation as the keyword-only
78
+ `execute_non_idempotent`; a connection built without it raises `ValueError` when an
79
+ `executeNonIdempotent` Step is constructed.
68
80
  `rowsAffected` sums all SQL Server DONE counts, including trigger statements. If the server
69
81
  supplies no count, `maxRowsAffected` fails `invalidResponse` before COMMIT. Receipts include
70
82
  the session process ID and server version; server errors add number, state, and severity.
@@ -83,7 +95,7 @@ the exact application call pattern.
83
95
  ## Verification
84
96
 
85
97
  The package unit tests cover routing, driver error numbers, input validation, row bounds,
86
- and commit uncertainty. The example integration test runs its Worker and Client against a
98
+ commit retries, and executeNonIdempotent fencing. The example integration test runs its Worker and Client against a
87
99
  real `dexcli dev` server with scripted connector operations. The SQL Server service-container
88
100
  workflow runs `tests/integration/test_database.py`; its mandatory TLS pass depends on the
89
101
  separate CI workflow change in PR #518. No live
@@ -1,13 +1,13 @@
1
1
  # Microsoft SQL Server Python connector
2
2
 
3
- The Python package exposes the manifest's `query` and `execute` operations through native
3
+ The Python package exposes the manifest's `query`, `execute`, and `executeNonIdempotent` operations through native
4
4
  `python-tds` sessions. Each attempt resolves the current private password, opens one SQL
5
5
  Server connection, pins session settings, and closes it. It never persists the password in
6
6
  Flow input, output, a receipt, or an Attribute.
7
7
 
8
8
  ## Install and configure
9
9
 
10
- Install `dex-connector-microsoft-sql-server==0.1.0`. Create a Dex Web connection named
10
+ Install `dex-connector-microsoft-sql-server==0.2.0`. Create a Dex Web connection named
11
11
  `sqlserver-refunds` for the [runnable example](examples/record_refund/README.md), following
12
12
  the authorization guide in the [connector README](../README.md#connection-setup).
13
13
  The connection needs a host, database, SQL authentication user and secret password. Port,
@@ -46,9 +46,21 @@ failures retry.
46
46
  `new_execute_step` runs one parameterized `INSERT`, `UPDATE`, `DELETE`, `MERGE`, or `WITH`
47
47
  statement in its own transaction. The optional final `@pN` idempotency-key placeholder
48
48
  binds Dex's stable Call ID. A write that exceeds `maxRowsAffected` or an OUTPUT bound
49
- rolls back and selects `limitExceeded`. A failed COMMIT whose outcome is unknown selects
50
- `uncertain`; a COMMIT failure retries only when no bytes were sent. Failures before COMMIT
51
- retry only when safe. Make every write statement idempotent across retries and Worker replacement.
49
+ rolls back and selects `limitExceeded`. `execute` is `repeatOnUnknown: safe`: a failed
50
+ COMMIT whose outcome is unknown returns Retry and the statement runs again, so it never
51
+ selects `uncertain`. Failures before COMMIT retry only when safe. Make every `execute`
52
+ statement repeat-safe across retries and Worker replacement.
53
+
54
+ `new_execute_non_idempotent_step` takes the same input for a statement that must not run
55
+ twice, such as a relative balance update. `executeNonIdempotent` is `repeatOnUnknown:
56
+ unsafe`: it records a single-dispatch claim in the sync Step heartbeat before COMMIT,
57
+ selects `uncertain` when COMMIT bytes may have reached the server, and selects `uncertain`
58
+ without connecting on a later attempt after such a COMMIT or a lost Worker. A COMMIT that
59
+ sent no bytes, or a proven rollback such as a deadlock victim, returns Retry; an unreadable
60
+ checkpoint returns Retry without connecting. `new_connection_with_operations` keeps its
61
+ `(query, execute, reference)` order and accepts the new operation as the keyword-only
62
+ `execute_non_idempotent`; a connection built without it raises `ValueError` when an
63
+ `executeNonIdempotent` Step is constructed.
52
64
  `rowsAffected` sums all SQL Server DONE counts, including trigger statements. If the server
53
65
  supplies no count, `maxRowsAffected` fails `invalidResponse` before COMMIT. Receipts include
54
66
  the session process ID and server version; server errors add number, state, and severity.
@@ -67,7 +79,7 @@ the exact application call pattern.
67
79
  ## Verification
68
80
 
69
81
  The package unit tests cover routing, driver error numbers, input validation, row bounds,
70
- and commit uncertainty. The example integration test runs its Worker and Client against a
82
+ commit retries, and executeNonIdempotent fencing. The example integration test runs its Worker and Client against a
71
83
  real `dexcli dev` server with scripted connector operations. The SQL Server service-container
72
84
  workflow runs `tests/integration/test_database.py`; its mandatory TLS pass depends on the
73
85
  separate CI workflow change in PR #518. No live
@@ -0,0 +1,27 @@
1
+ # Record a refund with SQL Server
2
+
3
+ Create `dbo.refund_ledger` and `dbo.refund_daily_totals` with `schema.sql` using an administrator
4
+ connection. Create the `sqlserver-refunds` connection in Dex Web with SQL authentication, SELECT and
5
+ INSERT on `dbo.refund_ledger`, and SELECT, INSERT, and UPDATE on `dbo.refund_daily_totals`. Run `uv run --project connectors/microsoft/sql-server/python python -m examples.record_refund.worker`
6
+ with `DEX_FLOW_SERVICE_ADDRESS` pointing to the Dex server, then start a Flow with
7
+ `uv run --project connectors/microsoft/sql-server/python python -m examples.record_refund.start
8
+ <unique-flow-id> connectors/microsoft/sql-server/python/examples/record_refund/sample-input.json`.
9
+
10
+ The write binds the stable Dex Call ID as its final unique key; `execute` is repeat-safe, so a COMMIT
11
+ with an unknown outcome runs it again with the same key. The Flow then adds the refund to today's
12
+ total in `dbo.refund_daily_totals` with `executeNonIdempotent`, because running that MERGE twice
13
+ would count the refund twice, and the subsequent read returns the committed row. Optional branches
14
+ remain unwired, so the Flow fails on a rejected write or an uncertain daily total instead of counting
15
+ the refund twice.
16
+ From the repository root, generate and lint strict Flow Definition Graph 2.0:
17
+
18
+ ```bash
19
+ PYTHONPATH=connectors/microsoft/sql-server/python dexcli visualize \
20
+ connectors/microsoft/sql-server/python/examples/record_refund/flow.py \
21
+ --language python --schema-version 2.0 --lint app --json \
22
+ --python connectors/microsoft/sql-server/python/.venv/bin/python \
23
+ --out /tmp/sqlserver-python-fdg/record-refund
24
+ ```
25
+
26
+ The graph shows PrepareRefund, WriteRefund, PrepareDailyTotal, AddRefundToDailyTotal,
27
+ PrepareReadBack, ReadRefund, and CompleteRefund.
@@ -13,12 +13,22 @@ from dex_connectors.microsoft_sql_server import (
13
13
  QueryRowsInput,
14
14
  RowSet,
15
15
  StatementExecution,
16
+ new_execute_non_idempotent_step,
16
17
  new_execute_step,
17
18
  new_query_step,
18
19
  )
19
20
 
20
21
  CONNECTION_NAME = "sqlserver-refunds"
21
22
  FLOW_TYPE = "SQLServerRecordRefundPython"
23
+ # Running this twice counts the refund twice, so it uses executeNonIdempotent.
24
+ ADD_REFUND_TO_DAILY_TOTAL = (
25
+ "MERGE dbo.refund_daily_totals WITH (HOLDLOCK) AS totals "
26
+ "USING (SELECT CAST(SYSUTCDATETIME() AS date) AS refund_date, "
27
+ "CAST(@p1 AS decimal(14, 2)) AS amount_usd) AS refund "
28
+ "ON totals.refund_date = refund.refund_date "
29
+ "WHEN MATCHED THEN UPDATE SET total_usd = totals.total_usd + refund.amount_usd "
30
+ "WHEN NOT MATCHED THEN INSERT (refund_date, total_usd) VALUES (refund.refund_date, refund.amount_usd);"
31
+ )
22
32
 
23
33
 
24
34
  @dataclass(frozen=True, slots=True)
@@ -45,6 +55,11 @@ def execute_input(request: RefundRequest) -> ExecuteStatementInput:
45
55
  )
46
56
 
47
57
 
58
+ def daily_total_input(request: RefundRequest) -> ExecuteStatementInput:
59
+ """Add the refund's exact amount to today's total; the MERGE touches one row."""
60
+ return ExecuteStatementInput(ADD_REFUND_TO_DAILY_TOTAL, (request.amount_usd,), max_rows_affected=1)
61
+
62
+
48
63
  def query_input(request: RefundRequest) -> QueryRowsInput:
49
64
  """Read back the committed refund by its application order ID."""
50
65
  return QueryRowsInput(
@@ -67,7 +82,17 @@ class PrepareRefund(dex.Step[RefundRequest]):
67
82
 
68
83
 
69
84
  # dex:group group-id:refund group-label:"Record refund"
70
- # dex:explanation text:"Pass the retained order to the read-back Query after the write commits."
85
+ # dex:explanation text:"Pass the retained refund to the daily total after the write commits."
86
+ class PrepareDailyTotal(dex.Step[MutationResult[StatementExecution]]):
87
+ def get_step_type(self) -> str:
88
+ return "PrepareDailyTotal"
89
+
90
+ def execute(self, context: dex.Context, input: MutationResult[StatementExecution]) -> dex.StepDecision:
91
+ return dex.go_to(dex.StepRef("AddRefundToDailyTotal"), _REQUEST.get(context))
92
+
93
+
94
+ # dex:group group-id:refund group-label:"Record refund"
95
+ # dex:explanation text:"Pass the retained order to the read-back Query after the daily total commits."
71
96
  class PrepareReadBack(dex.Step[MutationResult[StatementExecution]]):
72
97
  def get_step_type(self) -> str:
73
98
  return "PrepareReadBack"
@@ -94,6 +119,7 @@ class RecordRefundFlow(dex.Flow[RefundRequest]):
94
119
  if connection.reference.name != CONNECTION_NAME:
95
120
  raise ValueError("refund Flow requires its static SQL Server connection")
96
121
  self.prepare = PrepareRefund()
122
+ self.prepare_daily_total = PrepareDailyTotal()
97
123
  self.prepare_read = PrepareReadBack()
98
124
  self.complete = CompleteRefund()
99
125
  self.execute = new_execute_step(
@@ -107,6 +133,19 @@ class RecordRefundFlow(dex.Flow[RefundRequest]):
107
133
  connection=connection,
108
134
  connection_name=CONNECTION_NAME,
109
135
  map_to_operation_input=execute_input,
136
+ completed=self.prepare_daily_total,
137
+ )
138
+ self.add_to_daily_total = new_execute_non_idempotent_step(
139
+ step_type="AddRefundToDailyTotal",
140
+ step_input_type=RefundRequest,
141
+ annotations={
142
+ "groupId": "refund",
143
+ "groupLabel": "Record refund",
144
+ "explanation": "Add the refund to today's total at most once.",
145
+ },
146
+ connection=connection,
147
+ connection_name=CONNECTION_NAME,
148
+ map_to_operation_input=daily_total_input,
110
149
  completed=self.prepare_read,
111
150
  )
112
151
  self.query = new_query_step(
@@ -128,7 +167,12 @@ class RecordRefundFlow(dex.Flow[RefundRequest]):
128
167
 
129
168
  def get_steps(self) -> dex.StepList[RefundRequest]:
130
169
  return dex.StepList.start_step(self.prepare).other_steps(
131
- self.execute, self.prepare_read, self.query, self.complete
170
+ self.execute,
171
+ self.prepare_daily_total,
172
+ self.add_to_daily_total,
173
+ self.prepare_read,
174
+ self.query,
175
+ self.complete,
132
176
  )
133
177
 
134
178
  def get_persistence_schema(self) -> dex.PersistenceSchema:
@@ -39,6 +39,11 @@ async def test_refund_flow_routes_success_retry_and_unwired_rejection(tmp_path:
39
39
  await client.start_flow(flow, success_id, RefundRequest("order-88213", "250.00"))
40
40
  success = await client.wait_for_flow(success_id, timedelta(seconds=30))
41
41
  assert success.status == dex.FlowStatus.COMPLETED, success.error_message
42
+ daily_total_calls = [
43
+ item for item in mock.execute_non_idempotent_script.calls() if item.flow_id == success_id
44
+ ]
45
+ assert len(daily_total_calls) == 1
46
+ assert daily_total_calls[0].input.parameters == ("250.00",)
42
47
 
43
48
  retry_id = f"sqlserver-python-retry-{uuid4().hex}"
44
49
  mock.execute_script.for_flow(retry_id).respond(
@@ -3,3 +3,8 @@ CREATE TABLE dbo.refund_ledger (
3
3
  amount_usd decimal(12, 2) NOT NULL,
4
4
  call_key nvarchar(36) NOT NULL UNIQUE
5
5
  );
6
+
7
+ CREATE TABLE dbo.refund_daily_totals (
8
+ refund_date date NOT NULL PRIMARY KEY,
9
+ total_usd decimal(14, 2) NOT NULL
10
+ );
@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dex-connector-microsoft-sql-server"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "Microsoft SQL Server connector for Dex Flows"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
11
11
  license = "MIT"
12
12
  license-files = ["LICENSE"]
13
- dependencies = ["dex-connectors-sdk==0.1.0", "dex-python-sdk>=1.28.0", "python-tds>=1.17.1,<1.18", "pyOpenSSL>=24,<27", "cryptography>=42,<51", "certifi>=2024.2.2", "httpx>=0.27"]
13
+ dependencies = ["dex-connectors-sdk>=0.12.0,<1", "dex-python-sdk>=1.28.0", "python-tds>=1.17.1,<1.18", "pyOpenSSL>=24,<27", "cryptography>=42,<51", "certifi>=2024.2.2", "httpx>=0.27"]
14
14
 
15
15
  [dependency-groups]
16
16
  dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.13", "ruff>=0.7"]
@@ -5,8 +5,8 @@
5
5
  from .client import Client, Config, Credentials
6
6
  from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
7
7
  from .models import Column, ExecuteStatementInput, QueryRowsInput, RowSet, StatementExecution
8
- from .operations import ExecuteStatementOperation, QueryRowsOperation
9
- from .steps import new_execute_step, new_query_step
8
+ from .operations import ExecuteStatementNonIdempotentOperation, ExecuteStatementOperation, QueryRowsOperation
9
+ from .steps import new_execute_non_idempotent_step, new_execute_step, new_query_step
10
10
 
11
11
  __all__ = [
12
12
  "Client",
@@ -20,9 +20,11 @@ __all__ = [
20
20
  "StatementExecution",
21
21
  "QueryRowsOperation",
22
22
  "ExecuteStatementOperation",
23
+ "ExecuteStatementNonIdempotentOperation",
23
24
  "new_connection",
24
25
  "new_connection_with_operations",
25
26
  "new_project_connection",
26
27
  "new_query_step",
27
28
  "new_execute_step",
29
+ "new_execute_non_idempotent_step",
28
30
  ]
@@ -9,6 +9,7 @@ from dex_connectors.sdk import (
9
9
  MutationDefinition,
10
10
  OperationRef,
11
11
  QueryDefinition,
12
+ RepeatOnUnknown,
12
13
  RetryPolicy,
13
14
  StepDefaults,
14
15
  default_connector_step_execute_retry_policy,
@@ -18,6 +19,7 @@ CONNECTOR_ID = "microsoft-sql-server"
18
19
  PROVIDER = "microsoft-sql-server"
19
20
  QUERY_OPERATION_ID = "query"
20
21
  EXECUTE_OPERATION_ID = "execute"
22
+ EXECUTE_NON_IDEMPOTENT_OPERATION_ID = "executeNonIdempotent"
21
23
  COMPLETED = "completed"
22
24
  DEFECT = "defect"
23
25
  INVALID_RESPONSE = "invalidResponse"
@@ -48,7 +50,7 @@ EXECUTE_DEFINITION = MutationDefinition(
48
50
  BranchDefinition(COMPLETED, "The server committed the statement's transaction; the Result holds the rows affected and any OUTPUT rows.", False),
49
51
  BranchDefinition(LIMIT_EXCEEDED, "The statement affected more rows than maxRowsAffected, or its OUTPUT rows exceeded maxRows or maxResponseBytes, so the connector rolled back and nothing was written.", True),
50
52
  BranchDefinition(PROVIDER_REJECTED, "The server conclusively refused the connection, statement, or commit, such as a duplicate key, a syntax error, or a permission error; nothing was written.", True),
51
- BranchDefinition(UNCERTAIN, "The connection failed after COMMIT was sent, so whether the server committed the write is unknown.", True),
53
+ BranchDefinition(UNCERTAIN, "Retained for identity stability and never selected: a COMMIT with an unknown outcome is retried, because execute statements must be repeat-safe.", True),
52
54
  BranchDefinition(INVALID_RESPONSE, "The server returned a value the connector cannot decode under its documented type mapping; the connector rolled back and nothing was written.", True),
53
55
  BranchDefinition(DEFECT, "Local input, connection configuration, or connector definition is invalid.", True),
54
56
  ),
@@ -57,4 +59,23 @@ EXECUTE_DEFINITION = MutationDefinition(
57
59
  2,
58
60
  execute_retry=default_connector_step_execute_retry_policy(),
59
61
  ),
62
+ repeat_on_unknown=RepeatOnUnknown.SAFE,
63
+ )
64
+
65
+ EXECUTE_NON_IDEMPOTENT_DEFINITION = MutationDefinition(
66
+ OperationRef(CONNECTOR_ID, EXECUTE_NON_IDEMPOTENT_OPERATION_ID),
67
+ (
68
+ BranchDefinition(COMPLETED, "The server committed the statement's transaction; the Result holds the rows affected and any OUTPUT rows.", False),
69
+ BranchDefinition(LIMIT_EXCEEDED, "The statement affected more rows than maxRowsAffected, or its OUTPUT rows exceeded maxRows or maxResponseBytes, so the connector rolled back and nothing was written.", True),
70
+ BranchDefinition(PROVIDER_REJECTED, "The server conclusively refused the connection, statement, or commit, such as a duplicate key, a syntax error, or a permission error; nothing was written.", True),
71
+ BranchDefinition(UNCERTAIN, "COMMIT may have reached the server, in this or an earlier attempt, and its outcome is unknown; the connector never runs the statement again, so inspect the database before writing again.", True),
72
+ BranchDefinition(INVALID_RESPONSE, "The server returned a value the connector cannot decode under its documented type mapping; the connector rolled back and nothing was written.", True),
73
+ BranchDefinition(DEFECT, "Local input, connection configuration, or connector definition is invalid.", True),
74
+ ),
75
+ StepDefaults(
76
+ timedelta(seconds=30),
77
+ 1,
78
+ execute_retry=default_connector_step_execute_retry_policy(),
79
+ ),
80
+ repeat_on_unknown=RepeatOnUnknown.UNSAFE,
60
81
  )
@@ -9,7 +9,7 @@ from dex_connectors.sdk.connectormock import Case, Mutation, Query
9
9
 
10
10
  from ..connection import Connection, new_connection_with_operations
11
11
  from ..models import Column, ExecuteStatementInput, QueryRowsInput, RowSet, StatementExecution
12
- from .definitions import CONNECTOR_ID, COMPLETED, DEFECT, EXECUTE_DEFINITION, INVALID_RESPONSE, LIMIT_EXCEEDED, PROVIDER_REJECTED, QUERY_DEFINITION, TRUNCATED, UNCERTAIN
12
+ from .definitions import CONNECTOR_ID, COMPLETED, DEFECT, EXECUTE_DEFINITION, EXECUTE_NON_IDEMPOTENT_DEFINITION, INVALID_RESPONSE, LIMIT_EXCEEDED, PROVIDER_REJECTED, QUERY_DEFINITION, TRUNCATED, UNCERTAIN
13
13
 
14
14
  def query_completed(value: RowSet, failure: Failure | None = None) -> Case[RowSet]:
15
15
  return Case.branch_result(COMPLETED, value, failure)
@@ -111,6 +111,51 @@ def execute_duplicate_key() -> Case[StatementExecution]:
111
111
 
112
112
  setattr(execute_duplicate_key, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
113
113
 
114
+ def execute_non_idempotent_completed(value: StatementExecution, failure: Failure | None = None) -> Case[StatementExecution]:
115
+ return Case.branch_result(COMPLETED, value, failure)
116
+
117
+ setattr(execute_non_idempotent_completed, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
118
+
119
+ def execute_non_idempotent_limit_exceeded(value: StatementExecution, failure: Failure | None = None) -> Case[StatementExecution]:
120
+ return Case.branch_result(LIMIT_EXCEEDED, value, failure)
121
+
122
+ setattr(execute_non_idempotent_limit_exceeded, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
123
+
124
+ def execute_non_idempotent_provider_rejected(value: StatementExecution, failure: Failure | None = None) -> Case[StatementExecution]:
125
+ return Case.branch_result(PROVIDER_REJECTED, value, failure)
126
+
127
+ setattr(execute_non_idempotent_provider_rejected, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
128
+
129
+ def execute_non_idempotent_uncertain(value: StatementExecution, failure: Failure) -> Case[StatementExecution]:
130
+ return Case.uncertain(value, failure)
131
+
132
+ setattr(execute_non_idempotent_uncertain, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
133
+
134
+ def execute_non_idempotent_invalid_response(value: StatementExecution, failure: Failure | None = None) -> Case[StatementExecution]:
135
+ return Case.branch_result(INVALID_RESPONSE, value, failure)
136
+
137
+ setattr(execute_non_idempotent_invalid_response, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
138
+
139
+ def execute_non_idempotent_defect(value: StatementExecution, failure: Failure | None = None) -> Case[StatementExecution]:
140
+ return Case.branch_result(DEFECT, value, failure)
141
+
142
+ setattr(execute_non_idempotent_defect, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
143
+
144
+ def execute_non_idempotent_retry(failure: Failure, after_seconds: float = 0) -> Case[StatementExecution]:
145
+ return Case.retry(failure, after_seconds)
146
+
147
+ setattr(execute_non_idempotent_retry, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
148
+
149
+ def execute_non_idempotent_added_to_daily_total() -> Case[StatementExecution]:
150
+ return Case.branch_result(COMPLETED, StatementExecution(rows_affected=1, columns=(), rows=()))
151
+
152
+ setattr(execute_non_idempotent_added_to_daily_total, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
153
+
154
+ def execute_non_idempotent_missing_daily_total_table() -> Case[StatementExecution]:
155
+ return Case.branch_result(PROVIDER_REJECTED, StatementExecution(), Failure(FailureKind.NOT_FOUND, CONNECTOR_ID, "executeNonIdempotent", "Adding to a missing refund_daily_totals table is rejected before commit."))
156
+
157
+ setattr(execute_non_idempotent_missing_daily_total_table, '__module__', "dex_connectors.microsoft_sql_server.sqlservermock")
158
+
114
159
 
115
160
  class Mock:
116
161
 
@@ -119,9 +164,12 @@ class Mock:
119
164
  self.query_script.default(query_completed_default_answer())
120
165
  self.execute_script: Mutation[ExecuteStatementInput, StatementExecution] = Mutation(EXECUTE_DEFINITION)
121
166
  self.execute_script.default(execute_completed_default_answer())
167
+ self.execute_non_idempotent_script: Mutation[ExecuteStatementInput, StatementExecution] = Mutation(EXECUTE_NON_IDEMPOTENT_DEFINITION)
168
+ self.execute_non_idempotent_script.default(execute_non_idempotent_added_to_daily_total())
122
169
  self._connection = new_connection_with_operations(
123
170
  query=self.query_script,
124
171
  execute=self.execute_script,
172
+ execute_non_idempotent=self.execute_non_idempotent_script,
125
173
  reference=ConnectionRef(CONNECTOR_ID, connection_name),
126
174
  )
127
175
 
@@ -152,4 +200,13 @@ __all__ = [
152
200
  "execute_race_lost",
153
201
  "execute_row_limit",
154
202
  "execute_duplicate_key",
203
+ "execute_non_idempotent_completed",
204
+ "execute_non_idempotent_limit_exceeded",
205
+ "execute_non_idempotent_provider_rejected",
206
+ "execute_non_idempotent_uncertain",
207
+ "execute_non_idempotent_invalid_response",
208
+ "execute_non_idempotent_defect",
209
+ "execute_non_idempotent_retry",
210
+ "execute_non_idempotent_added_to_daily_total",
211
+ "execute_non_idempotent_missing_daily_total_table",
155
212
  ]
@@ -90,6 +90,8 @@ def new_execute_step(
90
90
  defect: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
91
91
  result_attribute: dex.Attribute[MutationResult[StatementExecution]] | None = None,
92
92
  step_options_override: dex.StepOptions | None = None,
93
+ # Accepted for compatibility; ignored because the operation is safe to repeat.
94
+ max_sends_override: int | None = None,
93
95
  ) -> MutationStep[StepInput, ExecuteStatementInput, StatementExecution]:
94
96
  if connection is None or connection.reference.name != connection_name:
95
97
  raise ValueError("Microsoft SQL Server Step connection name must match its connection reference")
@@ -130,6 +132,62 @@ def new_execute_step(
130
132
 
131
133
  setattr(new_execute_step, '__module__', 'dex_connectors.microsoft_sql_server.steps')
132
134
 
135
+ def new_execute_non_idempotent_step(
136
+ *,
137
+ step_type: str,
138
+ step_input_type: type[StepInput],
139
+ annotations: StepAnnotations | Mapping[str, str],
140
+ connection: Connection,
141
+ connection_name: str,
142
+ map_to_operation_input: Callable[[StepInput], ExecuteStatementInput],
143
+ completed: dex.StepTarget[MutationResult[StatementExecution]],
144
+ limit_exceeded: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
145
+ provider_rejected: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
146
+ uncertain: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
147
+ invalid_response: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
148
+ defect: dex.StepTarget[MutationResult[StatementExecution]] | None = None,
149
+ result_attribute: dex.Attribute[MutationResult[StatementExecution]] | None = None,
150
+ step_options_override: dex.StepOptions | None = None,
151
+ ) -> MutationStep[StepInput, ExecuteStatementInput, StatementExecution]:
152
+ if connection is None or connection.reference.name != connection_name:
153
+ raise ValueError("Microsoft SQL Server Step connection name must match its connection reference")
154
+ if isinstance(annotations, StepAnnotations):
155
+ step_annotations = annotations
156
+ else:
157
+ if not isinstance(annotations, Mapping) or set(annotations) != {"groupId", "groupLabel", "explanation"}:
158
+ raise ValueError("Microsoft SQL Server Step annotations require groupId, groupLabel, and explanation")
159
+ if any(not isinstance(value, str) for value in annotations.values()):
160
+ raise ValueError("Microsoft SQL Server Step annotations must be strings")
161
+ step_annotations = StepAnnotations(annotations["groupId"], annotations["groupLabel"], annotations["explanation"])
162
+ branches = {
163
+ "completed": completed,
164
+ }
165
+ if limit_exceeded is not None:
166
+ branches["limitExceeded"] = limit_exceeded
167
+ if provider_rejected is not None:
168
+ branches["providerRejected"] = provider_rejected
169
+ if uncertain is not None:
170
+ branches["uncertain"] = uncertain
171
+ if invalid_response is not None:
172
+ branches["invalidResponse"] = invalid_response
173
+ if defect is not None:
174
+ branches["defect"] = defect
175
+ return MutationStep(
176
+ MutationStepConfig(
177
+ step_type=step_type,
178
+ step_input_type=step_input_type,
179
+ annotations=step_annotations,
180
+ operation=_bound_operation(connection, "execute_non_idempotent"),
181
+ connection=connection.reference,
182
+ map_to_operation_input=map_to_operation_input,
183
+ branches=branches,
184
+ result_attribute=result_attribute,
185
+ step_options_override=step_options_override,
186
+ )
187
+ )
188
+
189
+ setattr(new_execute_non_idempotent_step, '__module__', 'dex_connectors.microsoft_sql_server.steps')
190
+
133
191
 
134
192
  def _bound_operation(connection: Connection, operation_name: str) -> Any:
135
193
  source = getattr(connection, operation_name, None)
@@ -24,7 +24,12 @@ from ._generated.config import Config, Credentials
24
24
  from ._generated.definitions import CONNECTOR_ID, EXECUTE_DEFINITION, QUERY_DEFINITION
25
25
 
26
26
  if TYPE_CHECKING:
27
- from .operations import ExecuteStatementOperation, QueryRowsOperation, _AttemptDeadline
27
+ from .operations import (
28
+ ExecuteStatementNonIdempotentOperation,
29
+ ExecuteStatementOperation,
30
+ QueryRowsOperation,
31
+ _AttemptDeadline,
32
+ )
28
33
 
29
34
  _SESSION_SETTINGS = (
30
35
  "SET LANGUAGE us_english",
@@ -192,11 +197,17 @@ class Client:
192
197
  return QueryRowsOperation(self)
193
198
 
194
199
  def execute(self) -> ExecuteStatementOperation:
195
- """Bind the transactional write operation to this client."""
200
+ """Bind the repeat-safe transactional write operation to this client."""
196
201
  from .operations import ExecuteStatementOperation
197
202
 
198
203
  return ExecuteStatementOperation(self)
199
204
 
205
+ def execute_non_idempotent(self) -> ExecuteStatementNonIdempotentOperation:
206
+ """Bind the fenced transactional write operation, which never runs its statement twice."""
207
+ from .operations import ExecuteStatementNonIdempotentOperation
208
+
209
+ return ExecuteStatementNonIdempotentOperation(self)
210
+
200
211
  async def aclose(self) -> None:
201
212
  """Release client resources; individual calls already close their sessions."""
202
213