IP address functions

12 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

ip_cut_ipv6

Masks trailing IPv6 or mapped-IPv4 bytes before returning address text.

ip_cut_ipv6(address:fixed_string(16),ipv6_bytes:uint8,ipv4_bytes:uint8) -> string

Takes sixteen address bytes plus separate suffix-byte counts for ordinary IPv6 and IPv4-mapped input. It zeros the selected trailing bytes before formatting and returns NULL when any argument is NULL. A mask exceeding the relevant address width raises INVALID_ARGUMENT; the operation is pure formatting rather than anonymization with secret state.

Example

ip_cut_ipv6(
  cast(X '00000000000000000000000000000001' AS fixed_string(16)),
  1,
  1
)
-- → '::'

ip_ipv4_cidr_to_range

Finds the first and last IPv4 addresses covered by a prefix length.

ip_ipv4_cidr_to_range(address:ipv4,prefix:uint8) -> tuple(ipv4,ipv4)

Clears or sets the host bits to return an inclusive tuple of native ipv4 bounds. Prefix zero spans the full address space, and prefix thirty-two selects only the supplied address. NULL propagates; prefixes outside zero through thirty-two raise INVALID_ARGUMENT.

Example

ip_ipv4_cidr_to_range(cast('192.0.2.7' AS ipv4), 24)
-- → (192.0.2.0, 192.0.2.255)

ip_ipv4_num_to_string

Formats a 32-bit network address as four dotted decimal octets.

ip_ipv4_num_to_string(address:uint32) -> string

Interprets the uint32 in network-order significance and emits canonical dotted-decimal IPv4 text. No hostname resolution occurs and every uint32 bit pattern is a representable address. NULL returns NULL, while an argument outside the required unsigned width raises TYPE_MISMATCH.

Example

ip_ipv4_num_to_string(cast(3232235777 AS UINT32))
-- → '192.168.1.1'

ip_ipv4_string_to_num

Parses dotted IPv4 text into its unsigned network-order integer.

ip_ipv4_string_to_num(text:string) -> uint32

Requires a strict four-octet address with each decimal component in range, rather than accepting a hostname or abbreviated network syntax. Invalid text raises INVALID_IP_ADDRESS and SQL NULL produces NULL. The uint32 result orders the first displayed octet as the most significant byte.

Example

ip_ipv4_string_to_num('192.168.1.1')
-- → 3232235777

ip_ipv4_to_ipv6

Embeds a typed IPv4 value in the IPv4-mapped IPv6 address range.

ip_ipv4_to_ipv6(address:ipv4) -> ipv6

Constructs the standard mapped prefix followed by the IPv4 address’s thirty-two bits. The result is a native ipv6 value, preserving the source address without a DNS query or textual heuristic. NULL returns NULL and non-ipv4 inputs raise TYPE_MISMATCH until explicitly converted.

Example

ip_ipv4_to_ipv6(cast('192.0.2.1' AS ipv4))
-- → ::ffff:192.0.2.1

ip_ipv6_cidr_to_range

Expands an IPv6 network prefix into inclusive lower and upper addresses.

ip_ipv6_cidr_to_range(address:ipv6,prefix:uint8) -> tuple(ipv6,ipv6)

Returns two ipv6 values by replacing every bit after the prefix with zero or one. A full-length prefix produces identical endpoints, while length zero covers all 128-bit addresses. NULL arguments yield NULL and a length greater than 128 raises INVALID_ARGUMENT.

Example

ip_ipv6_cidr_to_range(cast('::1' AS ipv6), 128)
-- → (::1, ::1)

ip_ipv6_num_to_string

Renders sixteen network-order address bytes in canonical IPv6 notation.

ip_ipv6_num_to_string(address:fixed_string(16)) -> string

Interprets fixed_string(16) as an IPv6 address and applies canonical compressed text formatting. The function only formats supplied bits and never performs network lookup. NULL propagates; a value with the wrong byte length or logical descriptor raises TYPE_MISMATCH.

Example

ip_ipv6_num_to_string(
  cast(X '00000000000000000000000000000001' AS fixed_string(16))
)
-- → '::1'

ip_ipv6_string_to_num

Parses compressed colon-separated address notation into a fixed binary representation.

ip_ipv6_string_to_num(text:string) -> fixed_string(16)

Parses an IPv6 address, expands compressed groups and stores its bits in fixed_string(16). Malformed address text raises INVALID_IP_ADDRESS rather than returning zero bytes. SQL NULL remains NULL, and the binary output has no host-dependent endianness or trailing terminator.

Example

hex_encode(ip_ipv6_string_to_num('::1'))
-- → '00000000000000000000000000000001'

ip_is_ip_address_in_range

Checks membership of an address in a textual IPv4 or IPv6 CIDR network.

ip_is_ip_address_in_range(address:string,cidr:string) -> bool

Parses both the address and CIDR, then compares their network bits using the stated prefix length. Incompatible address families do not match; malformed addresses, networks or prefix lengths raise INVALID_IP_ADDRESS. SQL NULL propagates and no stored CIDR type or network request is introduced.

Example

ip_is_ip_address_in_range('192.0.2.9', '192.0.2.0/24')
-- → true

ip_is_ipv4_string

Recognizes strict dotted-decimal address syntax without converting the result.

ip_is_ipv4_string(text:string) -> bool

Returns true only for valid IPv4 text under the parser’s strict octet rules. Malformed input produces false rather than INVALID_IP_ADDRESS, and NULL produces NULL. Hostnames and IPv6 literals are false; a nonstring argument raises TYPE_MISMATCH.

Example

ip_is_ipv4_string('192.0.2.1')
-- → true

ip_is_ipv6_string

Tests whether textual input denotes a valid IPv6 address.

ip_is_ipv6_string(text:string) -> bool

Valid compressed or expanded IPv6 syntax returns true; malformed groups and plain IPv4 notation return false. The predicate does not resolve hostnames and deliberately avoids parse exceptions for invalid text. NULL remains NULL, while incompatible argument types raise TYPE_MISMATCH.

Example

ip_is_ipv6_string('2001:db8::1')
-- → true

ip_reverse_dns_query

Builds a PTR lookup name from an address without contacting DNS.

ip_reverse_dns_query(ipv4) -> string
ip_reverse_dns_query(ipv6) -> string

An IPv4 address becomes reversed decimal octets under in-addr.arpa, while IPv6 becomes reversed hexadecimal nibbles under ip6.arpa. The output is only the query name, so it is deterministic and eligible for stateless continuous evaluation. NULL returns NULL and incompatible source types raise TYPE_MISMATCH.

Example

ip_reverse_dns_query(cast('192.0.2.1' AS ipv4))
-- → '1.2.0.192.in-addr.arpa'