mz_pgrepr/

value.rs

// Copyright Materialize, Inc. and contributors. All rights reserved.
//
// Use of this software is governed by the Business Source License
// included in the LICENSE file.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0.

use std::collections::BTreeMap;
use std::error::Error;
use std::{io, str};

use bytes::{BufMut, BytesMut};
use chrono::{DateTime, NaiveDateTime, NaiveTime, Utc};
use dec::OrderedDecimal;
use itertools::Itertools;
use mz_ore::cast::ReinterpretCast;
use mz_ore::fmt::FormatBuffer;
use mz_pgrepr_consts::oid::TYPE_INT2_OID;
use mz_pgwire_common::Format;
use mz_repr::adt::array::ArrayDimension;
use mz_repr::adt::char;
use mz_repr::adt::date::Date;
use mz_repr::adt::jsonb::JsonbRef;
use mz_repr::adt::mz_acl_item::{AclItem, MzAclItem};
use mz_repr::adt::numeric::{self as mz_repr_numeric, NumericMaxScale, rescale};
use mz_repr::adt::pg_legacy_name::NAME_MAX_BYTES;
use mz_repr::adt::range::{Range, RangeInner};
use mz_repr::adt::timestamp::CheckedTimestamp;
use mz_repr::strconv::{self, Nestable};
use mz_repr::{Datum, RowArena, RowPacker, RowRef, SqlRelationType, SqlScalarType};
use postgres_types::{FromSql, IsNull, ToSql, Type as PgType};
use uuid::Uuid;

use crate::types::{NumericConstraints, UINT2, UINT4, UINT8};
use crate::value::error::{IntoDatumError, NulCharacterError};
use crate::{Interval, Jsonb, Numeric, Type, UInt2, UInt4, UInt8, regproc};

pub mod error;
pub mod interval;
pub mod jsonb;
pub mod numeric;
pub mod record;
pub mod unsigned;

/// A PostgreSQL datum.
#[derive(Debug)]
pub enum Value {
    /// A variable-length, multi-dimensional array of values.
    Array {
        /// The dimensions of the array.
        dims: Vec<ArrayDimension>,
        /// The elements of the array.
        elements: Vec<Option<Value>>,
    },
    /// A boolean value.
    Bool(bool),
    /// A byte array, i.e., a variable-length binary string.
    Bytea(Vec<u8>),
    /// A single-byte character.
    Char(u8),
    /// A date.
    Date(Date),
    /// A 4-byte floating point number.
    Float4(f32),
    /// An 8-byte floating point number.
    Float8(f64),
    /// A 2-byte signed integer.
    Int2(i16),
    /// A 4-byte signed integer.
    Int4(i32),
    /// An 8-byte signed integer.
    Int8(i64),
    /// A 2-byte unsigned integer.
    UInt2(UInt2),
    /// A 4-byte unsigned integer.
    UInt4(UInt4),
    /// An 8-byte unsigned integer.
    UInt8(UInt8),
    /// A time interval.
    Interval(Interval),
    /// A binary JSON blob.
    Jsonb(Jsonb),
    /// A sequence of homogeneous values.
    List(Vec<Option<Value>>),
    /// A map of string keys and homogeneous values.
    Map(BTreeMap<String, Option<Value>>),
    /// An identifier string of no more than 64 characters in length.
    Name(String),
    /// An arbitrary precision number.
    Numeric(Numeric),
    /// An object identifier.
    Oid(u32),
    /// An object identifier naming a function.
    ///
    /// Kept distinct from [`Value::Oid`] because the text encoding resolves the
    /// OID to the function's name, matching PostgreSQL's `regprocout`. The
    /// binary encoding is identical to an `oid`, as it is in PostgreSQL.
    RegProc(u32),
    /// A sequence of heterogeneous values.
    Record(Vec<Option<Value>>),
    /// A time.
    Time(NaiveTime),
    /// A date and time, without a timezone.
    Timestamp(CheckedTimestamp<NaiveDateTime>),
    /// A date and time, with a timezone.
    TimestampTz(CheckedTimestamp<DateTime<Utc>>),
    /// A variable-length string.
    Text(String),
    /// A fixed-length string.
    BpChar(String),
    /// A variable-length string with an optional limit.
    VarChar(String),
    /// A universally unique identifier.
    Uuid(Uuid),
    /// A small int vector.
    Int2Vector {
        /// The elements of the vector.
        elements: Vec<Option<Value>>,
    },
    /// A Materialize timestamp.
    MzTimestamp(mz_repr::Timestamp),
    /// A contiguous range of values along a domain.
    Range(Range<Box<Value>>),
    /// A list of privileges granted to a role, that uses [`mz_repr::role_id::RoleId`]s for role
    /// references.
    MzAclItem(MzAclItem),
    /// A list of privileges granted to a user that uses [`mz_repr::adt::system::Oid`]s for role
    /// references. This type is used primarily for compatibility with PostgreSQL.
    AclItem(AclItem),
}

impl Value {
    /// Constructs a new `Value` from a Materialize datum.
    ///
    /// The conversion happens in the obvious manner, except that `Datum::Null`
    /// is converted to `None` to align with how PostgreSQL handles NULL.
    pub fn from_datum(datum: Datum, typ: &SqlScalarType) -> Option<Value> {
        match (datum, typ) {
            (Datum::Null, _) => None,
            (Datum::True, SqlScalarType::Bool) => Some(Value::Bool(true)),
            (Datum::False, SqlScalarType::Bool) => Some(Value::Bool(false)),
            (Datum::Int16(i), SqlScalarType::Int16) => Some(Value::Int2(i)),
            (Datum::Int32(i), SqlScalarType::Int32) => Some(Value::Int4(i)),
            (Datum::Int64(i), SqlScalarType::Int64) => Some(Value::Int8(i)),
            (Datum::UInt8(c), SqlScalarType::PgLegacyChar) => Some(Value::Char(c)),
            (Datum::UInt16(u), SqlScalarType::UInt16) => Some(Value::UInt2(UInt2(u))),
            (Datum::UInt32(oid), SqlScalarType::Oid) => Some(Value::Oid(oid)),
            (Datum::UInt32(oid), SqlScalarType::RegProc) => Some(Value::RegProc(oid)),
            // NOTE: `regclass` and `regtype` collapse into `Value::Oid`, so they
            // render as digits where PostgreSQL renders a name. Unlike `regproc`
            // they can name objects a user created, which no static table can
            // know. Resolution for those two lives in the SQL cast to `text`.
            (Datum::UInt32(oid), SqlScalarType::RegClass) => Some(Value::Oid(oid)),
            (Datum::UInt32(oid), SqlScalarType::RegType) => Some(Value::Oid(oid)),
            (Datum::UInt32(u), SqlScalarType::UInt32) => Some(Value::UInt4(UInt4(u))),
            (Datum::UInt64(u), SqlScalarType::UInt64) => Some(Value::UInt8(UInt8(u))),
            (Datum::Float32(f), SqlScalarType::Float32) => Some(Value::Float4(*f)),
            (Datum::Float64(f), SqlScalarType::Float64) => Some(Value::Float8(*f)),
            (Datum::Numeric(d), SqlScalarType::Numeric { .. }) => Some(Value::Numeric(Numeric(d))),
            (Datum::MzTimestamp(t), SqlScalarType::MzTimestamp) => Some(Value::MzTimestamp(t)),
            (Datum::MzAclItem(mai), SqlScalarType::MzAclItem) => Some(Value::MzAclItem(mai)),
            (Datum::AclItem(ai), SqlScalarType::AclItem) => Some(Value::AclItem(ai)),
            (Datum::Date(d), SqlScalarType::Date) => Some(Value::Date(d)),
            (Datum::Time(t), SqlScalarType::Time) => Some(Value::Time(t)),
            (Datum::Timestamp(ts), SqlScalarType::Timestamp { .. }) => Some(Value::Timestamp(ts)),
            (Datum::TimestampTz(ts), SqlScalarType::TimestampTz { .. }) => {
                Some(Value::TimestampTz(ts))
            }
            (Datum::Interval(iv), SqlScalarType::Interval) => Some(Value::Interval(Interval(iv))),
            (Datum::Bytes(b), SqlScalarType::Bytes) => Some(Value::Bytea(b.to_vec())),
            (Datum::String(s), SqlScalarType::String) => Some(Value::Text(s.to_owned())),
            (Datum::String(s), SqlScalarType::VarChar { .. }) => Some(Value::VarChar(s.to_owned())),
            (Datum::String(s), SqlScalarType::Char { length }) => {
                Some(Value::BpChar(char::format_str_pad(s, *length)))
            }
            (Datum::String(s), SqlScalarType::PgLegacyName) => Some(Value::Name(s.into())),
            (_, SqlScalarType::Jsonb) => {
                Some(Value::Jsonb(Jsonb(JsonbRef::from_datum(datum).to_owned())))
            }
            (Datum::Uuid(u), SqlScalarType::Uuid) => Some(Value::Uuid(u)),
            (Datum::Array(array), SqlScalarType::Array(elem_type)) => {
                let dims = array.dims().into_iter().collect();
                let elements = array
                    .elements()
                    .iter()
                    .map(|elem| Value::from_datum(elem, elem_type))
                    .collect();
                Some(Value::Array { dims, elements })
            }
            (Datum::Array(array), SqlScalarType::Int2Vector) => {
                assert!(
                    array.has_int2vector_dims(),
                    "int2vector must be 1 dimensional, or empty"
                );
                let elements = array
                    .elements()
                    .iter()
                    .map(|elem| Value::from_datum(elem, &SqlScalarType::Int16))
                    .collect();
                Some(Value::Int2Vector { elements })
            }
            (Datum::List(list), SqlScalarType::List { element_type, .. }) => {
                let elements = list
                    .iter()
                    .map(|elem| Value::from_datum(elem, element_type))
                    .collect();
                Some(Value::List(elements))
            }
            (Datum::List(record), SqlScalarType::Record { fields, .. }) => {
                let fields = record
                    .iter()
                    .zip_eq(fields)
                    .map(|(e, (_name, ty))| Value::from_datum(e, &ty.scalar_type))
                    .collect();
                Some(Value::Record(fields))
            }
            (Datum::Map(dict), SqlScalarType::Map { value_type, .. }) => {
                let entries = dict
                    .iter()
                    .map(|(k, v)| (k.to_owned(), Value::from_datum(v, value_type)))
                    .collect();
                Some(Value::Map(entries))
            }
            (Datum::Range(range), SqlScalarType::Range { element_type }) => {
                let value_range = range.into_bounds(|b| {
                    Box::new(
                        Value::from_datum(b.datum(), element_type)
                            .expect("RangeBounds never contain Datum::Null"),
                    )
                });
                Some(Value::Range(value_range))
            }
            _ => panic!("can't serialize {}::{:?}", datum, typ),
        }
    }

