Copyright of this product 2013-2023,
Machbase Corporation(or Inc.) or its subsidiaries.
All Rights reserved.
http://www.machbase.com
support@machbase.com
Machbase Python API 2.4 (English introduction)
This package is a pure Python implementation of Machbase client protocol and provides a
drop-in replacement API compatible with the legacy Python API.
Python compatibility
- Supported runtime baseline is Python 3.6 or later.
- The source code avoids Python 3.7+ only syntax and does not depend on `dataclasses`.
- The package can be imported directly via `PYTHONPATH` on Python 3.6.x without extra backport packages.
Key changes in version 2.4
1. Reusable prepared cursor
- `connection.cursor(prepared=True)` creates a cursor that keeps one server-side
prepared statement and reuses it while the SQL text remains unchanged.
- A different SQL operation frees the previous statement before preparing the new one.
- Closing the cursor frees the cached statement. Closing the cursor after its connection
has already closed is also safe.
2. Parameter markers
- Prepared cursors accept DB-API positional `%s`, native positional `?`,
DB-API named `%(name)s`, and native named `:name` markers.
- Marker-like text inside quoted strings and SQL comments is preserved.
- Named and positional marker styles cannot be mixed in one operation.
- Named binds require Machbase protocol 4.0.3 or newer.
3. Machbase 8.7 support
- ARRAY values support bind/fetch and sparse input through `SparseArray`.
- ARRAY APPEND supports projected element targets. Public positions are 0-based.
- ARRAY operations require protocol 4.0.4 or newer.
- Cursor `lastrowid` exposes server-provided generated row IDs.
- Result metadata identifies primary keys; connections support database selection.
4. Package metadata
- SDK version is `2.4`; the DBMS release version is `8.7`.
- Install with `python -m pip install machbaseapi==2.4` after publication.
Key changes in version 2.3
1. Append NULL padding
- Append rows may omit trailing columns. The omitted columns are sent as NULL through
the append null-bit metadata.
- For TAG tables, values through the summarized `value` column remain required;
later value/meta columns may be omitted.
- `appendData()` and `appendDataByTime()` send append data immediately. `appendFlush()`
is an append response synchronization point, not a delayed-send trigger.
- Fixed float/double append NULL values are restored as Python `None` when fetched.
2. Package metadata
- Version is updated to `2.3`.
Key changes in version 2.2
1. Pure Python implementation
- Native binary libraries (`.so`, `.dylib`, `.dll`) are no longer required.
- Wire protocol, packet framing, and marshal/unmarshal logic are implemented in Python modules
(`protocol.py`, `marshal.py`, `packet.py`).
- Distribution is platform independent (`py3-none-any` wheel).
2. Fully compatible with existing interfaces
- Existing entry points are preserved (`machbase`, `machbaseAPI`, `connect`, `MachbaseConnection`, `MachbaseCursor`).
- Legacy call patterns for common operations are maintained for migration (`open`, `close`, `openEx`,
`execute`, `select`, `fetch`, `append`, DB-API cursor execution/fetch).
- Existing sample scripts and test code can be executed using the new package without adapter code.
- Existing behavior for unsupported features is preserved as explicit errors.
3. Improved append API
- `append`, `appendByTime` can be used without explicit `types`.
- `appendData`, `appendDataByTime` also support optional type arguments.
- `types` can still be inferred from active append session and explicit table metadata.
- Async-friendly append path: callers can supply callbacks and receive protocol ack handling
without forcing unnecessary blocking.
- Improved row normalization and validation for mixed input forms.
4. Reliability and API strictness improvements
- Connection pooling is rejected with clear errors because pooling is intentionally not supported.
- Unknown connection options are rejected up front (fast validation).
- Expanded DB-API compatible exception mapping.
- Safer close/shutdown cleanup for sockets and sessions.
- Consistent internal encoding for bytes/binary-like values during legacy-style APIs.
5. Operational and migration notes
- Binary wheel no longer embeds platform native modules.
- Installation is lightweight and easier to mirror in CI/build pipelines.
- Version is updated to `2.2` (Python 3.6 direct-import compatibility and packaging/documentation refresh).
What changed for users migrating from 1.x
- Connection
- Use the same host/port/user/password defaults as before.
- No `lib` copy or platform-specific package setup required.
- Append
- Existing `append` usage is supported; session-based and immediate append flows remain available.
- Compatibility boundaries
- Existing scripts that relied on hidden/undocumented native behaviors may need review.
- Pooling-related keys or unsupported options will now raise immediate errors (instead of being ignored).
Known limitations and troubleshooting
- Auto commit model
- Transactions are auto-commit by protocol design for this API.
- High-volume append
- Performance gains from batching large payloads are still recommended.
- For ultra-high throughput scenarios, tune client-side batching strategy in your application.
- Error handling
- Append/append_data and query errors are surfaced through return status and callbacks according to API layer.
FAQ
- Why only `py3-none-any`?
- The package does not load platform-specific binaries anymore.
- Where can I check differences from old binaries?
- Refer to `CHANGELOG.md` and API regression test suite in `test/regress`.
For full behavioral and compatibility reference, see `CHANGELOG.md` and the regression test set.
# Changelog
## 2.4
### Added
- Added Machbase 8.7 ARRAY bind/fetch and sparse ARRAY input through `SparseArray`.
- Added projected ARRAY APPEND targets; public ARRAY positions are 0-based.
- Added cursor `lastrowid` for server-provided generated row IDs.
- Added primary-key result metadata and database selection support.
- Added `connection.cursor(prepared=True)` and the public
`MachbasePreparedCursor` type.
- Added reusable server-side prepared statement lifecycle across `execute()` and
`executemany()` calls with identical SQL text.
- Added prepared-cursor marker normalization for `%s`, `?`, `%(name)s`, and
`:name` while preserving quoted and commented marker-like text.
### Changed
- Renamed Python metadata fields, arguments, and type helpers from
`spiner_type` to `machbase_type`. Code accessing these fields or helpers
directly must use the new names; wire type values are unchanged.
- Closing a protocol prepared statement after its connection is closed now
releases local statement state without attempting network I/O.
### Fixed
- Named prepared operations on servers earlier than protocol 4.0.3 are rejected
with `NotSupportedError` and SQLSTATE `0A000` before PREPARE.
- An empty mapping for a markerless prepared operation is normalized to no
parameters, consistently with `None` and an empty sequence.
### Notes
- Named prepared parameters require protocol 4.0.3 or newer.
- Package version is set to `2.4` (SDK version, independent of DBMS version 8.7).
- ARRAY operations require protocol 4.0.4 or newer.
- Release packaging produces one platform-independent wheel. Upload credentials
are supplied externally; the upload target requires the exact package version.
## 2.3
### Changed
- Version bump from 2.2 to 2.3 for the pure-Python API package.
- Append rows may omit trailing visible/meta columns, which are sent as NULL.
- TAG append still requires input through the summarized `value` column.
- Legacy `appendFlush()` now checks pending append responses instead of returning a session-only stub result.
- Updated package metadata and release documents for the 2.3 release.
### Fixed
- Fixed append NULL fetch handling for fixed float/double sentinel values so they are restored as Python `None`.
### Notes
- Package version is set to `2.3`.
## 2.2
### Changed
- Version bump from 2.1 to 2.2 for the pure-Python API package.
- Removed remaining Python 3.7+ only syntax from the runtime modules.
- Replaced `dataclasses`-based helper containers with plain classes so `PYTHONPATH` execution also works on Python 3.6.x.
- Updated package metadata and release documents for the 2.2 release.
### Notes
- Package version is set to `2.2`.
- The source package can be imported on Python 3.6.x without extra backport dependencies.
## 2.1
### Changed
- Version bump from 2.0 to 2.1 for pure-python API package.
- Documentation and metadata were updated to reflect the 2.1 release.
### Notes
- Package version is set to `2.1`.
## 2.0.0
### Changed
- Migrated to a pure Python implementation of Machbase protocol processing.
- Removed dependency on native dynamic libraries (`.so`, `.dll`, `.dylib`) from runtime package.
- Kept legacy API compatibility as the primary migration strategy:
- `machbase` and `machbaseAPI` legacy styles
- `connect`, `MachbaseConnection`, `MachbaseCursor`
- legacy sample script behavior for connection/query/append use cases
- Improved append handling:
- more flexible row normalization in session and one-shot append paths
- async-friendly acknowledgement callback flow
- stronger validation around row/type consistency
- Strengthened connection argument validation:
- pooling-related options are explicitly rejected
- unknown keyword options are rejected with clear error messages
### Fixed
- Unified protocol implementation path to Python-only marshal/packet parsing.
- Removed native bridge-related packaging behavior and binary cleanup assumptions.
- Reduced hidden binary cleanup side effects in build artifacts and packaging files.
### Notes
- Package version is set to `2.0.0`.
- Binary distribution format remains source-compatible with legacy test artifacts when using
`PYTHONPATH`-based execution.
Metadata
Release files for machbaseapi 2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| machbaseapi-2.4-py3-none-any.whl | Python 3 | none | any | Details for machbaseapi-2.4-py3-none-any.whl |
Release files / machbaseapi-2.4-py3-none-any.whl
| Download URL | machbaseapi-2.4-py3-none-any.whl |
|---|---|
| Size | 34.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8afee218db9badfd36f945c63c73f1b0b8eb31b4a548bffc5e2961322034d921
|
|
BLAKE2b-256 checksum How to use checksums |
5254f7bc9c12eab049ed171b212b0304e98133e0bc8a4d6ee28849f921faf42d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.10.0 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/1.0.0 urllib3/1.26.20 tqdm/4.64.1 importlib-metadata/4.8.3 keyring/23.4.1 rfc3986/1.5.0 colorama/0.4.5 CPython/3.6.8
|
Security for machbaseapi 2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.