Struct sqlx_postgres::PgTypeInfo

pub struct PgTypeInfo(/* private fields */);

Type information for a PostgreSQL type.

Note: Implementation of == (PartialEq::eq())

Because == on TypeInfos has been used throughout the SQLx API as a synonym for type compatibility, e.g. in the default impl of Type::compatible(), some concessions have been made in the implementation.

When comparing two PgTypeInfos using the == operator (PartialEq::eq()), if one was constructed with Self::with_oid() and the other with Self::with_name() or Self::array_of(), == will return true:

// Potentially surprising result, this assert will pass:
assert_eq!(PgTypeInfo::with_oid(Oid(1)), PgTypeInfo::with_name("definitely_not_real"));

Since it is not possible in this case to prove the types are not compatible (because both PgTypeInfos need to be resolved by an active connection to know for sure) and type compatibility is mainly done as a sanity check anyway, it was deemed acceptable to fudge equality in this very specific case.

This also applies when querying with the text protocol (not using prepared statements, e.g. sqlx::raw_sql()), as the connection will be unable to look up the type info like it normally does when preparing a statement: it won’t know what the OIDs of the output columns will be until it’s in the middle of reading the result, and by that time it’s too late.

To compare types for exact equality, use Self::type_eq() instead.

Implementations

impl PgTypeInfo

pub fn kind(&self) -> &PgTypeKind

Returns the kind (simple, array, enum, etc.) for this type.

pub fn oid(&self) -> Option<Oid>

Returns the OID for this type, if available.

The OID may not be available if SQLx only knows the type by name. It will have to be resolved by a PgConnection at runtime which will yield a new and semantically distinct TypeInfo instance.

This method does not perform any such lookup.

Note

With the exception of the default pg_type catalog, type OIDs are not stable in PostgreSQL. If a type is added by an extension, its OID will be assigned when the CREATE EXTENSION statement is executed, and so can change depending on what extensions are installed and in what order, as well as the exact version of PostgreSQL.

pub const fn with_name(name: &'static str) -> Self

Create a PgTypeInfo from a type name.

The OID for the type will be fetched from Postgres on use of a value of this type. The fetched OID will be cached per-connection.

Note: Type Names Prefixed with _

In pg_catalog.pg_type, Postgres prefixes a type name with _ to denote an array of that type, e.g. int4[] actually exists in pg_type as _int4.

Previously, it was necessary in manual PgHasArrayType impls to return PgTypeInfo::with_name() with the type name prefixed with _ to denote an array type, but this would not work with schema-qualified names.

As of 0.8, PgTypeInfo::array_of() is used to declare an array type, and the Postgres driver is now able to properly resolve arrays of custom types, even in other schemas, which was not previously supported.

It is highly recommended to migrate existing usages to PgTypeInfo::array_of() where applicable.

However, to maintain compatibility, the driver now infers any type name prefixed with _ to be an array of that type. This may introduce some breakages for types which use a _ prefix but which are not arrays.

As a workaround, type names with _ as a prefix but which are not arrays should be wrapped in quotes, e.g.:

use sqlx::postgres::PgTypeInfo;
use sqlx::{Type, TypeInfo};

/// `CREATE TYPE "_foo" AS ENUM ('Bar', 'Baz');`
#[derive(sqlx::Type)]
// Will prevent SQLx from inferring `_foo` as an array type.
#[sqlx(type_name = r#""_foo""#)]
enum Foo {
    Bar,
    Baz
}

assert_eq!(Foo::type_info().name(), r#""_foo""#);

pub fn array_of(elem_name: &'static str) -> Self

Create a PgTypeInfo of an array from the name of its element type.

The array type OID will be fetched from Postgres on use of a value of this type. The fetched OID will be cached per-connection.

pub const fn with_oid(oid: Oid) -> Self

Create a PgTypeInfo from an OID.

Note that the OID for a type is very dependent on the environment. If you only ever use one database or if this is an unhandled built-in type, you should be fine. Otherwise, you will be better served using Self::with_name().

Note: Interaction with ==

This constructor may give surprising results with ==.

See the type-level docs for details.

pub fn type_eq(&self, other: &Self) -> bool

Returns true if self can be compared exactly to other.

Unlike ==, this will return false if

Trait Implementations

impl Clone for PgTypeInfo

fn clone(&self) -> PgTypeInfo

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PgTypeInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for PgTypeInfo

type Target = PgType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for PgTypeInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for PgTypeInfo

fn eq(&self, other: &PgTypeInfo) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TypeInfo for PgTypeInfo

fn name(&self) -> &str

Returns the database system name of the type. Length specifiers should not be included. Common type names are VARCHAR, TEXT, or INT. Type names should be uppercase. They should be a rough approximation of how they are written in SQL in the given database.

fn is_null(&self) -> bool

fn type_compatible(&self, other: &Self) -> bool

where Self: Sized,

Return true if self and other represent mutually compatible types.

impl StructuralPartialEq for PgTypeInfo