    /// Converts a Materialize datum from this value.
    pub fn into_datum<'a>(
        self,
        buf: &'a RowArena,
        typ: &Type,
    ) -> Result<Datum<'a>, IntoDatumError> {
        Ok(match self {
            Value::Array { dims, elements } => {
                let element_pg_type = match typ {
                    Type::Array(t) => &*t,
                    _ => panic!("Value::Array should have type Type::Array. Found {:?}", typ),
                };
                let elements: Result<Vec<_>, _> = elements
                    .into_iter()
                    .map(|element| match element {
                        Some(element) => element.into_datum(buf, element_pg_type),
                        None => Ok(Datum::Null),
                    })
                    .collect();
                let elements = elements?;
                buf.try_make_datum(|packer| {
                    packer
                        .try_push_array(&dims, elements)
                        .map_err(IntoDatumError::from)
                })?
            }
            Value::Int2Vector { .. } => {
                // This situation is handled gracefully by Value::decode; if we
                // wind up here it's a programming error.
                unreachable!("into_datum cannot be called on Value::Int2Vector");
            }
            Value::Bool(true) => Datum::True,
            Value::Bool(false) => Datum::False,
            Value::Bytea(b) => Datum::Bytes(buf.push_bytes(b)),
            Value::Char(c) => Datum::UInt8(c),
            Value::Date(d) => Datum::Date(d),
            Value::Float4(f) => Datum::Float32(f.into()),
            Value::Float8(f) => Datum::Float64(f.into()),
            Value::Int2(i) => Datum::Int16(i),
            Value::Int4(i) => Datum::Int32(i),
            Value::Int8(i) => Datum::Int64(i),
            Value::UInt2(u) => Datum::UInt16(u.0),
            Value::UInt4(u) => Datum::UInt32(u.0),
            Value::UInt8(u) => Datum::UInt64(u.0),
            Value::Jsonb(js) => buf.push_unary_row(js.0.into_row()),
            Value::List(elems) => {
                let elem_pg_type = match typ {
                    Type::List(t) => &*t,
                    _ => panic!("Value::List should have type Type::List. Found {:?}", typ),
                };
                let elems: Result<Vec<_>, _> = elems
                    .into_iter()
                    .map(|elem| match elem {
                        Some(elem) => elem.into_datum(buf, elem_pg_type),
                        None => Ok(Datum::Null),
                    })
                    .collect();
                let elems = elems?;
                buf.make_datum(|packer| packer.push_list(elems))
            }
            Value::Map(map) => {
                let elem_pg_type = match typ {
                    Type::Map { value_type } => &*value_type,
                    _ => panic!("Value::Map should have type Type::Map. Found {:?}", typ),
                };
                buf.try_make_datum(|packer| {
                    packer.try_push_dict_with(|row| {
                        for (k, v) in map {
                            row.push(Datum::String(buf.push_string(k)));
                            let datum = match v {
                                Some(elem) => elem.into_datum(buf, elem_pg_type)?,
                                None => Datum::Null,
                            };
                            row.push(datum);
                        }
                        Ok::<_, IntoDatumError>(())
                    })
                })?
            }
            Value::Oid(oid) | Value::RegProc(oid) => Datum::UInt32(oid),
            Value::Record(_) => {
                // This situation is handled gracefully by Value::decode; if we
                // wind up here it's a programming error.
                unreachable!("into_datum cannot be called on Value::Record");
            }
            Value::Time(t) => Datum::Time(t),
            Value::Timestamp(ts) => Datum::Timestamp(ts),
            Value::TimestampTz(ts) => Datum::TimestampTz(ts),
            Value::Interval(iv) => Datum::Interval(iv.0),
            Value::Text(s) | Value::VarChar(s) | Value::Name(s) => {
                Datum::String(buf.push_string(s))
            }
            Value::BpChar(s) => Datum::String(buf.push_string(s.trim_end().into())),
            Value::Uuid(u) => Datum::Uuid(u),
            Value::Numeric(n) => Datum::Numeric(n.0),
            Value::MzTimestamp(t) => Datum::MzTimestamp(t),
            Value::Range(range) => {
                let elem_pg_type = match typ {
                    Type::Range { element_type } => &*element_type,
                    _ => panic!("Value::Range should have type Type::Range. Found {:?}", typ),
                };
                let range = range.try_into_bounds(|elem| elem.into_datum(buf, elem_pg_type))?;
                buf.try_make_datum(|packer| packer.push_range(range).map_err(IntoDatumError::from))?
            }
            Value::MzAclItem(mz_acl_item) => Datum::MzAclItem(mz_acl_item),
            Value::AclItem(acl_item) => Datum::AclItem(acl_item),
        })
    }

    /// Like [`Self::into_datum`] but maps the error to a formatted string for decode/parameter contexts.
    ///
    /// Callers can then convert the `String` to their preferred error type (e.g. `io::Error`,
    /// protocol error). The message is `"unable to decode {context}: {error}"`.
    pub fn into_datum_decode_error<'a>(
        self,
        buf: &'a RowArena,
        typ: &Type,
        context: &str,
    ) -> Result<Datum<'a>, String> {
        self.into_datum(buf, typ)
            .map_err(|e| format!("unable to decode {}: {}", context, e))
    }

    /// Serializes this value to `buf` in the specified `format`.
    ///
    /// `settings` affects only the text encoding.
    pub fn encode(
        &self,
        ty: &Type,
        format: Format,
        buf: &mut BytesMut,
        settings: TextEncodeSettings,
    ) -> Result<(), io::Error> {
        match format {
            Format::Text => {
                self.encode_text(buf, settings);
                Ok(())
            }
            Format::Binary => self.encode_binary(ty, buf),
        }
    }

    /// Serializes this value to `buf` using the [text encoding
    /// format](Format::Text).
    pub fn encode_text(&self, buf: &mut BytesMut, settings: TextEncodeSettings) -> Nestable {
        let extra_float_digits = settings.extra_float_digits;
        match self {
            Value::Array { dims, elements } => {
                strconv::format_array(buf, dims, elements, |buf, elem| match elem {
                    None => Ok::<_, ()>(buf.write_null()),
                    Some(elem) => Ok(elem.encode_text(buf.nonnull_buffer(), settings)),
                })
                .expect("provided closure never fails")
            }
            Value::Int2Vector { elements } => {
                strconv::format_legacy_vector(buf, elements, |buf, elem| {
                    Ok::<_, ()>(
                        elem.as_ref()
                            .expect("Int2Vector does not support NULL values")
                            .encode_text(buf.nonnull_buffer(), settings),
                    )
                })
                .expect("provided closure never fails")
            }
            Value::Bool(b) => strconv::format_bool(buf, *b),
            Value::Bytea(b) => strconv::format_bytes(buf, b),
            Value::Char(c) => {
                buf.put_u8(*c);
                Nestable::MayNeedEscaping
            }
            Value::Date(d) => strconv::format_date(buf, *d),
            Value::Int2(i) => strconv::format_int16(buf, *i),
            Value::Int4(i) => strconv::format_int32(buf, *i),
            Value::Int8(i) => strconv::format_int64(buf, *i),
            Value::UInt2(u) => strconv::format_uint16(buf, u.0),
            Value::UInt4(u) => strconv::format_uint32(buf, u.0),
            Value::UInt8(u) => strconv::format_uint64(buf, u.0),
            Value::Interval(iv) => strconv::format_interval(buf, iv.0),
            Value::Float4(f) if extra_float_digits > 0 => strconv::format_float32(buf, *f),
            Value::Float4(f) => {
                format_float_limited(buf, f64::from(*f), FLOAT4_DIGITS + extra_float_digits)
            }
            Value::Float8(f) if extra_float_digits > 0 => strconv::format_float64(buf, *f),
            Value::Float8(f) => format_float_limited(buf, *f, FLOAT8_DIGITS + extra_float_digits),
            Value::Jsonb(js) => strconv::format_jsonb(buf, js.0.as_ref()),
            Value::List(elems) => strconv::format_list(buf, elems, |buf, elem| match elem {
                None => Ok::<_, ()>(buf.write_null()),
                Some(elem) => Ok(elem.encode_text(buf.nonnull_buffer(), settings)),
            })
            .expect("provided closure never fails"),
            Value::Map(elems) => strconv::format_map(buf, elems, |buf, value| match value {
                None => Ok::<_, ()>(buf.write_null()),
                Some(elem) => Ok(elem.encode_text(buf.nonnull_buffer(), settings)),
            })
            .expect("provided closure never fails"),
            Value::Oid(oid) => strconv::format_uint32(buf, *oid),
            // Mirrors PostgreSQL's `regprocout`.
            Value::RegProc(oid) => match *oid {
                0 => strconv::format_string(buf, REGPROC_NULL),
                oid => match regproc::name(oid) {
                    Some(name) => strconv::format_string(buf, name),
                    None => strconv::format_uint32(buf, oid),
                },
            },
            Value::Record(elems) => strconv::format_record(buf, elems, |buf, elem| match elem {
                None => Ok::<_, ()>(buf.write_null()),
                Some(elem) => Ok(elem.encode_text(buf.nonnull_buffer(), settings)),
            })
            .expect("provided closure never fails"),
            Value::Text(s) | Value::VarChar(s) | Value::BpChar(s) | Value::Name(s) => {
                strconv::format_string(buf, s)
            }
            Value::Time(t) => strconv::format_time(buf, *t),
            Value::Timestamp(ts) => strconv::format_timestamp(buf, ts),
            Value::TimestampTz(ts) => strconv::format_timestamptz(buf, ts),
            Value::Uuid(u) => strconv::format_uuid(buf, *u),
            Value::Numeric(d) => strconv::format_numeric(buf, &d.0),
            Value::MzTimestamp(t) => strconv::format_mz_timestamp(buf, *t),
            Value::Range(range) => strconv::format_range(buf, range, |buf, elem| match elem {
                Some(elem) => Ok(elem.encode_text(buf.nonnull_buffer(), settings)),
                None => Ok::<_, ()>(buf.write_null()),
            })
            .expect("provided closure never fails"),
            Value::MzAclItem(mz_acl_item) => strconv::format_mz_acl_item(buf, *mz_acl_item),
            Value::AclItem(acl_item) => strconv::format_acl_item(buf, *acl_item),
        }
    }

    /// Serializes this value to `buf` using the [binary encoding
    /// format](Format::Binary).
    pub fn encode_binary(&self, ty: &Type, buf: &mut BytesMut) -> Result<(), io::Error> {
        // NOTE: If implementing binary encoding for a previously unsupported `Value` type,
        // please update the `binary_encoding_error` method below.
        let is_null = match self {
            Value::Array { dims, elements } => {
                let ndims = pg_len("number of array dimensions", dims.len())?;
                let has_null = elements.iter().any(|e| e.is_none());
                let elem_type = match ty {
                    Type::Array(elem_type) => elem_type,
                    _ => unreachable!(),
                };
                buf.put_i32(ndims);
                buf.put_i32(has_null.into());
                buf.put_u32(elem_type.oid());
                for dim in dims {
                    buf.put_i32(pg_len("array dimension length", dim.length)?);
                    buf.put_i32(dim.lower_bound.try_into().map_err(|_| {
                        io::Error::new(
                            io::ErrorKind::InvalidData,
                            "array dimension lower bound does not fit into an i32",
                        )
                    })?);
                }
                for elem in elements {
                    encode_element(buf, elem.as_ref(), elem_type)?;
                }
                Ok(postgres_types::IsNull::No)
            }
            Value::Int2Vector { elements } => {
                // this should always be `false`, but there are exceptions in postgres
                // feels better to compute this than to assert otherwise
                let has_null = elements.iter().any(|e| e.is_none());
                buf.put_i32(1);
                buf.put_i32(has_null.into());
                buf.put_u32(TYPE_INT2_OID);
                buf.put_i32(pg_len("int2vector dimension length", elements.len())?);
                buf.put_i32(0);
                for elem in elements {
                    encode_element(buf, elem.as_ref(), &Type::Int2)?;
                }
                Ok(postgres_types::IsNull::No)
            }
            Value::Bool(b) => b.to_sql(&PgType::BOOL, buf),
            Value::Bytea(b) => b.to_sql(&PgType::BYTEA, buf),
            Value::Char(c) => i8::reinterpret_cast(*c).to_sql(&PgType::CHAR, buf),
            Value::Date(d) => d.pg_epoch_days().to_sql(&PgType::DATE, buf),
            Value::Float4(f) => f.to_sql(&PgType::FLOAT4, buf),
            Value::Float8(f) => f.to_sql(&PgType::FLOAT8, buf),
            Value::Int2(i) => i.to_sql(&PgType::INT2, buf),
            Value::Int4(i) => i.to_sql(&PgType::INT4, buf),
            Value::Int8(i) => i.to_sql(&PgType::INT8, buf),
            Value::UInt2(u) => u.to_sql(&*UINT2, buf),
            Value::UInt4(u) => u.to_sql(&*UINT4, buf),
            Value::UInt8(u) => u.to_sql(&*UINT8, buf),
            Value::Interval(iv) => iv.to_sql(&PgType::INTERVAL, buf),
            Value::Jsonb(js) => js.to_sql(&PgType::JSONB, buf),
            Value::List(_) => {
                // A binary encoding for list is tricky. We only get one OID to
                // describe the type of this list to the client. And we can't
                // just up front allocate an OID for every possible list type,
                // like PostgreSQL does for arrays, because, unlike arrays,
                // lists can be arbitrarily nested.
                //
                // So, we'd need to synthesize a type with a stable OID whenever
                // a new anonymous list type is *observed* in Materialize. Or we
                // could mandate that only named list types can be sent over
                // pgwire, and not anonymous list types, since named list types
                // get a stable OID when they're created. Then we'd need to
                // expose a table with the list OID -> element OID mapping for
                // clients to query. And THEN we'd need to teach every client we
                // care about how to query this table.
                //
                // This isn't intractible. It's how PostgreSQL's range type
                // works, which is supported by many drivers. But our job is
                // harder because most PostgreSQL drivers don't want to carry
                // around code for Materialize-specific types. So we'd have to
                // add type plugin infrastructure for those drivers, then
                // distribute the list/map support as a plugin.
                //
                // Serializing the actual list would be simple, though: just a
                // 32-bit integer describing the list length, followed by the
                // encoding of each element in order.
                //
                // tl;dr it's a lot of work. For now, the recommended workaround
                // is to either use the text encoding or convert the list to a
                // different type (JSON, an array, unnest into rows) that does
                // have a binary encoding.
                Err("binary encoding of list types is not implemented".into())
            }
            Value::Map(_) => {
                // Map binary encodings are hard for the same reason as list
                // binary encodings (described above). You just have key and
                // value OIDs to deal with rather than an element OID.
                Err("binary encoding of map types is not implemented".into())
            }
            Value::Name(s) => s.to_sql(&PgType::NAME, buf),
            // PostgreSQL's `regprocsend` is `int4send`, so binary is identical to
            // an `oid`.
            Value::Oid(i) | Value::RegProc(i) => i.to_sql(&PgType::OID, buf),
            Value::Record(fields) => {
                let nfields = pg_len("record field length", fields.len())?;
                buf.put_i32(nfields);
                let field_types = match ty {
                    Type::Record(fields) => fields,
                    _ => unreachable!(),
                };
                for (f, ty) in fields.iter().zip_eq(field_types) {
                    buf.put_u32(ty.oid());
                    encode_element(buf, f.as_ref(), ty)?;
                }
                Ok(postgres_types::IsNull::No)
            }
            Value::Text(s) => s.to_sql(&PgType::TEXT, buf),
            Value::BpChar(s) => s.to_sql(&PgType::BPCHAR, buf),
            Value::VarChar(s) => s.to_sql(&PgType::VARCHAR, buf),
            Value::Time(t) => t.to_sql(&PgType::TIME, buf),
            Value::Timestamp(ts) => ts.to_sql(&PgType::TIMESTAMP, buf),
            Value::TimestampTz(ts) => ts.to_sql(&PgType::TIMESTAMPTZ, buf),
            Value::Uuid(u) => u.to_sql(&PgType::UUID, buf),
            Value::Numeric(a) => a.to_sql(&PgType::NUMERIC, buf),
            Value::MzTimestamp(t) => t.to_string().to_sql(&PgType::TEXT, buf),
            Value::Range(range) => {
                buf.put_u8(range.pg_flag_bits());

                let elem_type = match ty {
                    Type::Range { element_type } => element_type,
                    _ => unreachable!(),
                };

                if let Some(RangeInner { lower, upper }) = &range.inner {
                    for bound in [&lower.bound, &upper.bound] {
                        if let Some(bound) = bound {
                            let base = buf.len();
                            buf.put_i32(0);
                            bound.encode_binary(elem_type, buf)?;
                            let len = pg_len("encoded range bound", buf.len() - base - 4)?;
                            buf[base..base + 4].copy_from_slice(&len.to_be_bytes());
                        }
                    }
                }
                Ok(postgres_types::IsNull::No)
            }
            Value::MzAclItem(mz_acl_item) => {
                buf.extend_from_slice(&mz_acl_item.encode_binary());
                Ok(postgres_types::IsNull::No)
            }
            Value::AclItem(_) => Err("aclitem has no binary encoding".into()),
        }
        .expect("encode_binary should never trigger a to_sql failure");
        if let IsNull::Yes = is_null {
            panic!("encode_binary impossibly called on a null value")
        }
        Ok(())
    }

    /// Static helper method to pre-validate that a Datum corresponding to
    /// the provided `SqlScalarType` can be converted into a `Value` and then
    /// encoded as binary using `encode_binary` without an error.
    ///
    /// Returns `Ok(())` if the type (including all of its nested element/field
    /// types) supports binary encoding, or `Err(reason)` describing the first
    /// unsupported type encountered. Container types are checked recursively, so
    /// e.g. a record or array that contains a `list` is rejected.
    ///
    /// The error messages mirror PostgreSQL's `no binary output function
    /// available for type <t>` so that drivers and users see a familiar
    /// diagnostic. Callers should report these errors with the SQLSTATE
    /// PostgreSQL uses for the same condition, `42883` (undefined_function).
    pub fn binary_encoding_error(typ: &SqlScalarType) -> Result<(), &'static str> {
        match typ {
            SqlScalarType::Bool => Ok(()),
            SqlScalarType::Int16 => Ok(()),
            SqlScalarType::Int32 => Ok(()),
            SqlScalarType::Int64 => Ok(()),
            SqlScalarType::PgLegacyChar => Ok(()),
            SqlScalarType::UInt16 => Ok(()),
            SqlScalarType::Oid => Ok(()),
            SqlScalarType::RegClass => Ok(()),
            SqlScalarType::RegProc => Ok(()),
            SqlScalarType::RegType => Ok(()),
            SqlScalarType::UInt32 => Ok(()),
            SqlScalarType::UInt64 => Ok(()),
            SqlScalarType::Float32 => Ok(()),
            SqlScalarType::Float64 => Ok(()),
            SqlScalarType::Numeric { .. } => Ok(()),
            SqlScalarType::MzTimestamp => Ok(()),
            SqlScalarType::MzAclItem => Ok(()),
            SqlScalarType::AclItem => Err("no binary output function available for type aclitem"),
            SqlScalarType::Date => Ok(()),
            SqlScalarType::Time => Ok(()),
            SqlScalarType::Timestamp { .. } => Ok(()),
            SqlScalarType::TimestampTz { .. } => Ok(()),
            SqlScalarType::Interval => Ok(()),
            SqlScalarType::Bytes => Ok(()),
            SqlScalarType::String => Ok(()),
            SqlScalarType::VarChar { .. } => Ok(()),
            SqlScalarType::Char { .. } => Ok(()),
            SqlScalarType::PgLegacyName => Ok(()),
            SqlScalarType::Jsonb => Ok(()),
            SqlScalarType::Uuid => Ok(()),
            SqlScalarType::Array(elem_type) => Self::binary_encoding_error(elem_type),
            SqlScalarType::Int2Vector => Ok(()),
            SqlScalarType::List { .. } => Err("no binary output function available for type list"),
            SqlScalarType::Map { .. } => Err("no binary output function available for type map"),
            SqlScalarType::Record { fields, .. } => fields
                .iter()
                .try_for_each(|(_, ty)| Self::binary_encoding_error(&ty.scalar_type)),
            SqlScalarType::Range { element_type } => Self::binary_encoding_error(element_type),
        }
    }

    /// Returns whether a value of the given `SqlScalarType` can be encoded using
    /// the binary format. See [`Value::binary_encoding_error`] for details,
    /// including the (recursive) handling of container types.
    pub fn can_encode_binary(typ: &SqlScalarType) -> bool {
        Self::binary_encoding_error(typ).is_ok()
    }

    /// Deserializes a value of type `ty` from `raw` using the specified
    /// `format`.
    pub fn decode(
        format: Format,
        ty: &Type,
        raw: &[u8],
    ) -> Result<Value, Box<dyn Error + Sync + Send>> {
        match format {
            Format::Text => Value::decode_text(ty, raw),
            Format::Binary => Value::decode_binary(ty, raw),
        }
    }

    /// Deserializes a value of type `ty` from `raw` using the [text encoding
    /// format](Format::Text).
    pub fn decode_text<'a>(
        ty: &'a Type,
        raw: &'a [u8],
    ) -> Result<Value, Box<dyn Error + Sync + Send>> {
        let s = str::from_utf8(raw)?;
        // Match PostgreSQL, which rejects NUL bytes in text-format values of
        // any type as part of client encoding verification.
        reject_nul(s)?;
        Ok(match ty {
            Type::Array(elem_type) => {
                let (elements, dims) = strconv::parse_array(
                    s,
                    || None,
                    |elem_text| Value::decode_text(elem_type, elem_text.as_bytes()).map(Some),
                )?;
                Value::Array { dims, elements }
            }
            Type::Int2Vector { .. } => {
                return Err("input of Int2Vector types is not implemented".into());
            }
            Type::Bool => Value::Bool(strconv::parse_bool(s)?),
            Type::Bytea => Value::Bytea(strconv::parse_bytes(s)?),
            Type::Char => Value::Char(raw.get(0).copied().unwrap_or(0)),
            Type::Date => Value::Date(strconv::parse_date(s)?),
            Type::Float4 => Value::Float4(strconv::parse_float32(s)?),
            Type::Float8 => Value::Float8(strconv::parse_float64(s)?),
            Type::Int2 => Value::Int2(strconv::parse_int16(s)?),
            Type::Int4 => Value::Int4(strconv::parse_int32(s)?),
            Type::Int8 => Value::Int8(strconv::parse_int64(s)?),
            Type::UInt2 => Value::UInt2(UInt2(strconv::parse_uint16(s)?)),
            Type::UInt4 => Value::UInt4(UInt4(strconv::parse_uint32(s)?)),
            Type::UInt8 => Value::UInt8(UInt8(strconv::parse_uint64(s)?)),
            Type::Interval { .. } => Value::Interval(Interval(strconv::parse_interval(s)?)),
            Type::Json => return Err("input of json types is not implemented".into()),
            Type::Jsonb => Value::Jsonb(Jsonb(strconv::parse_jsonb(s)?)),
            Type::List(elem_type) => Value::List(strconv::parse_list(
                s,
                matches!(**elem_type, Type::List(..)),
                || None,
                |elem_text| Value::decode_text(elem_type, elem_text.as_bytes()).map(Some),
            )?),
            Type::Map { value_type } => Value::Map(strconv::parse_map(
                s,
                matches!(**value_type, Type::Map { .. }),
                |elem_text| {
                    elem_text
                        .map(|t| Value::decode_text(value_type, t.as_bytes()))
                        .transpose()
                },
            )?),
            Type::Name => Value::Name(strconv::parse_pg_legacy_name(s)),
            Type::Numeric { constraints } => Value::Numeric(Numeric(rescale_numeric(
                strconv::parse_numeric(s)?,
                constraints.as_ref(),
            )?)),
            Type::Oid | Type::RegClass | Type::RegType => Value::Oid(strconv::parse_oid(s)?),
            Type::RegProc => Value::RegProc(parse_regproc(s)?),
            Type::Record(_) => {
                return Err("input of anonymous composite types is not implemented".into());
            }
            Type::Text => Value::Text(s.to_owned()),
            Type::BpChar { .. } => Value::BpChar(s.to_owned()),
            Type::VarChar { .. } => Value::VarChar(s.to_owned()),
            Type::Time { .. } => Value::Time(strconv::parse_time(s)?),
            Type::TimeTz { .. } => return Err("input of timetz types is not implemented".into()),
            Type::Timestamp { .. } => Value::Timestamp(strconv::parse_timestamp(s)?),
            Type::TimestampTz { .. } => Value::TimestampTz(strconv::parse_timestamptz(s)?),
            Type::Uuid => Value::Uuid(strconv::parse_uuid(s)?),
            Type::MzTimestamp => Value::MzTimestamp(strconv::parse_mz_timestamp(s)?),
            Type::Range { element_type } => Value::Range(strconv::parse_range(s, |elem_text| {
                Value::decode_text(element_type, elem_text.as_bytes()).map(Box::new)
            })?),
            Type::MzAclItem => Value::MzAclItem(strconv::parse_mz_acl_item(s)?),
            Type::AclItem => Value::AclItem(strconv::parse_acl_item(s)?),
        })
    }

    /// Deserializes a value of type `ty` from `s` using the [text encoding format](Format::Text).
    pub fn decode_text_into_row<'a>(
        ty: &'a Type,
        s: &'a str,
        packer: &mut RowPacker,
    ) -> Result<(), Box<dyn Error + Sync + Send>> {
        // Match PostgreSQL, which rejects NUL bytes in text-format values of
        // any type as part of client encoding verification.
        reject_nul(s)?;
        Ok(match ty {
            Type::Array(elem_type) => {
                let (elements, dims) =
                    strconv::parse_array(s, || None, |elem_text| Ok::<_, String>(Some(elem_text)))?;
                // SAFETY: The function returns the number of times it called `push` on the packer.
                unsafe {
                    packer.push_array_with_unchecked(&dims, |packer| {
                        let mut nelements = 0;
                        for element in elements {
                            match element {
                                Some(elem_text) => {
                                    Value::decode_text_into_row(elem_type, &elem_text, packer)?
                                }

                                None => packer.push(Datum::Null),
                            }
                            nelements += 1;
                        }
                        Ok::<_, Box<dyn Error + Sync + Send>>(nelements)
                    })?
                }
            }
            Type::Int2Vector { .. } => {
                return Err("input of Int2Vector types is not implemented".into());
            }
            Type::Bool => packer.push(Datum::from(strconv::parse_bool(s)?)),
            Type::Bytea => packer.push(Datum::Bytes(&strconv::parse_bytes(s)?)),
            Type::Char => packer.push(Datum::UInt8(s.as_bytes().get(0).copied().unwrap_or(0))),
            Type::Date => packer.push(Datum::Date(strconv::parse_date(s)?)),
            Type::Float4 => packer.push(Datum::Float32(strconv::parse_float32(s)?.into())),
            Type::Float8 => packer.push(Datum::Float64(strconv::parse_float64(s)?.into())),
            Type::Int2 => packer.push(Datum::Int16(strconv::parse_int16(s)?)),
            Type::Int4 => packer.push(Datum::Int32(strconv::parse_int32(s)?)),
            Type::Int8 => packer.push(Datum::Int64(strconv::parse_int64(s)?)),
            Type::UInt2 => packer.push(Datum::UInt16(strconv::parse_uint16(s)?)),
            Type::UInt4 => packer.push(Datum::UInt32(strconv::parse_uint32(s)?)),
            Type::UInt8 => packer.push(Datum::UInt64(strconv::parse_uint64(s)?)),
            Type::Interval { .. } => packer.push(Datum::Interval(strconv::parse_interval(s)?)),
            Type::Json => return Err("input of json types is not implemented".into()),
            Type::Jsonb => packer.push(strconv::parse_jsonb(s)?.into_row().unpack_first()),
            Type::List(elem_type) => {
                let elems = strconv::parse_list(
                    s,
                    matches!(**elem_type, Type::List(..)),
                    || None,
                    |elem_text| Ok::<_, String>(Some(elem_text)),
                )?;
                packer.push_list_with(|packer| {
                    for elem in elems {
                        match elem {
                            Some(elem) => Value::decode_text_into_row(elem_type, &elem, packer)?,
                            None => packer.push(Datum::Null),
                        }
                    }
                    Ok::<_, Box<dyn Error + Sync + Send>>(())
                })?;
            }
            Type::Map { value_type } => {
                let map =
                    strconv::parse_map(s, matches!(**value_type, Type::Map { .. }), |elem_text| {
                        elem_text.map(Ok::<_, String>).transpose()
                    })?;
                packer.push_dict_with(|row| {
                    for (k, v) in map {
                        row.push(Datum::String(&k));
                        match v {
                            Some(elem) => Value::decode_text_into_row(value_type, &elem, row)?,
                            None => row.push(Datum::Null),
                        }
                    }
                    Ok::<_, Box<dyn Error + Sync + Send>>(())
                })?;
            }
            Type::Name => packer.push(Datum::String(&strconv::parse_pg_legacy_name(s))),
            Type::Numeric { constraints } => packer.push(Datum::Numeric(rescale_numeric(
                strconv::parse_numeric(s)?,
                constraints.as_ref(),
            )?)),
            Type::Oid | Type::RegClass | Type::RegType => {
                packer.push(Datum::UInt32(strconv::parse_oid(s)?))
            }
            Type::RegProc => packer.push(Datum::UInt32(parse_regproc(s)?)),
            Type::Record(_) => {
                return Err("input of anonymous composite types is not implemented".into());
            }
            Type::Text => packer.push(Datum::String(s)),
            Type::BpChar { .. } => packer.push(Datum::String(s.trim_end())),
            Type::VarChar { .. } => packer.push(Datum::String(s)),
            Type::Time { .. } => packer.push(Datum::Time(strconv::parse_time(s)?)),
            Type::TimeTz { .. } => return Err("input of timetz types is not implemented".into()),
            Type::Timestamp { .. } => packer.push(Datum::Timestamp(strconv::parse_timestamp(s)?)),
            Type::TimestampTz { .. } => {
                packer.push(Datum::TimestampTz(strconv::parse_timestamptz(s)?))
            }
            Type::Uuid => packer.push(Datum::Uuid(strconv::parse_uuid(s)?)),
            Type::MzTimestamp => packer.push(Datum::MzTimestamp(strconv::parse_mz_timestamp(s)?)),
            Type::Range { element_type } => {
                let range = strconv::parse_range(s, |elem_text| {
                    Value::decode_text(element_type, elem_text.as_bytes()).map(Box::new)
                })?;
                // TODO: We should be able to push ranges without scratch space, but that requires
                // a different `push_range` API.
                let buf = RowArena::new();
                let range = range
                    .try_into_bounds(|elem| elem.into_datum(&buf, element_type))
                    .map_err(Box::<dyn Error + Sync + Send>::from)?;
                packer
                    .push_range(range)
                    .map_err(Box::<dyn Error + Sync + Send>::from)?;
            }
            Type::MzAclItem => packer.push(Datum::MzAclItem(strconv::parse_mz_acl_item(s)?)),
            Type::AclItem => packer.push(Datum::AclItem(strconv::parse_acl_item(s)?)),
        })
    }

    /// Deserializes a value of type `ty` from `raw` using the [binary encoding
    /// format](Format::Binary).
    pub fn decode_binary(ty: &Type, raw: &[u8]) -> Result<Value, Box<dyn Error + Sync + Send>> {
        match ty {
            Type::Array(_) => Err("input of array types is not implemented".into()),
            Type::Int2Vector => Err("input of int2vector types is not implemented".into()),
            Type::Bool => bool::from_sql(ty.inner(), raw).map(Value::Bool),
            Type::Bytea => Vec::<u8>::from_sql(ty.inner(), raw).map(Value::Bytea),
            Type::Char => {
                i8::from_sql(ty.inner(), raw).map(|c| Value::Char(u8::reinterpret_cast(c)))
            }
            Type::Date => {
                let days = i32::from_sql(ty.inner(), raw)?;
                Ok(Value::Date(Date::from_pg_epoch(days)?))
            }
            Type::Float4 => f32::from_sql(ty.inner(), raw).map(Value::Float4),
            Type::Float8 => f64::from_sql(ty.inner(), raw).map(Value::Float8),
            Type::Int2 => i16::from_sql(ty.inner(), raw).map(Value::Int2),
            Type::Int4 => i32::from_sql(ty.inner(), raw).map(Value::Int4),
            Type::Int8 => i64::from_sql(ty.inner(), raw).map(Value::Int8),
            Type::UInt2 => UInt2::from_sql(ty.inner(), raw).map(Value::UInt2),
            Type::UInt4 => UInt4::from_sql(ty.inner(), raw).map(Value::UInt4),
            Type::UInt8 => UInt8::from_sql(ty.inner(), raw).map(Value::UInt8),
            Type::Interval { .. } => Interval::from_sql(ty.inner(), raw).map(Value::Interval),
            Type::Json => Err("input of json types is not implemented".into()),
            Type::Jsonb => Jsonb::from_sql(ty.inner(), raw).map(Value::Jsonb),
            Type::List(_) => Err("binary decoding of list types is not implemented".into()),
            Type::Map { .. } => Err("binary decoding of map types is not implemented".into()),
            Type::Name => {
                let s = String::from_sql(ty.inner(), raw)?;
                reject_nul(&s)?;
                if s.len() > NAME_MAX_BYTES {
                    return Err("identifier too long".into());
                }
                Ok(Value::Name(s))
            }
            Type::Numeric { constraints } => {
                let n = Numeric::from_sql(ty.inner(), raw)?;
                // The wire format's `0xD000`/`0xF000` sign words spell
                // `±Infinity`, which `Numeric::from_sql` decodes because it also
                // decodes query *results*, where an infinite numeric is
                // legitimate (aggregation overflow produces one). As a parameter
                // it must be rejected: the text path rejects `'Infinity'::numeric`
                // (`strconv::parse_numeric`), so accepting the binary spelling
                // would let a client smuggle in a value no SQL literal can name.
                if n.0.0.is_infinite() {
                    return Err("numeric infinity is not supported".into());
                }
                Ok(Value::Numeric(Numeric(rescale_numeric(
                    n.0,
                    constraints.as_ref(),
                )?)))
            }
            Type::Oid | Type::RegClass | Type::RegType => {
                u32::from_sql(ty.inner(), raw).map(Value::Oid)
            }
            Type::RegProc => u32::from_sql(ty.inner(), raw).map(Value::RegProc),
            Type::Record(_) => Err("input of anonymous composite types is not implemented".into()),
            Type::Text => decode_binary_string(ty, raw).map(Value::Text),
            Type::BpChar { .. } => decode_binary_string(ty, raw).map(Value::BpChar),
            Type::VarChar { .. } => decode_binary_string(ty, raw).map(Value::VarChar),
            Type::Time { .. } => {
                // The wire value is microseconds since midnight. Do not use
                // `NaiveTime::from_sql`. Its duration arithmetic silently
                // wraps around midnight, turning out-of-range values like
                // 24:00:00 into 00:00:00. Reject them instead, including
                // 24:00:00 itself, which `NaiveTime` cannot represent and
                // the text path rejects too.
                const USECS_PER_DAY: i64 = 24 * 60 * 60 * 1_000_000;
                let usecs = i64::from_sql(ty.inner(), raw)?;
                if !(0..USECS_PER_DAY).contains(&usecs) {
                    return Err("time out of range".into());
                }
                let secs = u32::try_from(usecs / 1_000_000).expect("less than 86,400");
                let nanos = u32::try_from(usecs % 1_000_000).expect("less than 1,000,000") * 1_000;
                Ok(Value::Time(
                    NaiveTime::from_num_seconds_from_midnight_opt(secs, nanos)
                        .expect("validated against USECS_PER_DAY"),
                ))
            }
            Type::TimeTz { .. } => Err("input of timetz types is not implemented".into()),
            Type::Timestamp { .. } => {
                let ts = NaiveDateTime::from_sql(ty.inner(), raw)?;
                Ok(Value::Timestamp(CheckedTimestamp::from_timestamplike(ts)?))
            }
            Type::TimestampTz { .. } => {
                let ts = DateTime::<Utc>::from_sql(ty.inner(), raw)?;
                Ok(Value::TimestampTz(CheckedTimestamp::from_timestamplike(
                    ts,
                )?))
            }
            Type::Uuid => Uuid::from_sql(ty.inner(), raw).map(Value::Uuid),
            Type::MzTimestamp => {
                let s = String::from_sql(ty.inner(), raw)?;
                let t: mz_repr::Timestamp = s.parse()?;
                Ok(Value::MzTimestamp(t))
            }
            Type::Range { .. } => Err("binary decoding of range types is not implemented".into()),
            Type::MzAclItem => {
                let mz_acl_item = MzAclItem::decode_binary(raw)?;
                Ok(Value::MzAclItem(mz_acl_item))
            }
            Type::AclItem => Err("aclitem has no binary encoding".into()),
        }
    }
}

