Crate hyperdb_api

Expand description

Pure Rust API for Hyper database.

This crate provides a safe, idiomatic Rust interface for working with Hyper database files (.hyper). It is a pure-Rust implementation using the PostgreSQL wire protocol with Hyper-specific extensions.

§Architecture

This is a layered API built from four crates:

hyper-types — Type definitions with LittleEndian encoding
hyper-protocol — Wire protocol with HyperBinary COPY support
hyper-client — Sync/async TCP and gRPC clients
hyperdb-api — High-level API (this crate)

Optional companion crates:

sea-query-hyper — HyperDB SQL dialect backend for sea-query
hyperdb-api-salesforce — Salesforce Data Cloud OAuth authentication

§Quick Start

use hyperdb_api::{HyperProcess, Connection, CreateMode, Result};

fn main() -> Result<()> {
    let hyper = HyperProcess::new(None, None)?;
    let conn = Connection::new(&hyper, "example.hyper", CreateMode::CreateIfNotExists)?;

    conn.execute_command("CREATE TABLE test (id INT, name TEXT)")?;
    conn.execute_command("INSERT INTO test VALUES (1, 'Hello')")?;

    let mut result = conn.execute_query("SELECT * FROM test")?;
    while let Some(chunk) = result.next_chunk()? {
        for row in &chunk {
            let id: Option<i32> = row.get(0);
            let name: Option<String> = row.get(1);
            println!("id: {:?}, name: {:?}", id, name);
        }
    }
    Ok(())
}

§Lifetime Safety

The API uses lifetime annotations to provide compile-time guarantees that resources are used correctly. All dependent types (Inserter, Catalog, Rowset, Transaction) carry a 'conn lifetime parameter tying them to the Connection they borrow:

Connection (owns underlying client)
├── Inserter<'conn>
│   └── CopyInWriter<'conn>
├── Catalog<'conn>
├── Rowset<'conn>
└── Transaction<'conn>

This is a simple hierarchical design, not a complex lifetime web:

Single root owner: Connection owns the underlying client
Simple borrows: All dependent types borrow &'conn Connection
No circular references: Inserter doesn’t reference Catalog, etc.
Single lifetime parameter: Just one 'conn — no multi-lifetime bounds

The Rust borrow checker enforces that you cannot drop or move a Connection while any dependent type holds a reference to it:

let conn = Connection::connect("localhost:7483", "test.hyper", CreateMode::CreateIfNotExists)?;
let inserter = Inserter::new(&conn, /* ... */)?;
drop(conn);  // ERROR: cannot move `conn` because it is borrowed by `inserter`

The execute(self) method on Inserter takes ownership (self), which automatically ends the borrow when the insert completes — no manual cleanup needed.

§Key Types

Connection / AsyncConnection — Sync and async database connections
HyperProcess — Manage a local hyperd server process
Inserter / MappedInserter / AsyncInserter — Bulk row insertion (HyperBinary COPY)
ArrowInserter / AsyncArrowInserter — Arrow RecordBatch insertion
Catalog — Schema/table introspection
TableDefinition — Define table schemas
Transaction / AsyncTransaction — RAII transaction guards

§Public Modules

copy — CSV/text export and import via COPY protocol
pool — Async connection pooling (deadpool-based)
grpc — gRPC transport types for Arrow IPC queries

§Bulk Data Loading

Several inserter APIs are available depending on your data format and runtime model:

Inserter / MappedInserter — Sync HyperBinary row-by-row
AsyncInserter — Async HyperBinary row-by-row (mirrors Inserter)
ArrowInserter — Sync Arrow IPC (batch or streaming RecordBatch)
AsyncArrowInserter — Async Arrow IPC
copy module — CSV/TSV/delimited text import & export

§Authentication

The client supports multiple authentication methods (Trust, Cleartext, MD5, SCRAM-SHA-256):

use hyperdb_api::{Connection, CreateMode, Result};

fn main() -> Result<()> {
    let conn = Connection::connect_with_auth(
        "localhost:7483",
        "example.hyper",
        CreateMode::CreateIfNotExists,
        "myuser",
        "mypassword",
    )?;
    Ok(())
}

Modules§

copy: CSV/text export and import via COPY protocol. CSV/text export and import via COPY protocol.
grpc: gRPC transport types for Hyper database access.
oids: Re-export of the PostgreSQL OID constants. Access as hyperdb_api::oids::INT4 etc. Well-known Hyper type OIDs.
pool: Connection pooling support. Async connection pool for Hyper database.

Macros§

schema_name: Creates a SchemaName with optional database qualifier.
table: Macro for creating table definitions with a fluent syntax.
table_name: Creates a TableName with optional database and schema qualifiers.

Structs§

