RustUse/use-postgres

use-postgres is a RustUse facade workspace for small, focused PostgreSQL primitive crates. It models PostgreSQL identifiers, built-in type labels, schemas, tables, columns, constraints, indexes, sequences, enum types, and extensions without becoming a database access layer.

RustUse is "Composable sets of primitive Rust utility crates for fellow crustaceans." This workspace keeps that shape: focused crates stay dependency-light, and the facade crate re-exports them behind feature flags.

Non-goals

use-postgres is not:

• a PostgreSQL client
• a connection pool
• an ORM
• a query builder
• a migration runner
• an async runtime integration
• a SQL parser
• a SQL executor
• a live database introspection layer

The crates do not depend on postgres, sqlx, diesel, tokio, or any database driver.

Relationship to use-sql

• use-sql models generic SQL primitives and vocabulary.
• use-postgres models PostgreSQL-specific dialect and object metadata.
• The crates avoid duplicating generic query execution, generic SQL expressions, database clients, and parser behavior.
• A future optional compatibility feature can add explicit conversions to use-sql primitives if the release line needs it.

Workspace crates

Crate	Purpose	Status
use-postgres	Feature-gated facade over focused PostgreSQL primitive crates	initial
use-pg-identifier	PostgreSQL identifiers, quoted/unquoted awareness, qualified names, validation helpers	initial
use-pg-type	PostgreSQL built-in type names, categories, array-like labels, optional OID wrapper	initial
use-pg-schema	Schema names, search paths, and common schema classification	initial
use-pg-table	Table names, table kinds, persistence labels, and table metadata	initial
use-pg-column	Column names, type metadata, defaults, nullability, identity/generated labels	initial
use-pg-constraint	Constraint names, kinds, deferrability, and metadata	initial
use-pg-index	Index names, methods, flags, columns, expressions, and predicates	initial
use-pg-sequence	Sequence names, options, ownership labels, and simple numeric settings	initial
use-pg-enum	Enum type names, ordered variant labels, and validation	initial
use-pg-extension	Extension names, versions, schema metadata, and common extension constants	initial

Installation

Use the workspace directly or depend on a Git revision until the first crates.io release is published.

[dependencies]
use-postgres = { git = "https://github.com/RustUse/use-postgres", rev = "<commit>" }

After publication, choose the narrowest focused crate that matches your use case or use the facade when one dependency is more convenient.

[dependencies]
use-postgres = "0.1.0"

Basic usage

# #[cfg(feature = "full")]
# {
use use_postgres::{column, constraint, enumeration, extension, index, schema, table, ty};

let users = table::PgTableRef::qualified(
    schema::PgSchemaName::public(),
    table::PgTableName::new("users")?,
);
let id = column::PgColumn::with_built_in_type(
    column::PgColumnName::new("id")?,
    ty::PgBuiltInType::BigInt,
)
.with_nullability(column::PgNullability::NotNull)
.with_identity(column::PgIdentityKind::Always);
let email = column::PgColumn::with_built_in_type(
    column::PgColumnName::new("email")?,
    ty::PgBuiltInType::Text,
)
.with_nullability(column::PgNullability::NotNull);

let primary_key = constraint::PgConstraint::new(constraint::PgConstraintKind::PrimaryKey)
    .with_name(constraint::PgConstraintName::new("users_pkey")?)
    .with_columns(vec![column::PgColumnName::new("id")?]);
let email_index = index::PgIndex::new(index::PgIndexName::new("users_email_idx")?)
    .with_table(users.clone())
    .with_method(index::PgIndexMethod::Btree)
    .with_columns(vec![index::PgIndexColumn::new("email")?])
    .with_flags(index::PgIndexFlags::default().unique(true));
let status = enumeration::PgEnumType::new(enumeration::PgEnumName::new("user_status")?)
    .with_schema(schema::PgSchemaName::public())
    .with_variants(vec![
        enumeration::PgEnumVariant::new("active")?,
        enumeration::PgEnumVariant::new("disabled")?,
    ])?;
let pgcrypto = extension::PgExtension::new(extension::PgExtensionName::pgcrypto())
    .with_version(extension::PgExtensionVersion::new("1.3")?);

assert_eq!(users.to_string(), "public.users");
assert_eq!(id.identity(), Some(column::PgIdentityKind::Always));
assert_eq!(email.nullability(), column::PgNullability::NotNull);
assert_eq!(primary_key.to_string(), "CONSTRAINT users_pkey PRIMARY KEY");
assert!(email_index.flags().is_unique());
assert_eq!(status.variants().len(), 2);
assert_eq!(pgcrypto.name().as_str(), "pgcrypto");
# }
# Ok::<(), Box<dyn std::error::Error>>(())

Feature model

The facade crate exposes one feature per focused crate and enables full by default. Disable default features when you want a narrow facade surface.

[dependencies]
use-postgres = { version = "0.1.0", default-features = false, features = ["identifier", "schema", "table"] }

Development

cargo fmt --all -- --check
cargo check --workspace --all-features
cargo check --workspace --all-features --examples
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo test --workspace --no-default-features
cargo doc --workspace --all-features --no-deps

License

Licensed under either of the following, at your option:

• Apache License, Version 2.0
• MIT license