/// The text PostgreSQL's `regprocout` emits for OID 0, and that `regprocin`
/// reads back as OID 0.
const REGPROC_NULL: &str = "-";

/// Parses the text format of a `regproc`, matching PostgreSQL's `regprocin`.
///
/// Accepting names is what keeps a `COPY ... TO` rendering loadable by
/// `COPY ... FROM`, since the text encoding emits names. An overloaded name
/// renders schema-qualified and names every one of its impls, so it does not
/// round trip, which is true of PostgreSQL as well.
fn parse_regproc(s: &str) -> Result<u32, Box<dyn Error + Sync + Send>> {
    if s == REGPROC_NULL {
        return Ok(0);
    }
    match regproc::oid(s) {
        Ok(oid) => Ok(oid),
        // PostgreSQL refuses the same input rather than picking an overload.
        Err(regproc::NameLookupError::Ambiguous) => {
            Err(format!("more than one function named \"{}\"", s).into())
        }
        Err(regproc::NameLookupError::NotFound) => match strconv::parse_oid(s) {
            Ok(oid) => Ok(oid),
            // Number-shaped input keeps its numeric diagnosis, which is what
            // reports an out of range OID. Anything else was meant as a name, so
            // report a missing function, matching PostgreSQL.
            Err(err) if is_number_shaped(s) => Err(err.into()),
            Err(_) => Err(format!("function \"{}\" does not exist", s).into()),
        },
    }
}

