Type mapping

How each supported .atl field type maps to PostgreSQL, protobuf, and Go.

Scope

This page covers the types atlantis currently supports. The following PostgreSQL types are not supported yet: oid, hstore, ltree, domains and composites. File an issue if you need one.

Scalars

Notes:

• citext requires the citext Postgres extension. The migration emitted by tide apply does not install it; the operator must CREATE EXTENSION citext once per database.
• numeric is mapped to string on the wire to preserve exact precision. The wire format is the canonical PostgreSQL numeric string (e.g. "123.4500"). Unparameterized numeric (no (p, s)) is not supported.
• jsonb payloads are stored as bytes and not parsed by Atlantis. Validity is checked by Postgres at insert time; an invalid JSON body errors at the storage layer, not at the gRPC boundary.
• uuid uses the canonical RFC 4122 hyphenated lowercase form on the wire. Non-canonical input is rejected by Postgres at parse time.
• bigint over the wire: proto int64. If you serialize a response to JSON yourself, proto-JSON encodes int64 as a string by default to preserve precision.
• varchar(N) length is enforced by Postgres (value too long for type on INSERT); Atlantis does not pre-validate.
• char(N) blank-pads on write: a three-character value stored in a char(10) column reads back with seven trailing spaces. char with no length is CHAR(1), matching Postgres, rather than the unbounded form varchar takes.
• money renders through lc_monetary, so the same row reads back as $1.23 under the C locale and differently under another. The value written is a plain decimal string; the value read carries the locale’s symbol and separators.
• json and xml have no equality operator in PostgreSQL, so neither can be a primary key, a filter, or an ORDER BY column. jsonb has both and is the type to declare for a new column; json exists so an existing column can be described exactly.
• json is stored and returned as bytes and not parsed. Unlike jsonb it preserves key order and whitespace exactly as written.
• name is PostgreSQL’s internal 63-byte identifier type. It appears in catalog-derived tables; text is the type for a new column.
• tsquery normalises on write — a & b reads back as 'a' & 'b'.
• bit and varbit travel as a string of 0 and 1 characters. Bare bit is BIT(1); bare varbit is unbounded.
• tsvector normalises on write — a b reads back as 'a' 'b'.
• varchar without a length accepts strings of any size. It exists so a legacy column declared that way can be described exactly; text is the better choice in a new schema. The two are not interchangeable to Atlantis — they are different Postgres types, so declaring text against a varchar column reports drift rather than agreement.

Time

• timestamp is PostgreSQL’s timestamp without time zone. google.protobuf.Timestamp is anchored to UTC, so a value crossing the wire is read as UTC. Declare timestamptz for a new column; timestamp exists so an existing column can be described exactly.
• time and timetz travel as strings, in PostgreSQL’s own text form: 03:04:05.000000 and 03:04:05+00. proto has no wall-clock-time well-known type to carry them.
• date carries 00:00:00 UTC as the time-of-day. A caller sending a non-zero time-of-day has the time fraction truncated to midnight on insert.
• interval round-trips exactly, including months and years. PostgreSQL stores months, days and microseconds as three separate components, and atlantis.common.v1.Interval carries the same three unchanged. No conversion happens at the wire boundary, because none is possible there: 1 month is 28 to 31 days depending on the month it is added to, and 1 day is 23, 24 or 25 hours across a daylight-saving boundary. A caller that wants a single duration has the date to compute it against; this layer does not.

Network

• All four travel as PostgreSQL’s own text form.
• inet normalises on write: 10.0.0.1 reads back as 10.0.0.1/32, because PostgreSQL stores the netmask alongside the address.

Vectors

• Requires the pgvector extension. The operator must CREATE EXTENSION vector once per database.
• N is the dimension. pgvector caps vector at 16,000 dimensions; the lexer does not enforce this but Postgres rejects creation past the cap.
• A wire payload whose length doesn’t match the declared N errors at request time.
• halfvec, sparsevec, and pgvector’s bit type are not supported yet.

Enums

An enum is declared at the top level and used as a field type:

enum Mood in app { happy, sad, "in progress" }

entity Person in app {
  id   bigint primary
  mood Mood not null
}

