justybase-db2 0.1.0a1__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 (107) hide show
  1. justybase_db2-0.1.0a1/API-COMPATIBILITY.md +40 -0
  2. justybase_db2-0.1.0a1/CHANGELOG.md +41 -0
  3. justybase_db2-0.1.0a1/CONTRIBUTING.md +56 -0
  4. justybase_db2-0.1.0a1/LICENSE +21 -0
  5. justybase_db2-0.1.0a1/MANIFEST.in +24 -0
  6. justybase_db2-0.1.0a1/PKG-INFO +474 -0
  7. justybase_db2-0.1.0a1/README.md +435 -0
  8. justybase_db2-0.1.0a1/RELEASING.md +44 -0
  9. justybase_db2-0.1.0a1/SECURITY.md +38 -0
  10. justybase_db2-0.1.0a1/THIRD-PARTY-NOTICES.md +35 -0
  11. justybase_db2-0.1.0a1/api/python-surface.json +104 -0
  12. justybase_db2-0.1.0a1/docs/CROSS-DRIVER-PARITY.md +145 -0
  13. justybase_db2-0.1.0a1/docs/DRIVER-CONTRACT-STATUS.md +56 -0
  14. justybase_db2-0.1.0a1/docs/DRIVER-CONTRACT.md +446 -0
  15. justybase_db2-0.1.0a1/docs/DRIVER-GUIDE.md +201 -0
  16. justybase_db2-0.1.0a1/docs/KERBEROS.md +49 -0
  17. justybase_db2-0.1.0a1/docs/QUALIFICATION.md +202 -0
  18. justybase_db2-0.1.0a1/pyproject.toml +152 -0
  19. justybase_db2-0.1.0a1/scripts/test-db2-integration.sh +377 -0
  20. justybase_db2-0.1.0a1/scripts/test-ibm-parity.sh +184 -0
  21. justybase_db2-0.1.0a1/setup.cfg +4 -0
  22. justybase_db2-0.1.0a1/src/justybase_db2/__init__.py +224 -0
  23. justybase_db2-0.1.0a1/src/justybase_db2/_cancellation.py +113 -0
  24. justybase_db2-0.1.0a1/src/justybase_db2/_rows.py +899 -0
  25. justybase_db2-0.1.0a1/src/justybase_db2/_session.py +499 -0
  26. justybase_db2-0.1.0a1/src/justybase_db2/async_/__init__.py +47 -0
  27. justybase_db2-0.1.0a1/src/justybase_db2/async_/connection.py +2102 -0
  28. justybase_db2-0.1.0a1/src/justybase_db2/async_/cursor.py +211 -0
  29. justybase_db2-0.1.0a1/src/justybase_db2/async_/pool.py +558 -0
  30. justybase_db2-0.1.0a1/src/justybase_db2/async_/transport.py +160 -0
  31. justybase_db2-0.1.0a1/src/justybase_db2/auth/handshake.py +336 -0
  32. justybase_db2-0.1.0a1/src/justybase_db2/auth/secmec9.py +1009 -0
  33. justybase_db2-0.1.0a1/src/justybase_db2/batch.py +67 -0
  34. justybase_db2-0.1.0a1/src/justybase_db2/codecs/decfloat.py +367 -0
  35. justybase_db2-0.1.0a1/src/justybase_db2/codecs/decimal.py +110 -0
  36. justybase_db2-0.1.0a1/src/justybase_db2/codecs/ebcdic.py +289 -0
  37. justybase_db2-0.1.0a1/src/justybase_db2/command_options.py +95 -0
  38. justybase_db2-0.1.0a1/src/justybase_db2/config.py +518 -0
  39. justybase_db2-0.1.0a1/src/justybase_db2/connection.py +2064 -0
  40. justybase_db2-0.1.0a1/src/justybase_db2/cursor.py +249 -0
  41. justybase_db2-0.1.0a1/src/justybase_db2/diagnostics.py +72 -0
  42. justybase_db2-0.1.0a1/src/justybase_db2/errors.py +321 -0
  43. justybase_db2-0.1.0a1/src/justybase_db2/import_.py +688 -0
  44. justybase_db2-0.1.0a1/src/justybase_db2/lob.py +316 -0
  45. justybase_db2-0.1.0a1/src/justybase_db2/pool.py +613 -0
  46. justybase_db2-0.1.0a1/src/justybase_db2/procedure.py +574 -0
  47. justybase_db2-0.1.0a1/src/justybase_db2/protocol/codepoints.py +252 -0
  48. justybase_db2-0.1.0a1/src/justybase_db2/protocol/ddm.py +1287 -0
  49. justybase_db2-0.1.0a1/src/justybase_db2/protocol/dss.py +351 -0
  50. justybase_db2-0.1.0a1/src/justybase_db2/protocol/sql_dta.py +741 -0
  51. justybase_db2-0.1.0a1/src/justybase_db2/protocol/sql_types.py +133 -0
  52. justybase_db2-0.1.0a1/src/justybase_db2/py.typed +0 -0
  53. justybase_db2-0.1.0a1/src/justybase_db2/resources.py +230 -0
  54. justybase_db2-0.1.0a1/src/justybase_db2/statement.py +19 -0
  55. justybase_db2-0.1.0a1/src/justybase_db2/transport/__init__.py +7 -0
  56. justybase_db2-0.1.0a1/src/justybase_db2/transport/tcp.py +182 -0
  57. justybase_db2-0.1.0a1/src/justybase_db2/transport/tls.py +28 -0
  58. justybase_db2-0.1.0a1/src/justybase_db2.egg-info/SOURCES.txt +104 -0
  59. justybase_db2-0.1.0a1/tests/conftest.py +8 -0
  60. justybase_db2-0.1.0a1/tests/live/test_async_live.py +267 -0
  61. justybase_db2-0.1.0a1/tests/live/test_ibm_parity.py +919 -0
  62. justybase_db2-0.1.0a1/tests/live/test_large_data_live.py +144 -0
  63. justybase_db2-0.1.0a1/tests/live/test_live.py +442 -0
  64. justybase_db2-0.1.0a1/tests/live/test_secmec7_live.py +76 -0
  65. justybase_db2-0.1.0a1/tests/live/test_soak_live.py +63 -0
  66. justybase_db2-0.1.0a1/tests/live/test_stage_features_live.py +221 -0
  67. justybase_db2-0.1.0a1/tests/live/test_tls_live.py +56 -0
  68. justybase_db2-0.1.0a1/tests/test_async_mock.py +53 -0
  69. justybase_db2-0.1.0a1/tests/test_async_safety.py +40 -0
  70. justybase_db2-0.1.0a1/tests/test_auth_handshake.py +403 -0
  71. justybase_db2-0.1.0a1/tests/test_batch.py +119 -0
  72. justybase_db2-0.1.0a1/tests/test_cancellation.py +381 -0
  73. justybase_db2-0.1.0a1/tests/test_change_database.py +277 -0
  74. justybase_db2-0.1.0a1/tests/test_client_info.py +233 -0
  75. justybase_db2-0.1.0a1/tests/test_codecs.py +102 -0
  76. justybase_db2-0.1.0a1/tests/test_command_options.py +278 -0
  77. justybase_db2-0.1.0a1/tests/test_config.py +211 -0
  78. justybase_db2-0.1.0a1/tests/test_contract.py +36 -0
  79. justybase_db2-0.1.0a1/tests/test_errors.py +89 -0
  80. justybase_db2-0.1.0a1/tests/test_import_features.py +236 -0
  81. justybase_db2-0.1.0a1/tests/test_import_spool.py +160 -0
  82. justybase_db2-0.1.0a1/tests/test_insert.py +104 -0
  83. justybase_db2-0.1.0a1/tests/test_jdc_vectors.py +168 -0
  84. justybase_db2-0.1.0a1/tests/test_kerberos.py +112 -0
  85. justybase_db2-0.1.0a1/tests/test_mock_server.py +387 -0
  86. justybase_db2-0.1.0a1/tests/test_pool_api.py +153 -0
  87. justybase_db2-0.1.0a1/tests/test_pool_features.py +363 -0
  88. justybase_db2-0.1.0a1/tests/test_pool_reset.py +198 -0
  89. justybase_db2-0.1.0a1/tests/test_protocol.py +265 -0
  90. justybase_db2-0.1.0a1/tests/test_resources.py +276 -0
  91. justybase_db2-0.1.0a1/tests/test_rows.py +188 -0
  92. justybase_db2-0.1.0a1/tests/test_schema.py +106 -0
  93. justybase_db2-0.1.0a1/tests/test_secmec9.py +39 -0
  94. justybase_db2-0.1.0a1/tests/test_session_features.py +760 -0
  95. justybase_db2-0.1.0a1/tests/test_tls.py +211 -0
  96. justybase_db2-0.1.0a1/tests/test_transaction.py +289 -0
  97. justybase_db2-0.1.0a1/tests/test_vectors.py +159 -0
  98. justybase_db2-0.1.0a1/tests/tls_fixtures.py +189 -0
  99. justybase_db2-0.1.0a1/tests/vectors/JDC-v1.vectors.json +730 -0
  100. justybase_db2-0.1.0a1/tests/vectors/JDC-v1.vectors.json.sha256 +1 -0
  101. justybase_db2-0.1.0a1/tests/vectors/driver-v1.vectors.json +654 -0
  102. justybase_db2-0.1.0a1/tests/vectors/driver-v1.vectors.json.sha256 +1 -0
  103. justybase_db2-0.1.0a1/tools/api/generate_python_surface.py +105 -0
  104. justybase_db2-0.1.0a1/tools/consumer_smoke.py +30 -0
  105. justybase_db2-0.1.0a1/tools/sbom/check_package_contents.py +113 -0
  106. justybase_db2-0.1.0a1/tools/security/check_no_committed_keys.py +89 -0
  107. justybase_db2-0.1.0a1/tools/testing/check_no_pytest_skips.py +45 -0