/// Whether `s` is shaped like a decimal number, ignoring whether it is in range.
fn is_number_shaped(s: &str) -> bool {
    let digits = s.trim();
    let digits = digits.strip_prefix(['+', '-']).unwrap_or(digits);
    !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit())
}

/// Session settings that affect how values are encoded as text.
///
/// PostgreSQL's text output for some types depends on session state. Encoders
/// whose output must not depend on the session, such as everything evaluated
/// in the dataflow layer, use [`TextEncodeSettings::STABLE`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TextEncodeSettings {
    /// PostgreSQL's `extra_float_digits`: positive values select the shortest
    /// round-trippable encoding for `float4` and `float8`, while zero and
    /// negative values limit output to `FLOAT4_DIGITS` or `FLOAT8_DIGITS` plus
    /// this value significant digits.
    pub extra_float_digits: i32,
}

impl TextEncodeSettings {
    /// Settings that do not depend on session state.
    pub const STABLE: TextEncodeSettings = TextEncodeSettings {
        extra_float_digits: 1,
    };
}

/// The number of significant decimal digits that survive a round trip through
/// `f32` and `f64` respectively.
const FLOAT4_DIGITS: i32 = 6;
const FLOAT8_DIGITS: i32 = 15;

/// Formats `f` with `ndig` significant digits like C's `%.*g`, mirroring
/// PostgreSQL's `float4out`/`float8out` when `extra_float_digits` is zero or
/// negative. Like PostgreSQL, `ndig` values below 1 are clamped to 1, and
/// non-finite values are spelled `NaN`, `Infinity`, and `-Infinity`.
fn format_float_limited(buf: &mut BytesMut, f: f64, ndig: i32) -> Nestable {
    if f.is_nan() {
        buf.write_str("NaN");
        return Nestable::Yes;
    }
    if f.is_infinite() {
        buf.write_str(if f < 0.0 { "-Infinity" } else { "Infinity" });
        return Nestable::Yes;
    }
    let ndig = ndig.max(1);
    // The exponent decides between the two notations, and it must be taken
    // after rounding to `ndig` digits, as rounding can carry into the next
    // exponent. `sci` has the shape `d[.ddd]e<exp>`.
    let prec = usize::try_from(ndig - 1).expect("ndig is at least 1");
    let sci = format!("{:.prec$e}", f);
    let (mantissa, exp) = sci.split_once('e').expect("e format has an exponent");
    let exp: i32 = exp.parse().expect("valid exponent");
    if exp < -4 || exp >= ndig {
        // Scientific notation. `%g` strips the fraction's trailing zeros and
        // pads the exponent to at least two digits.
        let mantissa = mantissa.trim_end_matches('0').trim_end_matches('.');
        write!(buf, "{mantissa}e{exp:+03}");
    } else {
        // Fixed-point notation. Rounding to `ndig - 1 - exp` decimal places
        // leaves exactly `ndig` significant digits. Trailing zeros are
        // stripped.
        let decimals = usize::try_from(ndig - 1 - exp).expect("exp is less than ndig");
        let fixed = format!("{f:.decimals$}");
        let fixed = match fixed.contains('.') {
            true => fixed.trim_end_matches('0').trim_end_matches('.'),
            false => &fixed,
        };
        buf.write_str(fixed);
    }
    Nestable::Yes
}

