Skip to main content

Crate db_collation

Crate db_collation 

Source
Expand description

§db-collation

Offline, exact string comparison under an explicitly identified database collation and version.

This crate exists for one purpose: reproduce the exact ordering semantics of a source database’s collation locally, without talking to that database. It is a pure function of a Collation description and the input bytes. It opens no sockets, holds no drivers, and never issues a query.

§Guarantees and non-guarantees

  • Exact or refused. For a supported configuration, Collation::compare matches the source database’s comparison operator exactly (validated by the differential harness in harness/). For anything not explicitly modelled, construction returns Error::Unsupported and the caller should fall back to comparing on the source database. A supported configuration can still reject an individual input that exceeds a documented source limit (e.g. Oracle’s 2000-byte UCA sort key); that is Error::InputLimit, and the caller falls back for that input only.
  • No approximation. Selecting the same locale name is not sufficient: ICU data versions change ordering (e.g. あ vs U+11DB0 reversed between ICU 76 and 78), and MySQL collations differ by UCA version, tailoring and padding. This crate therefore gates on version, not on names alone.
  • Deterministic tie-break. PostgreSQL deterministic collations break ICU equality ties with a bytewise comparison (shorter string first). That is reproduced here; nondeterministic collations intentionally do not.

§Supported configurations

See Collation and the crate README for the current matrix.

§Examples

use db_collation::{Collation, Result};
use std::cmp::Ordering;

fn main() -> Result<()> {
    // Bytewise comparison is always available.
    assert_eq!(Collation::binary().compare("a", "b")?, Ordering::Less);

    // Unsupported configurations fail closed, so the caller can fall back.
    assert!(Collation::from_mysql_name_unspecified_version("utf8mb4_general_ci").is_err());
    Ok(())
}

With the mysql-uca feature (enabled by default):

use db_collation::{Collation, Result};
use std::cmp::Ordering;

fn main() -> Result<()> {
    let c = Collation::mysql_0900_ai_ci();
    assert_eq!(c.compare("a", "A")?, Ordering::Equal);
    Ok(())
}

Structs§

Collation
A collation that this crate can compare with, or an explicit refusal.
MysqlCollation
A resolved MySQL collation description.
OracleCollation
A resolved Oracle collation description.
PostgresCollation
A resolved PostgreSQL collation description.
VersionId
A provider-specific collation data version token.

Enums§

Backend
Which backend a Collation uses.
Error
Errors produced when building or using a collation.
MysqlUcaVersion
MySQL UCA weight-table version.
OracleProvider
Oracle collation provider.
OracleUcaVersion
Oracle UCA version for a UCA*_DUCET collation.
Pad
Trailing-space comparison semantics.
PostgresProvider
PostgreSQL collation provider.

Functions§

collation_versionpostgres-icu
The collation data version this build would use for locale, formatted exactly as PostgreSQL reports it in pg_collation_actual_version(oid).
icu_library_versionpostgres-icu
The local ICU’s own library version (e.g. 76.1), for diagnostics.

Type Aliases§

Result
Convenience alias for Result with Error.