@@ -0,0 +1,40 @@
1
+ # API compatibility policy — JustyBase.Db2 for Python
2
+
3
+ The project mechanically tracks its consumer-visible Python API so accidental
4
+ public-surface changes fail CI.
5
+
6
+ Two artifacts work together:
7
+
8
+ - `api/python-surface.json` — a canonical snapshot of the public names (and
9
+ the signatures of selected callables) exported by `justybase_db2` and
10
+ `justybase_db2.async_`.
11
+ - `tools/api/generate_python_surface.py --check` — regenerates the surface and
12
+ fails when it drifts from the committed snapshot.
13
+
14
+ ## Stability tiers
15
+
16
+ | Tier | Surface | Alpha policy |
17
+ | --- | --- | --- |
18
+ | Supported alpha | `connect`, `Connection`, `Cursor`, `parse_dsn`, `Pool` / `AsyncPool` (including their one-shot helpers, `connection_factory` and `clear_all_*_pools`), `Db2Diagnostic` / `observe_diagnostics`, structured errors, `import_rows`, `blob`/`clob`/`xml`, the `async_` API | Changes must be deliberate, documented, and reflected in the snapshot. |
19
+ | Experimental | Kerberos/GSSAPI, trusted-context switching, `CancelToken` command cancellation, interrupt edge semantics, LOB streaming controls | May change between alpha releases, but changes must remain explicit and documented. |
20
+ | Internal | `justybase_db2.protocol.*`, `justybase_db2.codecs.*`, `justybase_db2.transport.*`, `justybase_db2.auth.*` | Not the recommended application API and may be reduced or internalized before 1.0. |
21
+
22
+ Before 1.0, Semantic Versioning permits breaking changes through minor-version
23
+ changes. `0.1.0a1` is intentionally not a stable 1.0 contract.
24
+
25
+ ## Commands
26
+
27
+ ```bash
28
+ python3 tools/api/generate_python_surface.py
29
+ python3 tools/api/generate_python_surface.py --check
30
+ ```
31
+
32
+ ## Change process
33
+
34
+ 1. Decide whether the API change is intentional.
35
+ 2. Update implementation and tests.
36
+ 3. Update the README, changelog, and affected guides.
37
+ 4. Regenerate the snapshot in the same reviewed change.
38
+ 5. Provide migration/deprecation guidance for supported-alpha consumers.
39
+
40
+ Do not blindly regenerate the snapshot only to make CI pass.
@@ -0,0 +1,41 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ Semantic Versioning; pre-1.0 releases use `0.MINOR.PATCH`.
6
+
7
+ ## [0.1.0a1]
8
+
9
+ Initial alpha release of `justybase-db2`.
10
+
11
+ ### Added
12
+
13
+ - Pure-Python DRDA/DDM driver for IBM Db2 LUW over TCP/TLS. No IBM CLI, ODBC,
14
+ JDBC or other native client runtime is required.
15
+ - PEP 249 / DB-API 2.0 synchronous API with `?` parameters, transactions,
16
+ cursors and structured errors, plus an independent `asyncio` API sharing the
17
+ same codecs, parser and row decoder.
18
+ - Authentication with SECMEC 3, SECMEC 7 and SECMEC 9, an automatic
19
+ `SERVER_ENCRYPT` fallback before credentials are sent, and a caller-supplied
20
+ token path for SECMEC 11 / GSSAPI. TLS 1.2/1.3 validates certificates and
21
+ hostnames.
22
+ - Direct and prepared SQL, stored procedures with OUT/INOUT parameters and
23
+ dynamic result sets, incremental row streaming, progressive LOB readers and
24
+ bounded materialization.
25
+ - Bounded batch execution and bounded row import with atomic or checkpoint
26
+ policies, quoted targets, expected type checks and on-disk LOB staging under
27
+ a process-wide spool quota.
28
+ - Synchronous and asyncio connection pools with bounded admission,
29
+ server-observed register baselines, reset-on-release, idle/lifetime reaping,
30
+ one-shot command helpers, injectable connection factories, global cleanup
31
+ helpers and metadata-only diagnostic observers.
32
+ - General command cancellation with `CancelToken`, idempotent and
33
+ thread/task-safe DRDA interrupts, and stable SQLCODE/SQLSTATE, error category
34
+ and `outcome` classification.
35
+ - Self-contained JDC v1 contract copy, shared behaviour vectors, a public API
36
+ snapshot and reproducible offline qualification.
37
+
38
+ ### Compatibility
39
+
40
+ Python 3.11–3.15. IBM Db2 LUW 12.1.5 on Linux x64 is the maintained live
41
+ baseline; protocol and API coverage is also exercised on Windows and macOS.
@@ -0,0 +1,56 @@
1
+ # Contributing
2
+
3
+ ## Development setup
4
+
5
+ ```bash
6
+ python -m venv .venv
7
+ . .venv/bin/activate
8
+ pip install -e ".[dev]"
9
+ ```
10
+
11
+ ## Checks
12
+
13
+ Run these before submitting a change:
14
+
15
+ ```bash
16
+ ruff check src tests
17
+ ruff format --check src tests
18
+ mypy
19
+ PYTHONPATH=src python3 -m pytest tests -q
20
+ python3 -m build
21
+ ```
22
+
23
+ Live Db2 qualification (Linux x64, Docker):
24
+
25
+ ```bash
26
+ ./scripts/test-db2-integration.sh
27
+ ./scripts/test-db2-integration.sh --full
28
+ ```
29
+
30
+ ## Guidelines
31
+
32
+ - Follow the surrounding code style: four-space indentation, `snake_case`
33
+ functions, `PascalCase` types, full type annotations on the public API.
34
+ - Every protocol change needs an offline test (golden frame, codec vector, or
35
+ decoder case) and, where applicable, a live test.
36
+ - Never weaken fail-closed session handling. If DRDA synchronization cannot be
37
+ proven after an error, timeout, cancellation, or interrupted stream, the
38
+ session must not return to a pool.
39
+ - Do not add runtime dependencies without a strong justification; the driver is
40
+ pure Python with an empty mandatory dependency set.
41
+ - Keep credentials out of commits, logs, and test fixtures. TLS fixtures are
42
+ generated ephemerally during tests.
43
+
44
+ ## Commit messages
45
+
46
+ Use focused commits with a prefix such as `fix:`, `test:`, `docs:`, `build:`, or
47
+ `api:`.
48
+
49
+ ## Pull requests
50
+
51
+ - Keep each change focused and include tests for behaviour changes.
52
+ - Do not commit credentials, private keys, live DSNs, or production data.
53
+ - By contributing, you agree that your contribution is licensed under the
54
+ project's MIT License.
55
+ - Report security-sensitive issues through the private channel described in
56
+ `SECURITY.md`, not in an issue or pull request.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Krzysztof Dusko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,24 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CHANGELOG.md
4
+ include CONTRIBUTING.md
5
+ include SECURITY.md
6
+ include THIRD-PARTY-NOTICES.md
7
+ include API-COMPATIBILITY.md
8
+ include RELEASING.md
9
+ include pyproject.toml
10
+
11
+ recursive-include src *.py py.typed
12
+ recursive-include tests *.py *.json *.sha256
13
+ recursive-include docs *.md
14
+ recursive-include api *.json
15
+ recursive-include scripts *.sh
16
+ recursive-include tools *.py
17
+
18
+ prune .github
19
+ prune build
20
+ prune dist
21
+ prune target
22
+ prune src/justybase_db2.egg-info
23
+
24
+ global-exclude __pycache__ *.py[cod] .DS_Store Thumbs.db .coverage *.log
@@ -0,0 +1,474 @@
1
+ Metadata-Version: 2.4
2
+ Name: justybase-db2
3
+ Version: 0.1.0a1
4
+ Summary: Native IBM Db2 LUW driver for Python speaking DRDA/DDM directly over TCP/TLS
5
+ Author: Krzysztof Dusko
6
+ License-Expression: MIT
7
+ Keywords: db2,ibm,drda,ddm,database,dbapi,asyncio
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3 :: Only
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Programming Language :: Python :: 3.15
17
+ Classifier: Topic :: Database
18
+ Classifier: Topic :: Database :: Front-Ends
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ License-File: THIRD-PARTY-NOTICES.md
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=9.2.0; extra == "dev"
27
+ Requires-Dist: pytest-asyncio>=1.4.1.post1; extra == "dev"
28
+ Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
29
+ Requires-Dist: coverage[toml]>=7.17.2; extra == "dev"
30
+ Requires-Dist: ruff>=0.17.4; extra == "dev"
31
+ Requires-Dist: mypy>=2.4.1; extra == "dev"
32
+ Requires-Dist: build>=1.6.1; extra == "dev"
33
+ Requires-Dist: twine>=7.0.0; extra == "dev"
34
+ Requires-Dist: pip-audit>=2.10.1; extra == "dev"
35
+ Provides-Extra: ibm-parity
36
+ Requires-Dist: ibm_db>=3.3.0; extra == "ibm-parity"
37
+ Requires-Dist: pytest>=9.2.0; extra == "ibm-parity"
38
+ Dynamic: license-file
39
+
40
+ # JustyBase.Db2 for Python
41
+
42
+ [![status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/justybase-db2/)
43
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit)
44
+ [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.15-blue)](https://www.python.org/downloads/)
45
+
46
+ > **Alpha software.** APIs and protocol coverage may change before a stable
47
+ > release. Validate the driver against your own Db2 environment and workload
48
+ > before production use.
49
+
50
+ Native **IBM Db2 LUW** driver for Python that speaks **DRDA/DDM** directly over
51
+ TCP/TLS. It does **not** require IBM CLI, ODBC, JDBC, the IBM .NET driver, or any
52
+ other Db2 client runtime — the protocol is implemented in pure Python.
53
+
54
+ - PyPI package: **`justybase-db2`**
55
+ - Python import: **`justybase_db2`**
56
+
57
+ > **Independent project:** this project is not maintained, endorsed, sponsored,
58
+ > or certified by IBM. IBM and Db2 are trademarks of International Business
59
+ > Machines Corporation.
60
+
61
+ ## Highlights
62
+
63
+ - PEP 249 / DB-API 2.0 synchronous API with `?` (qmark) parameters.
64
+ `threadsafety` is `1`: use one connection per thread, or serialize access
65
+ yourself.
66
+ - Independent, idiomatic `asyncio` API (`justybase_db2.async_`) sharing the same
67
+ DRDA codecs, parser, and row decoder.
68
+ - Direct and prepared SQL, transactions, streaming rows, LOB materialization and
69
+ progressive LOB reads, stored procedures, bounded row import, bounded batch
70
+ execution, and pooling.
71
+ - Password authentication (SECMEC 3), DES-encrypted password (SECMEC 7), and
72
+ encrypted EUSRIDPWD (SECMEC 9). A connection without a configured mechanism
73
+ follows an `AUTHENTICATION=SERVER_ENCRYPT` server by retrying with 9 (or 7)
74
+ before any credentials are sent, like IBM CLI.
75
+ - TLS 1.2/1.3 with certificate validation.
76
+ - General-purpose `CancelToken` for sync and asyncio commands, batches, imports
77
+ and streaming reads, with an idempotent, thread/task-safe DRDA interrupt.
78
+ - Structured SQLCODE/SQLSTATE errors and fail-closed session cleanup when DRDA
79
+ stream synchronization cannot be proven.
80
+ - Bounded materialization (16 MiB per LOB, 32 MiB per result set), a 1 GiB
81
+ streamed-LOB budget with 64 KiB chunks, and a shared 10 GiB spool
82
+ `ResourceBudget` that importers reserve against for staged LOB values.
83
+ DSN protocol-limit keys are validated against documented hard ceilings.
84
+ - Deterministic offline DRDA replay tests and a live Db2 LUW qualification
85
+ harness. Protocol/API smoke tests on Linux, Windows, and macOS.
86
+
87
+ ## Requirements
88
+
89
+ - Python **3.11–3.15**. No mandatory third-party runtime dependency.
90
+ - An IBM Db2 LUW server reachable over TCP or TLS.
91
+
92
+ The maintained live qualification baseline is **Db2 LUW 12.1.5 on Linux x64**.
93
+ Windows and macOS are exercised by protocol/API smoke tests. See
94
+ `docs/QUALIFICATION.md`.
95
+
96
+ ## Compatibility
97
+
98
+ The driver targets Python 3.11–3.15 and IBM Db2 LUW. Live and offline
99
+ qualification details are in `docs/QUALIFICATION.md`; the supported API surface
100
+ and stability tiers are in `API-COMPATIBILITY.md`.
101
+
102
+ ## Cross-driver contract
103
+
104
+ The observable behaviour implemented here is defined by [JDC v1](docs/DRIVER-CONTRACT.md);
105
+ known gaps are recorded in [the status file](docs/DRIVER-CONTRACT-STATUS.md) and
106
+ cross-driver differences in [the parity matrix](docs/CROSS-DRIVER-PARITY.md).
107
+ The self-contained contract and shared behaviour vectors are checked by the
108
+ offline suite (`tests/test_jdc_vectors.py`).
109
+
110
+ ## Installation
111
+
112
+ During the alpha phase, install with `--pre` so pip selects the pre-release:
113
+
114
+ ```bash
115
+ pip install --pre justybase-db2
116
+ ```
117
+
118
+ ```python
119
+ import justybase_db2
120
+ ```
121
+
122
+ ## DB-API quick start
123
+
124
+ ```python
125
+ import justybase_db2
126
+
127
+ conn = justybase_db2.connect("db2://user:password@localhost:50000/TESTDB")
128
+ cursor = conn.cursor()
129
+ cursor.execute(
130
+ "SELECT ID, NAME FROM APP.CUSTOMERS WHERE ID = ?",
131
+ (42,),
132
+ )
133
+ for row in cursor:
134
+ print(row)
135
+ conn.close()
136
+ ```
137
+
138
+ ## Async quick start
139
+
140
+ ```python
141
+ from justybase_db2.async_ import connect
142
+
143
+ async with await connect("db2://user:password@localhost:50000/TESTDB") as conn:
144
+ async with conn.cursor() as cur:
145
+ await cur.execute("SELECT ID, NAME FROM APP.CUSTOMERS WHERE ID = ?", (42,))
146
+ async for row in cur:
147
+ print(row)
148
+ ```
149
+
150
+ ## Prepared statements
151
+
152
+ ```python
153
+ statement = conn.prepare("SELECT NAME FROM APP.CUSTOMERS WHERE ID = ?")
154
+ result = conn.query_prepared(statement, (42,))
155
+ ```
156
+
157
+ ## Per-command options
158
+
159
+ Every `Connection` / `AsyncConnection` / `Cursor` operation accepts an optional
160
+ `CommandOptions` argument:
161
+
162
+ ```python
163
+ from justybase_db2 import CommandOptions
164
+
165
+ result = conn.query(
166
+ "SELECT * FROM APP.BIG",
167
+ options=CommandOptions(timeout_ms=5000), # None = connection timeout, 0 = no deadline
168
+ )
169
+ conn.execute(
170
+ "INSERT INTO APP.T VALUES (?)",
171
+ (1,),
172
+ options=CommandOptions(user="BATCH", client_info={"application_name": "loader"}),
173
+ )
174
+ ```
175
+
176
+ The per-command user and client registers are applied before the operation and
177
+ stay on the session afterwards (sticky). Omitted or empty client-info fields
178
+ keep their current value.
179
+
180
+ ## Transactions
181
+
182
+ ```python
183
+ conn.autocommit = False
184
+ try:
185
+ conn.execute("INSERT INTO APP.T VALUES (?)", (1,))
186
+ conn.execute("INSERT INTO APP.T VALUES (?)", (2,))
187
+ conn.commit()
188
+ except justybase_db2.Error:
189
+ conn.rollback()
190
+ raise
191
+ ```
192
+
193
+ Or use an explicit transaction scope:
194
+
195
+ ```python
196
+ with conn.begin_transaction("CS") as tx:
197
+ tx.execute("INSERT INTO APP.T VALUES (?)", (1,))
198
+ # committed on clean exit, rolled back on exception; isolation restored
199
+ ```
200
+
201
+ ## Pooling
202
+
203
+ ```python
204
+ from justybase_db2 import Pool, PoolOptions
205
+
206
+ pool = Pool("db2://user:password@localhost:50000/TESTDB", PoolOptions())
207
+ with pool.connection() as conn:
208
+ print(conn.query("VALUES 1").rows)
209
+
210
+ # One-shot helpers acquire and return a lease for you.
211
+ print(pool.query("VALUES 1").rows)
212
+ pool.execute("INSERT INTO APP.T VALUES (?)", (1,))
213
+ pool.with_connection(lambda conn: conn.current_schema)
214
+
215
+ # query_stream keeps the lease until the reader is exhausted or closed.
216
+ for row in pool.query_stream("SELECT ID FROM APP.T"):
217
+ print(row)
218
+
219
+ print(pool.stats) # connections, idle, active, waiting, discarded, ...
220
+ pool.drain_idle() # close idle sessions, keep the pool usable
221
+ pool.shutdown(10) # stop admission, wait for leases, close everything
222
+ ```
223
+
224
+ The asyncio pool has the same helpers (`query`, `execute`, `execute_batch`,
225
+ `call_procedure`, `query_stream`, `with_connection`):
226
+
227
+ ```python
228
+ from justybase_db2.async_ import AsyncPool, PoolOptions
229
+
230
+ pool = AsyncPool(dsn, PoolOptions(max_size=8))
231
+ async with await pool.acquire() as conn:
232
+ await conn.query("VALUES 1")
233
+ print((await pool.query("VALUES 1")).rows)
234
+ await pool.shutdown(10)
235
+ ```
236
+
237
+ `PoolOptions.connection_factory` accepts a callable
238
+ `factory(config, connect_timeout_ms=...)` for injecting custom connections;
239
+ `clear_all_pools()` / `clear_all_async_pools()` shut down every live pool.
240
+ `observe_diagnostics()` subscribes to metadata-only timing events (`connect`,
241
+ `acquire`, `execute`, `reset`, `discard`) without ever receiving SQL or credentials.
242
+
243
+ `PoolStats` exposes `connections`, `idle`, `active`, `waiting`, `discarded`,
244
+ `acquire_timeouts`, `exhausted`, and `created`. Defaults are 10 connections,
245
+ 100 waiters, 30 s acquire, 10 s connect, 300 s idle, 1800 s lifetime and 30 s
246
+ reap. An idle/lifetime reaper runs in the background (`reap_interval`); expiry
247
+ is also enforced on acquire and release. Every pool interval, including
248
+ `reap_interval`, must be positive.
249
+
250
+ ## Bulk import
251
+
252
+ `ImportTarget` builds a fully quoted `INSERT`; `ImportPolicy` chooses one atomic
253
+ transaction or a commit per bounded batch:
254
+
255
+ ```python
256
+ from justybase_db2 import ImportOptions, ImportPolicy, ImportTarget, import_rows
257
+
258
+ target = ImportTarget(
259
+ schema="APP", table="CUSTOMERS", columns=["ID", "NAME"],
260
+ expected_sql_types=[496, 448], # checked before the first write
261
+ )
262
+ progress = import_rows(
263
+ conn, target, source_rows,
264
+ ImportOptions(
265
+ policy=ImportPolicy.ATOMIC,
266
+ max_batch_rows=256,
267
+ max_batch_bytes=8 * 1024 * 1024, # soft: one oversized row is sent alone
268
+ table_lock=True, # exclusive lock inside the transaction
269
+ notify_after_rows=10_000,
270
+ on_progress=print,
271
+ ),
272
+ )
273
+ print(progress.committed_rows, progress.committed_batches)
274
+ ```
275
+
276
+ `ImportOptions.commit_every`/`observer` remain supported; the default policy is
277
+ `ATOMIC` and progress is reported every 10,000 rows. Pass `policy=None`
278
+ explicitly to use the commit-every-`commit_every` mode.
279
+ `async_import_rows` accepts a sync or async row source. `table_lock` requires
280
+ `ImportPolicy.ATOMIC` and an `ImportTarget`; invalid combinations fail before
281
+ any I/O.
282
+
283
+ With an `ImportTarget`, each batch is sent as a multi-row
284
+ `INSERT ... VALUES (...), (...)` statement (at most 1024 rows per statement),
285
+ with one cached prepared statement per chunk size. A plain SQL string still
286
+ uses one prepared insert per row.
287
+
288
+ ## Streaming and large objects
289
+
290
+ ```python
291
+ reader = conn.query_stream("SELECT ID, PAYLOAD FROM APP.BLOB_TABLE")
292
+ for row in reader:
293
+ print(row[0], len(row[1]))
294
+ ```
295
+
296
+ Materialized LOBs are bounded to 16 MiB and a materialized result set to 32 MiB.
297
+ Larger values use the streaming reader and progressive LOB locators.
298
+
299
+ Bind a file or stream as a LOB parameter:
300
+
301
+ ```python
302
+ from justybase_db2 import blob
303
+
304
+ conn.execute("INSERT INTO APP.BLOB_TABLE VALUES (?, ?)", (1, blob("/path/data.bin")))
305
+ ```
306
+
307
+ Streamed LOB parameters are written as bounded EXTDTA/DSS segments (64 KiB by
308
+ default) and never materialized in memory. `ProtocolLimits.max_streamed_lob_bytes`
309
+ (default 1 GiB) rejects an oversized source before any SQL is sent, and
310
+ `lob_chunk_bytes` tunes the read size. A reader opened by the driver (a path or
311
+ in-memory buffer passed to `blob`/`clob`/`xml`) is closed after the value has
312
+ been streamed; a reader supplied by the caller stays open. Pass
313
+ `CommandOptions(cancel=CancelToken())` to abort a stream between chunks
314
+ deterministically.
315
+
316
+ ## Cancellation
317
+
318
+ ```python
319
+ handle_conn.interrupt() # sends a DRDA SQL interrupt using the session token
320
+
321
+ from justybase_db2 import CancelToken, CommandOptions
322
+ token = CancelToken()
323
+ conn.execute_prepared(statement, params, options=CommandOptions(cancel=token))
324
+ token.cancel() # interrupts the running command from any thread/task
325
+ ```
326
+
327
+ The same token works for sync and asyncio commands, `execute_batch`, imports
328
+ (`ImportOptions(cancel=token)`) and streaming reads. Cancellation before any
329
+ request is written is `not_started`; a confirmed `-952` is `OPERATION_CANCELLED`
330
+ with outcome `confirmed`. `interrupt()` is idempotent and thread/task-safe.
331
+
332
+ An interrupt acknowledgment does not by itself prove that the original command
333
+ has stopped; await the original operation, which may also complete normally if
334
+ it won the race.
335
+
336
+ ## TLS
337
+
338
+ Use `db2s://` and configure a trusted CA:
339
+
340
+ ```python
341
+ justybase_db2.connect(
342
+ "db2s://user:password@db2.example.com:50001/PRODDB"
343
+ "?ssl_root_ca=/etc/db2/ca.pem"
344
+ )
345
+ ```
346
+
347
+ IBM CLI-style key/value strings are accepted for a documented subset, including
348
+ `Security=SSL` and `SSLServerCertificate=...`. Unsupported security modes fail
349
+ validation instead of silently falling back to plaintext.
350
+
351
+ ## Authentication
352
+
353
+ Mechanism selection:
354
+
355
+ - not set (default): request `3` (`USRIDPWD`). If an
356
+ `AUTHENTICATION=SERVER_ENCRYPT` server refuses it and lists `9` or `7`, send
357
+ a second `ACCSEC` on the same connection with `9`, else `7`, before any
358
+ credentials are sent.
359
+ - `3` (`Authentication=SERVER`): cleartext user ID and password on the DRDA
360
+ stream.
361
+ - `7` (`usrencpwd`, `encrypted_password_security`): cleartext user ID and a
362
+ DES-CBC-encrypted password (`ENCALG=1`). AES (`ENCALG=2`) fails closed before
363
+ credentials are sent.
364
+ - `9` (`Authentication=SERVER_ENCRYPT`, `secmec9`): Diffie-Hellman key
365
+ agreement and encrypted user ID and password.
366
+ - `11` (`kerberos`, `gssapi`): caller-supplied GSSAPI token file; see
367
+ `docs/KERBEROS.md`. The driver never acquires tickets itself.
368
+
369
+ An explicitly configured mechanism, including `3`, is never changed. When the
370
+ server refuses it, the error names every mechanism the server accepts and the
371
+ `SECCHKCD`, before `SECCHK` is sent.
372
+
373
+ ```python
374
+ justybase_db2.connect("db2://user:password@host:50000/TESTDB?security_mechanism=7")
375
+ ```
376
+
377
+ ## Insert with identity
378
+
379
+ ```python
380
+ result = conn.execute_insert("INSERT INTO APP.T (VAL) VALUES (?)", (7,))
381
+ print(result.rows_affected, result.last_insert_id) # via IDENTITY_VAL_LOCAL()
382
+ cursor.execute_insert("INSERT INTO APP.T (VAL) VALUES (8)")
383
+ print(cursor.lastrowid)
384
+ ```
385
+
386
+ ## Stored procedures
387
+
388
+ `OUT` and `INOUT` parameters are supported:
389
+
390
+ ```python
391
+ result = conn.call_procedure("CALL APP.GET_CUSTOMER(?, ?)", (42, None))
392
+ print(result.output_parameters)
393
+ ```
394
+
395
+ Dynamic (cursor-returning) result sets are materialized in
396
+ `ProcedureResult.result_sets`; `call_procedure_stream` yields them lazily:
397
+
398
+ ```python
399
+ for event, columns, row in conn.call_procedure_stream("CALL APP.LIST_CUSTOMERS()"):
400
+ print(event, columns, row)
401
+ ```
402
+
403
+ ## Supported types
404
+
405
+ | Db2 type | Python type |
406
+ | --- | --- |
407
+ | `SMALLINT` / `INTEGER` / `BIGINT` | `int` |
408
+ | `REAL` / `DOUBLE` / `FLOAT` | `float` |
409
+ | `DECIMAL` / `NUMERIC` | `decimal.Decimal` |
410
+ | `DECFLOAT` | `decimal.Decimal` |
411
+ | `CHAR` / `VARCHAR` / `CLOB` / `GRAPHIC` / `DBCLOB` / `XML` | `str` |
412
+ | `BINARY` / `VARBINARY` / `BLOB` | `bytes` |
413
+ | `BOOLEAN` | `bool` |
414
+ | `DATE` | `datetime.date` |
415
+ | `TIME` | `datetime.time` |
416
+ | `TIMESTAMP` | `datetime.datetime` |
417
+ | `NULL` | `None` |
418
+
419
+ ## Known limitations
420
+
421
+ - Db2 for z/OS and Db2 for IBM i are **not** verified and are not claimed as
422
+ supported. Only Db2 LUW 12.1.5 is in the live baseline.
423
+ - Kerberos / GSSAPI (SECMEC 11) is experimental and requires a caller-supplied
424
+ GSSAPI token file; there is no hidden fallback to password authentication.
425
+ - Trusted-context user switching requires matching server configuration and is
426
+ experimental.
427
+ - Stored-procedure support covers OUT/INOUT parameters and dynamic result sets;
428
+ exotic procedure shapes may still be incomplete.
429
+
430
+ ## Testing
431
+
432
+ Offline protocol and API tests:
433
+
434
+ ```bash
435
+ PYTHONPATH=src python3 -m pytest tests -q
436
+ ruff check src tests
437
+ mypy
438
+ python3 -m build
439
+ ```
440
+
441
+ Live Db2 tests start an isolated, pinned Db2 Community container:
442
+
443
+ ```bash
444
+ ./scripts/test-db2-integration.sh # smoke suite
445
+ ./scripts/test-db2-integration.sh --full # full live suite + second DB
446
+ ./scripts/test-db2-integration.sh --secmec7 # SERVER_ENCRYPT lane
447
+ ./scripts/test-db2-integration.sh --tls # TLS lane
448
+ ./scripts/test-db2-integration.sh --large-data # 1 GiB streamed BLOB lane
449
+ ./scripts/test-db2-integration.sh --soak # pool/LOB soak lane
450
+ ```
451
+
452
+ Running the IBM image means accepting its applicable license terms.
453
+
454
+ ## Documentation
455
+
456
+ - `docs/QUALIFICATION.md` — qualification and compatibility
457
+ - `docs/DRIVER-GUIDE.md` — advanced driver guide
458
+ - `docs/DRIVER-CONTRACT.md` — JDC v1 observable-behaviour contract
459
+ - `docs/DRIVER-CONTRACT-STATUS.md` — repo-specific JDC conformance record
460
+ - `docs/KERBEROS.md` — SECMEC 11 / GSSAPI token path and limitations
461
+ - `docs/CROSS-DRIVER-PARITY.md` — cross-driver feature matrix and known divergences
462
+ - `API-COMPATIBILITY.md` — API compatibility policy
463
+ - `RELEASING.md` — manual release checklist
464
+ - `CONTRIBUTING.md` — contributing
465
+ - `SECURITY.md` — security policy
466
+ - `CHANGELOG.md` — changelog
467
+
468
+ ## License and provenance
469
+
470
+ Licensed under the [MIT License](https://opensource.org/license/mit). The
471
+ implementation uses the MIT-licensed [`go-db2`](https://github.com/go-db2/go-db2)
472
+ project as a primary DRDA protocol reference; required notices are retained in
473
+ `THIRD-PARTY-NOTICES.md`. This project does not bundle IBM CLI libraries or IBM
474
+ driver binaries.