/// Returns an error if `s` contains a NUL character, which PostgreSQL rejects
/// in text values.
fn reject_nul(s: &str) -> Result<(), Box<dyn Error + Sync + Send>> {
    if s.contains('\0') {
        Err(Box::new(NulCharacterError))
    } else {
        Ok(())
    }
}

/// Decodes a binary-format string value, rejecting embedded NUL characters.
fn decode_binary_string(ty: &Type, raw: &[u8]) -> Result<String, Box<dyn Error + Sync + Send>> {
    let s = String::from_sql(ty.inner(), raw)?;
    reject_nul(&s)?;
    Ok(s)
}

/// Rescales `n` to the scale required by `constraints`, if any.
fn rescale_numeric(
    mut n: OrderedDecimal<mz_repr_numeric::Numeric>,
    constraints: Option<&NumericConstraints>,
) -> Result<OrderedDecimal<mz_repr_numeric::Numeric>, Box<dyn Error + Sync + Send>> {
    if let Some(constraints) = constraints {
        rescale(
            &mut n.0,
            NumericMaxScale::try_from(i64::from(constraints.max_scale()))?.into_u8(),
        )?;
    }
    Ok(n)
}

fn encode_element(buf: &mut BytesMut, elem: Option<&Value>, ty: &Type) -> Result<(), io::Error> {
    match elem {
        None => buf.put_i32(-1),
        Some(elem) => {
            let base = buf.len();
            buf.put_i32(0);
            elem.encode_binary(ty, buf)?;
            let len = pg_len("encoded element", buf.len() - base - 4)?;
            buf[base..base + 4].copy_from_slice(&len.to_be_bytes());
        }
    }
    Ok(())
}

