Data Types

AionDB implements a practical SQL type set with PostgreSQL-facing names where possible.

The type system is part of the compatibility contract. PostgreSQL exposes many aliases and subtle behaviors, so v0.1 users should validate the exact types their application or driver uses.

Core scalar types

The runtime stores every column value as one of the variants of the internal DataType enum. The PG-facing names and OIDs below are what the wire protocol and pg_catalog views report.

PostgreSQL aliases (for example INTEGER, INT4, VARCHAR(n), BPCHAR, NAME, OID, the reg* family) parse where supported and are folded into one of the canonical types above. Treat alias parsing as best-effort: prefer the canonical name in fixtures and tests so the type the engine actually stores is unambiguous.

Choosing types

Use the simplest type that represents the application value:

Avoid using PostgreSQL-specific aliases in examples unless the compatibility behavior is what you are testing. Canonical type names make fixtures easier to read.

Date and time

Supported type names include:

• DATE
• TIME
• TIMETZ
• TIMESTAMP
• TIMESTAMPTZ
• INTERVAL

PostgreSQL date/time semantics are broad. Validate exact parsing, formatting, timezone, and interval arithmetic behavior before relying on compatibility-sensitive workloads.

For application tests, include:

• timezone conversion cases;
• date-only values;
• timestamp values near daylight-saving changes if relevant;
• interval arithmetic used by the application;
• driver round-trips from application values to SQL and back.

JSON and arrays

JSON and JSONB parse to AionDB's JSONB representation. Arrays are represented as TYPE[] or compatible PostgreSQL array spellings where implemented.

JSON and array support should be tested with the operators your workload needs. A parser accepting the type name does not imply every PostgreSQL JSONB operator, containment behavior, path operator, or array operation is implemented.

Recommended evaluation:

CREATE TABLE payloads (
    id INT PRIMARY KEY,
    body JSONB,
    tags TEXT[]
);

Then test inserts, selects, casts, nulls, and the exact predicates generated by your application.

Network and system-facing types

AionDB includes parser and catalog support for types such as:

• MACADDR
• MACADDR8
• TID
• PG_LSN

These are mainly for PostgreSQL compatibility surfaces and catalog behavior.

Treat these types as compatibility surfaces first. If a driver or ORM introspection query expects them, verify catalog output and wire encoding before relying on application-level behavior.

Vector type

Vectors use fixed dimensions:

CREATE TABLE items (
    id INT,
    embedding VECTOR(3)
);

INSERT INTO items VALUES (1, '[1.0,2.0,3.0]');

Distance functions include:

SELECT l2_distance(embedding, '[1.0,0.0,0.0]') FROM items;
SELECT cosine_distance(embedding, '[1.0,0.0,0.0]') FROM items;

Vector dimensions are checked. Passing a vector with the wrong dimension should fail instead of silently producing a result.

Null behavior

Test nulls explicitly for every type used by the application:

CREATE TABLE null_demo (
    id INT PRIMARY KEY,
    note TEXT,
    score DOUBLE,
    embedding VECTOR(3)
);

INSERT INTO null_demo VALUES (1, NULL, NULL, NULL);

Null behavior matters for comparisons, joins, vector ranking, and driver decoding. Do not assume a driver maps null values the same way for every type.

Driver type mapping

For each driver, validate:

• text format decoding;
• binary format decoding if the driver uses it;
• parameter binding;
• prepared statement inference;
• null round-trips;
• arrays and JSON if used;
• vector literal formatting.

When a type mismatch occurs, include the driver version and whether the query used simple or extended protocol.