ArrowChunk: A chunk of rows from Arrow data, analogous to TCP’s row chunks.
ArrowInserter: Inserts Arrow IPC stream data into a Hyper table.
ArrowReader: Reads query results in Arrow IPC stream format.
ArrowRow: A row from an Arrow record batch, providing typed value access.
ArrowRowset: Parsed Arrow result set for streaming row access.
AsyncArrowInserter: Async inserter for Arrow IPC stream data into a Hyper table.
AsyncArrowInserterOwned: Owned-handle variant of AsyncArrowInserter that holds an Arc<AsyncConnection> instead of a borrow.
AsyncConnection: An async connection to a Hyper database.
AsyncConnectionBuilder: An async builder for creating database connections.
AsyncInserter: An async high-performance bulk data inserter.
AsyncPreparedStatement: A handle to a server-side prepared statement (async).
AsyncPreparedStatementOwned: Owned-handle variant of AsyncPreparedStatement that holds an Arc<AsyncConnection> instead of a borrow.
AsyncRowset: A streaming result set returned from an async query.
AsyncTransaction: An async RAII transaction guard.
Catalog: Provides catalog operations for database metadata.
ChunkSender: A thread-safe sender for InsertChunks.
ColumnDefinition: A column definition.
ColumnMapping: Defines how a column receives its value during insertion.
Connection: A connection to a Hyper database.
ConnectionBuilder: A builder for creating database connections.
DatabaseName: Represents an escaped SQL database name.
Date: A date value (days since 2000-01-01).
GeoError: Re-export of GeoError from hyperdb-api-core::types. Error type for geography operations.
Geography: A geography (spatial) value.
HyperProcess: A running Hyper server instance.
InsertChunk: A thread-safe chunk for encoding rows in parallel.
Inserter: A high-performance bulk data inserter.
Interval: An interval value.
LogFileStatsProvider: A QueryStatsProvider that extracts stats by parsing Hyper’s JSON log file.
MappedInserter: An inserter that supports SQL expression mappings.
Name: Represents an escaped SQL identifier name.
Notice: A notice or warning message from the server.
Numeric: A numeric (decimal) value with up to 38 digits of precision.
OffsetTimestamp: A timestamp with timezone offset.
Oid: A Hyper Object Identifier (OID).
Parameters: Parameters for configuring the Hyper server.
PreparedStatement: A handle to a server-side prepared statement.
QueryStats: Detailed statistics for a single query execution.
ResultColumn: Metadata about a column in a result schema.
ResultSchema: Schema information for a query result.
Row: A row from a query result, providing typed value access.
RowIterator: An iterator over rows in a query result set.
Rowset: A streaming result set from a SQL query.
SchemaName: Represents an escaped SQL schema name with optional database qualifier.
ServerVersion: A parsed server version with comparison support.
TableDefinition: A table definition.
TableName: Represents a fully qualified SQL table name.
Time: A time value (microseconds since midnight).
Timestamp: A timestamp value (microseconds since 2000-01-01 00:00:00).
Transaction: An RAII transaction guard that automatically rolls back on drop if not committed.
Type: Hyper SQL type information (OID + optional modifier).

Enums§

CreateMode: Database creation mode when connecting.
Error: The error type for Hyper API operations.
ErrorKind: The kind of error that occurred.
ListenMode: Specifies which protocols HyperProcess should listen on.
Nullability: Specifies whether a column allows NULL values.
Persistence: Possible persistence levels for database objects.
SqlType: SQL type tags that identify the type of a column.
TransportMode: Parameters for configuring the Hyper server.

Constants§

VERSION: Semantic version of this crate, resolved at compile time from Cargo.toml. Used by downstream tools (notably hyperdb-mcp) to surface the library version in their own status output without duplicating the version string.

Traits§

ChunkSource: Source of Arrow IPC byte chunks for streaming decode.
FromArrowValue: Trait for types that can be extracted from Arrow columns.
FromRow: Trait for types that can be constructed from a database row.
IntoValue: Trait for types that can be inserted into a Hyper table.
QueryStatsProvider: Trait for collecting query statistics from a Hyper server.
RowValue: Trait for types that can be extracted from a Row.
ScalarValue: Trait for types that can be extracted from a scalar query result.
ToSqlParam: Trait for types that can be used as parameters in parameterized SQL queries.

Functions§

escape_name: Escapes a SQL identifier for safe use in queries.
escape_sql_path: Escapes a database file path for safe use in SQL statements.
escape_string_literal: Escapes a SQL string literal for safe use in queries.
parse_arrow_ipc: Parses Arrow IPC stream bytes into a vector of RecordBatches (zero-copy).

Type Aliases§

NoticeReceiver: Type alias for a notice receiver callback.
Result: Result type for Hyper API operations.