Client Compatibility Baseline

Операторский baseline по совместимости клиентов/ORM. Каноничный источник: этот runbook в angarabook/src/operations/.

Supported Framework Matrix (RM-0.6.5.7)

Framework / Driver	Version	Status	Notes
psql	any	✅ Supported	baseline
psycopg3	3.3.4	✅ Supported	Fixed in v0.6.5.3: EQP cast/arithmetic, date/timestamp encoding, IS NULL, = ANY(ARRAY). Fixed in v0.6.5.5: correct OID mapping and UTC serialization. Fixed in v0.6.5.7: DATE type (OID 1082, binary i32), bool comparison (1=2 → false), FK DDL accept (NOT ENFORCED), multi-col CREATE INDEX accept
Django ORM + psycopg3	5.x	✅ Supported	Basic migrations PASS; EQP gaps fixed in v0.6.5.3. Fixed in v0.6.5.5: set_config/obj_description stubs unblock introspection.
Odoo 19 (community)	19.x	✅ Supported	Fixed in v0.6.5.3: IS NULL, = ANY(ARRAY), pg_class filter, pg_index, CREATE SEQUENCE. Fixed in v0.6.5.5: GAP-C2 (UPDATE SET func), GAP-C5 (date_trunc).
sqlx	0.8.6	✅ Supported	Fixed in v0.6.5.3: ParameterDescription in Describe(S)
tokio-postgres (simple query)	0.7.17	✅ Supported	Simple query protocol
tokio-postgres (extended query)	0.7.17	✅ Supported	Fixed in v0.6.5.3: ParameterDescription in Describe(S). Fixed in v0.6.5.7: binary encode for DATE/TIMESTAMP, binary param decode OID 1114/1184, ParameterDescription returns real OIDs from Parse

Goal

Удерживать repeatable compatibility baseline для:

psql
DBeaver
Odoo-shaped probes

и отслеживать regressions через pinned воспроизводимые проверки.

Phase A focus (Odoo)

Runtime smoke без критических SQL-ошибок.
Stable trace replay без shape/protocol regressions.
Явная граница между допустимыми shape-stubs и недопустимыми semantic-unsafe stubs.

Pinned tooling

tools/pg_catalog_trace/run_odoo_stages_angara.sh
tools/pg_catalog_trace/extract_angara_trace.py
tools/pg_catalog_trace/replay_angara_trace.sh
tools/compat_suite/run.sh --nightly --runs 3
tools/compat_suite/run.sh --odoo --runs 3

High-signal checks

SQLSTATE mapping (42601, 0A000) стабилен.
Catalog/info_schema формы ответов стабильны для probe-набора.
Odoo/DBeaver smoke-путь не ломается от изменений в pg_catalog.

Regression triage

Артефакты compat-suite:

summary.json
iter_<N>/summary.json
iter_<N>/test_<name>.log

Function Compatibility (RM-0.6.5.5)

Для поддержки ORM (Django, Odoo) добавлены следующие функции:

set_config(name, value, is_local): Stub, возвращает value. Позволяет Django настраивать TimeZone и search_path без ошибок.
obj_description(oid, catalog): Stub, возвращает NULL. Позволяет Django выполнять интроспекцию базы данных.
date_trunc(field, timestamp): Полная реализация. Поддерживает все стандартные поля (year, month, day, hour и т.д.).
NOW(), CURRENT_TIMESTAMP: Возвращают текущее время в UTC.

DML Compatibility (RM-0.6.5.5)

UPDATE SET col = func_call(): Теперь поддерживается использование функций (например, write_date = NOW()) и явных приведений типов (col = val::type) в клаузе SET. Это критично для Odoo 19.

Query Execution & Bug Fixes (RM-0.6.5.7)

Bool comparison: Сравнение констант разных типов теперь корректно приводится к boolean. Пример: SELECT 1 = 2; возвращает f (ранее могло вызывать ошибку типов).

Поддерживаемые типы (RM-0.6.5.7)

date: Нативный тип. OID 1082. Binary mode: BE i32 (days since 2000-01-01). Text mode: ISO-8601 (YYYY-MM-DD). current_date поддерживается. Пример: SELECT '2026-05-08'::date;
timestamp: Нативный тип. OID 1114 (без зоны) / 1184 (с зоной). Binary mode: BE i64 (microseconds since 2000-01-01). Поддерживается каст строковых литералов в формате ISO-8601. Пример: SELECT '2026-05-08 12:00:00'::timestamp;

DDL Compatibility (RM-0.6.5.7)

Синтаксис REFERENCES и FOREIGN KEY ... REFERENCES принимается парсером (v0.6.5.7+). Ограничения не применяются (NOT ENFORCED). Сервер логирует [FK constraint] ... accepted as NOT ENFORCED. Пример:

CREATE TABLE orders (
    id INT PRIMARY KEY,
    user_id INT REFERENCES users(id) -- NOT ENFORCED
);

Multi-Column Indexes

CREATE INDEX ON t(a, b, c) принимается (v0.6.5.7+). Индекс строится только по первой колонке. Оставшиеся колонки сохраняются в метаданных. Сервер логирует предупреждение. Пример:

CREATE INDEX idx_multi ON my_table (col1, col2, col3); -- Строится только по col1

Known Limitations (RM-0.6.6.3)

SQL-level PREPARE / EXECUTE / DEALLOCATE

Синтаксис SQL PREPARE stmt AS ... / EXECUTE stmt(...) / DEALLOCATE stmt не поддерживается в AngaraBase v0.6. Вернётся feature_not_supported.

Что использовать вместо: extended query protocol (Parse/Bind/Execute pgwire messages), который автоматически используется всеми поддерживаемыми драйверами:

# psycopg3 — EQP автоматически (prepare=True по умолчанию)
with conn.cursor() as cur:
    cur.execute("SELECT $1::int", (42,))  # → PREPARE + BIND + EXECUTE под капотом

// JDBC
PreparedStatement ps = conn.prepareStatement("SELECT ?::int");
ps.setInt(1, 42);

# psql — использует simple query protocol; PREPARE как SQL НЕ работает.
# Для интерактивного тестирования используй \bind (psql 16+):
psql> SELECT $1::int \bind 42 \g

pg_sleep()

Функция pg_sleep(seconds) не реализована в v0.6. Для тестирования таймаутов используй тяжёлый запрос:

SET statement_timeout = 10;  -- 10 ms
SELECT count(*) FROM large_table a CROSS JOIN large_table b;  -- → ERROR 57014

Protocol Compatibility (RM-0.6.5.7)

Binary encode DATE/TS: Типы date и timestamp кодируются в бинарном формате как BE i32 и BE i64 соответственно.
Binary param decode: Поддерживается декодирование бинарных параметров для OID 1114 (timestamp) и 1184 (timestamptz).
ParameterDescription OID: Сообщение ParameterDescription (фаза Parse) теперь возвращает реальные OID типов параметров вместо нулей.

Быстрый путь:

найти failing test в summary;
открыть соответствующий log;
локально воспроизвести точным cargo test или suite-runner командой.

AngaraBook