fn pg_len(what: &str, len: usize) -> Result<i32, io::Error> {
    len.try_into().map_err(|_| {
        io::Error::new(
            io::ErrorKind::InvalidData,
            format!("{} does not fit into an i32", what),
        )
    })
}

/// Converts a Materialize row into a vector of PostgreSQL values.
///
/// Calling this function is equivalent to mapping [`Value::from_datum`] over
/// every datum in `row`.
pub fn values_from_row(row: &RowRef, typ: &SqlRelationType) -> Vec<Option<Value>> {
    row.iter()
        .zip_eq(typ.column_types.iter())
        .map(|(col, typ)| Value::from_datum(col, &typ.scalar_type))
        .collect()
}

#[cfg(test)]
mod tests {
    use mz_repr::arb_datum_for_scalar;
    use proptest::prelude::*;

    use super::*;

    /// Property test: [`Value::binary_encoding_error`] agrees with the actual
    /// behavior of [`Value::encode_binary`] for every `(SqlScalarType, Datum)`
    /// pair the proptest infrastructure can generate.
    ///
    /// This guards against future drift between the static predicate and the
    /// encoder: any new `SqlScalarType` variant whose classification disagrees
    /// with what `encode_binary` actually does will surface here.
    #[mz_ore::test]
    #[cfg_attr(miri, ignore)] // numeric/decimal contexts unsupported under miri
    fn proptest_binary_encoding_error_matches_encode_binary() {
        let strat =
            any::<SqlScalarType>().prop_flat_map(|ty| (Just(ty.clone()), arb_datum_for_scalar(ty)));
        proptest!(ProptestConfig::with_cases(256), |((ty, prop_datum) in strat)| {
            // `binary_encoding_error` is a precondition for callers of
            // `encode_binary`: if it returns `Ok`, then encoding must succeed
            // (and not panic via the internal `.expect`).
            if Value::binary_encoding_error(&ty).is_err() {
                return Ok(());
            }
            let datum = Datum::from(&prop_datum);
            let value = match Value::from_datum(datum, &ty) {
                Some(v) => v,
                // `Datum::Null` produces `None`; nothing to encode.
                None => return Ok(()),
            };
            let pg_ty = Type::from(&ty);
            let mut buf = BytesMut::new();
            value
                .encode_binary(&pg_ty, &mut buf)
                .expect("encode_binary must succeed when binary_encoding_error returns Ok");
        });
    }

