GaussDB-Rust

GaussDB and OpenGauss support for Rust.

gaussdb

Documentation

A native, synchronous GaussDB client with full PostgreSQL compatibility.

tokio-gaussdb

Documentation

A native, asynchronous GaussDB client with full PostgreSQL compatibility.

gaussdb-types

Documentation

Conversions between Rust and GaussDB/PostgreSQL types.

gaussdb-native-tls

Documentation

TLS support for gaussdb and tokio-gaussdb via native-tls.

gaussdb-openssl

Documentation

TLS support for gaussdb and tokio-gaussdb via openssl.

Features

GaussDB Authentication Support

This library provides full support for GaussDB's enhanced authentication mechanisms:

• SHA256 Authentication: GaussDB's secure SHA256-based authentication
• MD5_SHA256 Authentication: Hybrid authentication combining MD5 and SHA256
• Standard PostgreSQL Authentication: Full compatibility with MD5, SCRAM-SHA-256, and other PostgreSQL auth methods

Quick Start

Basic Connection

use tokio_gaussdb::{NoTls, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Connect to GaussDB with SHA256 authentication
    let (client, connection) = tokio_gaussdb::connect(
        "host=localhost user=gaussdb password=Gaussdb@123 dbname=postgres port=5433",
        NoTls,
    ).await?;

    // Spawn the connection task
    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    // Execute a simple query
    let rows = client.query("SELECT $1::TEXT", &[&"hello world"]).await?;
    let value: &str = rows[0].get(0);
    println!("Result: {}", value);

    Ok(())
}

Advanced Authentication

use tokio_gaussdb::{Config, NoTls};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure connection with specific authentication
    let mut config = Config::new();
    config
        .host("localhost")
        .port(5433)
        .user("gaussdb")
        .password("Gaussdb@123")
        .dbname("postgres");

    let (client, connection) = config.connect(NoTls).await?;

    // Handle connection...
    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    // Your application logic here
    Ok(())
}

Compatibility

Database Support

Database	Version	Authentication	Status
GaussDB	2.0+	SHA256, MD5_SHA256, MD5	✅ Full Support
OpenGauss	3.0+	SHA256, MD5_SHA256, MD5	✅ Full Support
PostgreSQL	10+	SCRAM-SHA-256, MD5	✅ Full Support

Feature Compatibility

Feature	GaussDB	OpenGauss	PostgreSQL
Basic SQL Operations	✅	✅	✅
Transactions	✅	✅	✅
Prepared Statements	✅	✅	✅
COPY Operations	✅	✅	✅
LISTEN/NOTIFY	⚠️ Limited	⚠️ Limited	✅
Binary COPY	⚠️ Issues	⚠️ Issues	✅

Running Tests

Prerequisites

The test suite requires GaussDB or OpenGauss to be running. The easiest way is with Docker:

1. Install docker and docker-compose

   • On Ubuntu: sudo apt install docker.io docker-compose
   • On Windows: Install Docker Desktop
   • On macOS: Install Docker Desktop

2. Make sure your user has Docker permissions

   • On Ubuntu: sudo usermod -aG docker $USER

Running Tests

1. Change to the top-level directory of gaussdb-rust repo
2. Start the test database:

   docker-compose up -d

3. Run the test suite:

   cargo test

4. Stop the test database:

   docker-compose stop

Test Configuration

The test suite supports both GaussDB and OpenGauss environments. Connection strings are automatically configured for:

• Host: localhost
• Port: 5433 (GaussDB/OpenGauss default)
• User: gaussdb
• Password: Gaussdb@123
• Database: postgres

Documentation

API Documentation

• gaussdb - Synchronous client API
• tokio-gaussdb - Asynchronous client API
• gaussdb-types - Type conversion utilities
• gaussdb-protocol - Low-level protocol implementation

Guides and Examples

• GaussDB Connection Guide
• Authentication Methods
• Migration from rust-postgres
• GaussDB vs PostgreSQL Differences

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

1. Clone the repository:

   git clone https://github.com/HuaweiCloudDeveloper/gaussdb-rust.git
   cd gaussdb-rust

2. Install Rust (if not already installed):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Run tests:

   cargo test

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

This project is based on the excellent rust-postgres library by Steven Fackler. We extend our gratitude to the original authors and contributors.

Support

• GitHub Issues - Bug reports and feature requests
• Documentation - API documentation and guides
• Examples - Code examples and tutorials