• The column carries the label, as a string. PostgreSQL enforces the set: a label the type does not list is refused at write time with invalid input value for enum.
• A label is an identifier, or a quoted string when it is not — "in progress" is a legal PostgreSQL label and has no bare spelling.
• Labels are ordered as declared, which is the order PostgreSQL sorts them in. Reordering an existing type is not something PostgreSQL can do, so a reordering in the .atl is not reported as a change.
• Enum columns are filterable and orderable. Ordering follows label order, not alphabetical order.
• Adding a label is additive. Removing one is refused. PostgreSQL has no ALTER TYPE ... DROP VALUE; removing a label needs a new type, a rewrite of every column using it, and a drop of the old one. tide plan says so rather than emitting DDL that cannot run.
• A label added by a migration cannot be used by that same migration — PostgreSQL refuses it as unsafe use of new value until the transaction commits. Adding a label and defaulting a column to it in one change is refused with that reason. A type created and defaulted to in the same migration is fine; PostgreSQL exempts that case.
• Arrays of enums are not supported, for the same reason as the text-carried types above.
• The type lives in the atlantis schema whatever table override the entities using it carry, because it is atlantis’s to create and drop.

Ranges

• Each travels as PostgreSQL’s own text form, bounds included: [1,5) is inclusive of 1 and exclusive of 5.
• PostgreSQL normalises on write. A tsrange written as [2024-01-01,2024-02-01) reads back as ["2024-01-01 00:00:00","2024-02-01 00:00:00").
• Multirange types (int4multirange and the rest) are not supported yet.

Geometric

• Each travels as PostgreSQL’s own text form: (1,2) for a point, <(0,0),1> for a circle.
• None is filterable or orderable. PostgreSQL sorts none of the seven and defines = on only five, so a filter, primary key or ORDER BY on one could not be executed.
• box normalises its corners on write: ((0,0),(1,1)) reads back as (1,1),(0,0).
• These are storage only. PostGIS geometry and geography are different types and are not supported.

Arrays

• Only one-dimensional arrays. [][]T is rejected at parse time.
• Element type T is any scalar above except vector and the types atlantis carries as text: inet, cidr, bit, varbit, tsvector, the range types and the geometric types. tide plan refuses an array of one of those. pgx decodes an array with its element’s codec, so inet[] would read back as the binary array body reinterpreted as characters — a wrong answer rather than an error. Declare text[] and cast in a custom query.
• A null array (nil slice in Go, missing field on the wire) is distinguishable from an empty array ([]T{} in Go, present-but-empty on the wire); both round-trip.

Filtering

Every type above is filterable through Query<Entity> except json, xml, the seven geometric types, vector, interval, and arrays ([]T). A column of one of those types can still be selected and written; it just has no predicate field on the generated <Entity>Filter message.

They are absent for two different reasons. json, xml and the geometric types have no equality or ordering operators in PostgreSQL, so a filter on one could not be executed. vector, interval and arrays have the operators and no predicate message.

Ordering is separate: every scalar type is orderable except json, xml, the geometric types, vector and arrays.

Two notes on floats. Comparisons run at the column’s own width, so a real column is compared as float4 rather than being widened — which is what makes eq on a real column match the literal you wrote. And eq on a float is still float equality: a value that was computed rather than stored from the same literal may not compare equal at either width.

Nullability

Fields are non-nullable by default; declaring not null is redundant for primary (which implies it). A field declared without not null is nullable. The proto field gets the optional keyword and the Go field becomes a pointer:

For bytes, Timestamp, Duration, vector, and arrays, the Go type is already nilable; the same value represents both null and (for bytes/vector/[]T) empty. Round-trip preserves the distinction over gRPC because proto3 transmits the field-presence bit separately from the length.

A nullable field with default <expr> is treated as nullable by the proto request (proto sees optional), but a NULL in the request leaves the column null — the default fires only when the request omits the field entirely.

Default-bearing fields

Fields declared with default <expr> become optional in the proto request even when not null:

entity Note in app {
  ...
  created_at timestamptz not null default now()
}

The proto request has optional Timestamp created_at. If the caller leaves it unset, Postgres applies now() on insert. If the caller sends a value, that value is used.

serial columns

A field declared bigint primary serial (or int primary serial) becomes optional in the proto request: the server lets Postgres assign the value from the sequence when the caller omits it. The on-the-wire type is still int64 / int32; only the field-presence semantics differ.

Related

• DSL grammar — the full type grammar and where types appear inside entity, query, and procedure declarations.