    /// A `regproc` renders as the function's name in text format and as a bare
    /// OID in binary, which is what PostgreSQL's `regprocout` and
    /// `regprocsend` do.
    #[mz_ore::test]
    fn regproc_text_encoding_resolves_names() {
        // 1242 is `boolin`, uniquely named. 1398 is one of six `abs` overloads,
        // so PostgreSQL qualifies it. 99999 names no function. The qualified
        // overload does not round trip, because its rendering names all six.
        for (oid, expected, round_trips) in [
            (0, "-", true),
            (1242, "boolin", true),
            (1398, "pg_catalog.abs", false),
            (99999, "99999", true),
            (u32::MAX, "4294967295", true),
        ] {
            let mut buf = BytesMut::new();
            Value::from_datum(Datum::UInt32(oid), &SqlScalarType::RegProc)
                .expect("a non-null datum encodes")
                .encode_text(&mut buf, TextEncodeSettings::STABLE);
            assert_eq!(str::from_utf8(&buf).unwrap(), expected, "regproc {oid}");

            if round_trips {
                let Value::RegProc(decoded) = Value::decode_text(&Type::RegProc, &buf).unwrap()
                else {
                    panic!("decoding a regproc must yield Value::RegProc");
                };
                assert_eq!(decoded, oid, "text rendering {expected} did not round trip");
            }

            let mut binary = BytesMut::new();
            Value::RegProc(oid)
                .encode_binary(&Type::RegProc, &mut binary)
                .expect("regproc has a binary encoding");
            assert_eq!(&binary[..], &oid.to_be_bytes()[..], "regproc {oid} binary");
        }
    }

