nz_rust
Pure Rust client driver for IBM Netezza and PureData System for Analytics.
[!WARNING] Preview software. This crate is under active development and its public API, protocol coverage and behavior may change between releases. It is ready for evaluation, integration work and controlled internal use; validate it against your Netezza environment before using it in production.
What it is
nz_rust is a dependency-light Rust driver for the Netezza simple-query
protocol. It provides a synchronous client, a Tokio-compatible async facade,
connection pools, catalog metadata, cancellation and bounded-memory result
streaming.
The project is intended for Rust applications, workbench integrations and tools that need direct Netezza connectivity without an ODBC bridge.
The crate implements the Netezza simple-query protocol, including the
handshake and authentication flow, text and binary result formats, Netezza
numeric decoding, catalog metadata, transactions, cancellation, connection
pools and bounded row streaming. Its compatibility surface was checked against
the C# JustyBase.NetezzaDriver and the Node/TypeScript
@justybase/netezza-driver.
Status and support expectations
The protocol and metadata surface is covered by unit tests, mock-server tests and opt-in live Netezza integration tests. The current implementation includes the following areas:
| Area | Status | Notes |
|---|---|---|
| Synchronous queries and commands | Available | Buffered and streaming APIs |
| Native Tokio client | Available | Client/Connection follow tokio-postgres' split driver model |
| Legacy async facade | Available | AsyncNzConnection uses Tokio's blocking pool for compatibility |
| Connection pooling | Available | Sync and async pools |
| Transactions and cancellation | Available | Recreate a connection after an unsynchronized protocol failure |
| Catalog metadata | Available | Schemas, tables, columns and additional catalog helpers |
| TLS | Opt-in | Enable the ssl feature |
| Netezza appliance coverage | Preview | Verify behavior against your appliance and server version |
The compatibility APIs query and execute_reader buffer result sets. For
large results, use execute_stream or the async streaming facade described
below.
The project does not currently promise long-term API stability or complete coverage of every Netezza server feature. Missing or appliance-specific behavior should be reported as an issue with the server version, SQL example and a sanitized error or protocol trace.
Contents
- Installation
- Quick start
- Connection strings
- Queries, values and parameters
- Streaming
- Async and pooling
- Metadata
- External-table transfer
- Errors and connection lifecycle
- Security and compatibility
- Testing
- Compatibility notes
- Contributing
- License
Installation
For a published release, add the crate to Cargo.toml:
[]
= "0.1"
When using the workspace checkout:
[]
= { = "../justybase_netezza_driver_rust" }
TLS support is opt-in:
[]
= { = "0.1", = ["ssl"] }
The default build has no TLS dependency. The ssl feature enables Rustls and
the CA bundle support used by secured Netezza sessions.
Quick start
The following example connects to a Netezza database and reads a small result set. Replace the example values with configuration from your environment or secret manager.
use ;
NzConnection::connect performs TCP setup, the Netezza handshake and
authentication. NzConnection::close is idempotent; dropping a connection
also releases its socket.
NzConnectionConfig::new uses port 5480 and the default timeout values. For
full control, construct NzConnectionConfig directly and set fields such as
command_timeout, connection_timeout, security_level, app_name and
client_type.
Connection strings
Both netezza:// and nz:// schemes are accepted, case-insensitively:
use NzConnection;
let mut connection = connect_with_str?;
# connection.close;
# Ok::
Supported connection-string details include percent-decoding, query options
such as sslmode, securityLevel, commandTimeout and
connectionTimeout, and bracketed IPv6 hosts:
nz://user:password@[2001:db8::10]:5480/JUST_DATA?sslmode=verify-full
Do not put credentials in source control. Prefer environment variables or a secret manager in applications and CI.
Querying, values and parameters
NzValue is the compatibility value model returned by the driver. It includes
null, boolean, signed integer, floating-point, exact numeric, text, temporal
and binary variants. NUMERIC values that fit the fixed-width
rust_decimal::Decimal representation use NzValue::Decimal; wider Netezza
values use the lossless NzValue::Numeric(String) fallback. Temporal values
remain canonical owned strings.
Rows can be read by ordinal or case-insensitive column name and extracted with
the checked FromSql API:
use ;
#
The ToSql trait is implemented for the common Rust scalar types, String,
byte slices, NzValue and Option<T>. query_one, query_opt, execute,
batch_execute, begin_transaction, commit, rollback and
transaction are available on NzConnection.
Netezza's simple-query path does not provide a server-side bind/prepare message. Parameters are therefore escaped and substituted into the SQL text by the driver. Values are protected by the driver's literal escaping, but parameters must not be used as SQL identifiers; validate or whitelist table, column and database identifiers separately.
For C#/ADO.NET-style named or positional parameters, use NzCommand and
NzParameter:
use ;
#
Bounded streaming
execute_stream decodes one row at a time and invokes a user-provided
QueryStreamSink before reading the next backend message. The connection does
not accumulate the full result set. Override on_values when the consumer can
process borrowed values immediately; the default on_values implementation
creates an owned Row for compatibility.
use ;
#
The sink may apply backpressure by blocking or returning an error. A sink error stops row delivery, sends a best-effort cancel, and drains the backend response through ReadyForQuery before returning the sink error. The connection can be reused when that drain succeeds. A protocol framing error still makes the connection unsafe to reuse; reconnect before issuing another command.
StreamSummary reports result-set metadata, row counts, affected rows and
server notices. Multiple result sets are delivered in order.
Override QueryStreamSink::on_notice to handle notices as they arrive during a query. The native Tokio client offers query_stream_events, whose QueryStreamEvent values include rows and notices in wire order; query_stream continues to yield rows only.
Async and pooling APIs
Client and Connection provide the native Tokio API. connect returns both
objects, just like tokio-postgres; the caller runs the connection future and
uses the cloneable client for serialized queries. query_stream exposes a
bounded RowStream with backpressure. The compatibility AsyncNzConnection
API remains available for cancellation, metadata and existing applications;
it moves the legacy blocking protocol work to Tokio's blocking pool.
use ;
# async
use ;
# async
Use query_with_timeout, execute_with_timeout or
execute_stream_with_timeout when a command needs a per-call wall-clock
budget. The deadline covers sending, response decoding and streaming fetches;
on timeout the driver sends an out-of-band cancel and drains the abandoned
response before the next command. AsyncNzConnection::cancel() can be awaited
from another Tokio task while a query is running and keeps the same session
usable when the server returns ReadyForQuery.
Use NzPool for synchronous applications and AsyncNzPool for Tokio
applications. Both support maximum and minimum connection counts, checkout
timeouts, idle/lifetime/use rotation and rollback-on-release. SQL errors keep a
drained session; transport, timeout and protocol errors retire it. An open
transaction is rolled back before a connection is returned to the idle queue
when rollback_on_release is enabled (the default).
Metadata and catalog operations
Catalog helpers are available through a short-lived mutable metadata view:
use ;
#
The metadata surface includes schemas, databases, tables, columns, views,
procedures, functions, synonyms, constraints, distribution keys, organize
keys, table sizes, sessions, object details and object search. Use
change_database to switch catalogs without reconnecting when no transaction
is active.
Additional helpers expose current database and schema, sequences, users, groups, query history, detailed columns, table keys, comments and owners. table_ddl, view_ddl, procedure_ddl, external_table_ddl and synonym_ddl reconstruct SQL from catalog entries. tables_ddl, views_ddl and procedures_ddl return per-object results and errors for batch requests. Use an explicit procedure signature when a name has multiple overloads.
External-table transfer
The crate also exposes the Netezza external-table import/export framing used by
the workbench. Register import data with register_import_data, execute the
corresponding external-table command, and unregister it when the transfer is
complete. Invalid buffer sizes are reported as errors; they are not silently
replaced with a default.
Use register_import_reader for synchronous Read sources and register_async_import_reader for Tokio AsyncRead sources. Files and readers are read in bounded chunks, so large imports do not need to reside in memory. Typed extraction supports rust_decimal::Decimal. Enable the optional chrono feature for NaiveDate, NaiveTime, NaiveDateTime and NzTimeTz.
Errors and connection lifecycle
All fallible operations return NzResult<T>. NzError distinguishes
configuration, transport, timeout, database and protocol failures.
NzError::Databasecontains structured backend diagnostics and SQLSTATE when supplied by Netezza.NzError::Protocolmeans framing or sequencing was invalid and the connection must be recreated.NzError::Timeoutmeans the command timeout path attempted out-of-band cancellation; recreate the connection if the server or transport cannot be confirmed synchronized.
The driver drains normal database errors through ReadyForQuery, allowing a
pool to retain the session after a SQL error. It retires sessions that cannot
be safely synchronized.
Security and compatibility
- Do not commit passwords or connection strings containing credentials. Use environment variables or a secret manager.
- SQL parameters are treated as values. They must not be used for table, column or database identifiers; validate or whitelist dynamic identifiers separately.
- TLS is opt-in through the
sslfeature. Use certificate verification in secured environments and test the selectedsslmodeagainst your appliance. - The simple-query protocol performs client-side parameter substitution; it is not a server-side prepared-statement API.
- Performance depends on the appliance, network, query shape and value types. No universal benchmark claim is made for this preview release.
Testing and validation
Offline/unit validation from the workspace root:
Live tests use NZ_DEV_HOST, NZ_DEV_PORT, NZ_DEV_USER and
NZ_DEV_PASSWORD:
NZ_RUN_LIVE_TESTS=1 \
The live suites are opt-in because they require access to a Netezza appliance. The mock-server and unit suites are the default appliance-independent checks.
The examples/nz-editor TUI is intentionally excluded from the published
crate. It is a separate local package and uses the published
justybase-spreadsheet crate from crates.io. The cross-driver benchmark is
also repository tooling; its C# runner uses the JustyBase.NetezzaDriver
NuGet package to compare live compatibility and correctness, while its Node
runner requires the separately built Node driver. These comparisons require a
real Netezza appliance and are not run in GitHub Actions.
Rust/C# result compatibility
The shared compatibility manifest is
benchmarks/netezza_cross_driver/compatibility_cases.json. It compares column
names, result-set shape, NULLs, canonical values, affected rows and selected
type categories. Floating-point cases use an explicit tolerance; errors are
compared by outcome rather than localized message text.
Run the deterministic/core live comparison with the C# reference driver:
NZ_DEV_HOST=... NZ_DEV_USER=... NZ_DEV_PASSWORD=... \
Run the extended comparison by importing the existing C# reference query corpus. The importer only reads the JavaScript source; it does not run Node or Node tests:
NZ_DEV_HOST=... NZ_DEV_USER=... NZ_DEV_PASSWORD=... \
Set NZ_CSHARP_REFERENCE_QUERIES when the reference corpus is stored at a
different path. Reports are written below target/netezza-cross-compatibility
and must not be committed. The report separates documented C# representation
differences (for example, wide NUMERIC rounding) from unexpected mismatches;
only unexpected mismatches make the command fail.
The C# benchmark project restores JustyBase.NetezzaDriver from NuGet. It is
not a dependency of nz_rust and is not included in the crates.io package.
License
Licensed under the Apache License, Version 2.0.
Contributing and support
Bug reports, compatibility findings and focused pull requests are welcome. Please include the Rust version, Netezza/PureData server version, relevant feature flags and a sanitized reproduction. Never include credentials or private connection details.
Compatibility notes
- The simple-query protocol performs client-side parameter substitution; it is not a server-side prepared-statement API.
queryandexecute_readerretain all result rows in memory.execute_streamis the bounded-memory API and is the preferred choice for large exports, grids and result stores.Clientuses native Tokio socket I/O;AsyncNzConnectionis retained as a blocking-pool compatibility facade.- The crate does not impose
chronoortime; it usesrust_decimalfor exact NUMERIC values within its fixed-width range and retains a string fallback for wider Netezza values.