    /// An overloaded name is an error rather than an arbitrary choice, which is
    /// what PostgreSQL does too.
    #[mz_ore::test]
    fn regproc_text_decoding_rejects_ambiguous_names() {
        assert_eq!(
            Value::decode_text(&Type::RegProc, b"pg_catalog.abs")
                .map(|_| ())
                .map_err(|e| e.to_string())
                .unwrap_err(),
            "more than one function named \"pg_catalog.abs\"",
        );
        assert_eq!(
            Value::decode_text(&Type::RegProc, b"no_such_function")
                .map(|_| ())
                .map_err(|e| e.to_string())
                .unwrap_err(),
            "function \"no_such_function\" does not exist",
        );
        let out_of_range = Value::decode_text(&Type::RegProc, b"99999999999999")
            .map(|_| ())
            .map_err(|e| e.to_string())
            .unwrap_err();
        assert!(
            out_of_range.starts_with("invalid input syntax for type oid"),
            "unexpected error for an out of range OID: {out_of_range}",
        );
    }

    /// [`format_float_limited`] must match C's `%.*g`, which PostgreSQL's
    /// `float4out`/`float8out` use when `extra_float_digits` is zero or
    /// negative.
    #[mz_ore::test]
    fn format_float_limited_matches_printf_g() {
        for (f, ndig, expected) in [
            (0.1_f64 + 0.2_f64, 15, "0.3"),
            (0.1_f64 + 0.2_f64, 1, "0.3"),
            (f64::from(123.45679_f32), 6, "123.457"),
            (f64::from(123.45679_f32), 3, "123"),
            (1e15, 15, "1e+15"),
            (-123456.0, 3, "-1.23e+05"),
            (999.999, 3, "1e+03"),
            (0.0001, 15, "0.0001"),
            (-0.00001, 15, "-1e-05"),
            (0.0, 15, "0"),
            (-0.0, 15, "-0"),
            (100.0, 15, "100"),
            (1.23456789012345, 12, "1.23456789012"),
            (f64::NAN, 15, "NaN"),
            (f64::INFINITY, 15, "Infinity"),
            (f64::NEG_INFINITY, -100, "-Infinity"),
            // `ndig` values below 1 clamp to 1.
            (0.1_f64 + 0.2_f64, -5, "0.3"),
        ] {
            let mut buf = BytesMut::new();
            format_float_limited(&mut buf, f, ndig);
            assert_eq!(
                str::from_utf8(&buf).unwrap(),
                expected,
                "{f} with {ndig} digits"
            );
        }
    }

    /// Verifies that we correctly print the chain of parsing errors, all the way through the stack.
    #[mz_ore::test]
    fn decode_text_error_smoke_test() {
        let bool_array = Value::Array {
            dims: vec![ArrayDimension {
                lower_bound: 0,
                length: 1,
            }],
            elements: vec![Some(Value::Bool(true))],
        };

        let mut buf = BytesMut::new();
        bool_array.encode_text(&mut buf, TextEncodeSettings::STABLE);
        let buf = buf.to_vec();

        let int_array_tpe = Type::Array(Box::new(Type::Int4));
        let decoded_int_array = Value::decode_text(&int_array_tpe, &buf);

        assert_eq!(
            decoded_int_array.map_err(|e| e.to_string()).unwrap_err(),
            "invalid input syntax for type array: Specifying array lower bounds is not supported: \"[0:0]={t}\"".to_string()
        );
    }

    /// Decoding a numeric must round it to the destination's declared scale,
    /// and the text and binary paths must agree. `COPY ... FROM` relies on the
    /// text/CSV side of this (SS-193); binary parameters rely on the binary
    /// side. `COPY ... FORMAT BINARY` is unsupported, so the binary path is
    /// exercised here rather than via mzcompose.
    #[mz_ore::test]
    #[cfg_attr(miri, ignore)] // numeric/decimal contexts unsupported under miri
    fn decode_numeric_applies_destination_scale() {
        // A `numeric(10, 2)` destination: scale 2.
        let ty = Type::from(&SqlScalarType::Numeric {
            max_scale: Some(NumericMaxScale::try_from(2_i64).unwrap()),
        });
        let expected = strconv::parse_numeric("10.45").unwrap();

        // Encode an over-scale value (10.447, scale 3) to binary, then decode
        // it back through the scale-2 type.
        let input = Value::Numeric(Numeric(strconv::parse_numeric("10.447").unwrap()));
        let mut buf = BytesMut::new();
        input
            .encode_binary(&ty, &mut buf)
            .expect("encoding 10.447 as numeric must succeed");
        let Value::Numeric(Numeric(binary)) = Value::decode_binary(&ty, &buf).unwrap() else {
            panic!("decode_binary of a numeric must yield Value::Numeric");
        };
        assert_eq!(binary, expected, "binary decode did not rescale to scale 2");

        // The text path must agree with the binary path.
        let Value::Numeric(Numeric(text)) = Value::decode_text(&ty, b"10.447").unwrap() else {
            panic!("decode_text of a numeric must yield Value::Numeric");
        };
        assert_eq!(text, expected, "text decode did not rescale to scale 2");
    }

    /// The numeric wire format's `±Infinity` sign words must be rejected as a
    /// parameter, matching the text path, which rejects `'Infinity'::numeric`.
    #[mz_ore::test]
    #[cfg_attr(miri, ignore)] // numeric/decimal contexts unsupported under miri
    fn decode_binary_numeric_rejects_infinity() {
        let ty = Type::Numeric { constraints: None };
        // units = 0, weight = 0, sign, dscale = 0.
        let header = |sign: u16| {
            let mut b = Vec::new();
            b.extend_from_slice(&0i16.to_be_bytes());
            b.extend_from_slice(&0i16.to_be_bytes());
            b.extend_from_slice(&sign.to_be_bytes());
            b.extend_from_slice(&0i16.to_be_bytes());
            b
        };
        // +Infinity and -Infinity.
        for sign in [0xD000, 0xF000] {
            let res = Value::decode_binary(&ty, &header(sign));
            assert_eq!(
                res.map(|_| ()).map_err(|e| e.to_string()).unwrap_err(),
                "numeric infinity is not supported",
                "sign {sign:#x} must be rejected",
            );
        }
        // NaN, which the text path does accept, still decodes.
        let Value::Numeric(Numeric(nan)) = Value::decode_binary(&ty, &header(0xC000)).unwrap()
        else {
            panic!("decode_binary of a numeric must yield Value::Numeric");
        };
        assert_eq!(nan, strconv::parse_numeric("NaN").unwrap());
    }

    /// Binary time values are microseconds since midnight. Out-of-range
    /// values, including 24:00:00, must error rather than silently wrap
    /// around midnight (SQL-473).
    #[mz_ore::test]
    fn decode_binary_time_rejects_out_of_range() {
        const USECS_PER_DAY: i64 = 24 * 60 * 60 * 1_000_000;
        let ty = Type::Time { precision: None };

        for usecs in [USECS_PER_DAY, USECS_PER_DAY + 1, -1, i64::MIN, i64::MAX] {
            let res = Value::decode_binary(&ty, &usecs.to_be_bytes());
            assert_eq!(
                res.map(|_| ()).map_err(|e| e.to_string()).unwrap_err(),
                "time out of range",
                "{usecs} microseconds must be rejected",
            );
        }

        let Value::Time(t) = Value::decode_binary(&ty, &(USECS_PER_DAY - 1).to_be_bytes()).unwrap()
        else {
            panic!("decoding a time value must yield Value::Time");
        };
        assert_eq!(
            t,
            NaiveTime::from_hms_micro_opt(23, 59, 59, 999_999).unwrap()
        );
    }

    /// Text values must never contain NUL characters, in either wire format.
    #[mz_ore::test]
    fn decode_rejects_nul_in_strings() {
        const NUL_ERR: &str = "invalid byte sequence for encoding \"UTF8\": 0x00";
        let raw = b"foo\x00bar";

        for ty in [
            Type::Text,
            Type::BpChar { length: None },
            Type::VarChar { max_length: None },
            Type::Name,
        ] {
            for format in [Format::Text, Format::Binary] {
                let res = Value::decode(format, &ty, raw);
                assert_eq!(
                    res.map(|_| ()).map_err(|e| e.to_string()).unwrap_err(),
                    NUL_ERR,
                    "{ty:?} in {format:?} format must reject NUL",
                );
            }
        }

        // The text format rejects NUL bytes regardless of the target type.
        let res = Value::decode_text(&Type::Bytea, b"\\x00\x00");
        assert_eq!(
            res.map(|_| ()).map_err(|e| e.to_string()).unwrap_err(),
            NUL_ERR,
        );

        // NUL-free values still decode.
        let Value::Text(s) = Value::decode(Format::Binary, &Type::Text, b"foobar").unwrap() else {
            panic!("decoding a text value must yield Value::Text");
        };
        assert_eq!(s, "foobar");
    }
}