Changelog¶
All notable changes to TypeBridge will be documented in this file.
[2.3.3] - 2026-10-27¶
Fixed¶
- The C runtime's
type_bridge_database_server_versionreports the version of the connected TypeDB server. Since 2.3.1 it reported the newest version admitted by the profile, so a connection to 3.13.6 said 3.14.0. - TypeDB versions at or above 3.11.0 are now admitted without an upper version ceiling. Measured, supported lines remain 3.11โ3.14. A connection to a newer line reuses the newest measured semantic profile and protocol assumptions and warns that it is "not tested or supported by this TypeBridge release". Admission does not guarantee compatibility; versions below 3.11.0 remain refused (#286).
- Generated SDK packages, the C runtime, and connected migrations admit
3.12.3+on the 3.12 line for profiletypedb-3.12.1/v1, and3.13.6+,3.14.0+, and newer lines fortypedb-3.13.6/v1. Older profiles retain their line and patch-floor constraints. Measured test pins are unchanged.
[2.3.2] - 2026-10-23¶
Added¶
type_bridge_server::transport::v3::StagedExecutor: the staged V3 executor as a library entry for hosts that embed the server crate, the V3 counterpart ofpreflight_remote_request_v2/execute_admitted_remote_request_v2.execute_staged_requesttakes an admitted caller and the signed request bytes and returns aStagedOutcome(signed reply bytes, code, committed / failed / unknown);/v3/stagedis that call behind HTTP framing. The hook order is documented on the V3 interceptor hooks and pinned by a test.
Changed¶
- TypeDB 3.14's query rules are refused at plan build on every profile and
in every language (#268): a sort on a duration (
query_plan_sort_unordered_value, V2query_plan_v2_sort_unordered_value) and a range comparison of durations (query_plan_duration_range, V2query_plan_v2_duration_range). On 3.12 and 3.13 these plans ran or crashed the server; on 3.14 they failed at the server.like/containson non-strings were already refused (query_plan_v2_string_operator_type).
[2.3.1] - 2026-10-23¶
2.3.1 adds TypeDB 3.14 to the supported matrix (#268). Applications and
generated packages need no change. TypeDB 3.14's stricter query rules
(no sort on unordered value types, no range comparison of durations, no
like/contains on non-strings) are not yet refused by the plan builder;
such plans fail at the server on 3.14 and follow in a later patch.
Added¶
- TypeDB 3.14 is supported: the window is 3.11โ3.14, and 3.14.0 is the
recommended server and the default
test.shlane. A 3.14 server speaks band 9 natively and also accepts band 8, so version discovery is unchanged. - TypeDB 3.14 shares semantic profile
typedb-3.13.6/v1: it changed no schema syntax, default or lowering. Generated packages and connected migrations on that profile run on TypeDB 3.13.6 or 3.14.0, and profile names, generated files and migration histories stay as they are.
Changed¶
- Band 9 runs the official
typedb-driver3.14.0 (protocol 3.14.0), which serves TypeDB 3.12, 3.13 and 3.14. Band 8 keeps the namespaced 3.11.5 driver. - TypeBridge depends on
typeql =3.14.0andchrono =0.4.45.typeqlpins its ownchronoandregexexactly, so an application that links the TypeDB 3.14 server crates could not resolve beside TypeBridge 2.3.0 (typeql =3.13.4). The driver pin check now also requirestypeqlon the support window's newest line. - The Python
typedb-driverextra accepts>=3.11,<3.15(>=3.12.3,<3.15on CPython 3.14).
Fixed¶
- Fetched integers beyond 2^53 stay exact on every supported server; a live test now checks it. TypeBridge reads typed concept values, not the driver's JSON rendering, which rounds them in drivers before 3.14.
[2.3.0] - 2026-10-22¶
2.3.0 runs every query, direct or through a proxy, on one Rust pipeline, and
adds staged transactions over typed query-plan/v3 programs in every SDK
(#253). See the "Upgrading to 2.3" guide for the steps from 2.2.
Breaking changes¶
2.3.0 removes the duplicate query paths that let one query behave differently direct and through a proxy. Each entry says what to do instead.
- Generated packages need their embedded schema authority. A package
installed without one is refused with
schema_authority_required. Every generator has embedded it since 2.1.0; regenerate older packages. - Direct queries now apply the same query limits as remote ones, because
every match request, direct or remote, from a generated package or a
dynamic registry, runs on one executor: a predicate nested past
canonical_depthis refused withcanonical_json_too_deepinstead of running, and a dynamic descriptor registry no longer falls back to the old executor when a request does not fit. Raise the session'sQueryLimitsto run such a query. QueryExecutionResourceLimitsconstructors in Python, TypeScript/Node, and C no longer clamp a value above the default: they keep it, and refuse a timeout past one day or more than 3 statements. Pass the values you mean.- Renamed Rust constants:
MAX_QUERY_ITEMS,MAX_QUERY_BYTES,MAX_QUERY_GRAPH_NODES,MAX_QUERY_ATTRIBUTE_VALUES,MAX_QUERY_COLLECTION_MEMBERS, andMAX_QUERY_ROLE_PLAYERSareDEFAULT_PROXY_QUERY_*, with the same values, beside the new, largerDEFAULT_DIRECT_QUERY_*; they are defaults, no longer ceilings. TheMAX_QUERY_*names remain as deprecated aliases (see Deprecated).DEFAULT_DIRECT_QUERY_TIMEOUT_MILLISECONDS,DEFAULT_PROXY_QUERY_TIMEOUT_MILLISECONDS,DEFAULT_DIRECT_QUERY_STATEMENTS, andDEFAULT_PROXY_QUERY_STATEMENTSare the defaults of the two dimensions that keep a maximum (MAX_QUERY_TIMEOUT_MILLISECONDS,MAX_QUERY_STATEMENTS). ProjectedQueryMaterializationLimits::tightenedis replaced bynew, and theMAX_PROJECTED_QUERY_*constants are removed; materialization takes its bounds from the answer policy.- Changed refusal codes:
- remote model-query preparation reports the limit that refused
adaptation, such as
canonical_json_too_deepwithmaximum_depthorquery_v2_adapter_literal_byte_limitwithactual_bytesandmaximum_bytes, instead ofquery_remote_v2_model_artifact_limit; - a generated manager filter with more than 256 predicates is refused
with
structural_limit_exceededinstead ofmanager_filter_predicate_limit; - replies to authored low-level plans (
query_v2_prepare_remote,queryV2PrepareRemote) are refused withquery_remote_v2_*codes, and a missing executor capability withunsupported_required_capability. - The V1 remote envelope is removed (
typebridge.query-remote-request/v1,-response/v1,-failure/v1). Authored low-level plans now travel in thetypebridge.query-remote-request/v2envelope that model queries already used; their binding API keeps its shape, and a failure carries the complete structured diagnostic. The capability advertisement and the signed outer reply are unchanged. Removed Rust API, with the*_v2item to use instead where one exists: - contract:
RemoteQueryRequest,RemoteQueryResponse,RemoteQueryFailure,RemoteLimits,RemoteReplyDecodeLimits,RemoteOutcome,RemoteReply,RemoteRequestFingerprint,decode_remote_reply,decode_signed_remote_failure, and the constantsQUERY_REMOTE_REQUEST_FORMAT_V1,QUERY_REMOTE_RESPONSE_FORMAT_V1,QUERY_REMOTE_FAILURE_FORMAT_V1andQUERY_REMOTE_REQUEST_CANONICALIZATION.RemoteOutcomeShapehas no replacement. - orm:
prepare_remote_query,preflight_remote_request,preflight_remote_request_at,execute_admitted_remote_request,encode_remote_request,encode_remote_request_at,check_advertised_capabilities,decode_remote_outcome,AdmittedRemoteRequest,RemoteRejection,PendingRemoteQueryandClaimedRemoteReply. - orm, the V1-or-V2 dispatch:
AdmittedRemoteRequestEnvelope,RemoteRejectionEnvelope,preflight_remote_request_versionedandexecute_admitted_remote_request_versionedbecomeAdmittedRemoteRequestV2,RemoteRejectionV2,preflight_remote_request_v2andexecute_admitted_remote_request_v2;RemoteRequestFormatandremote_request_formatare removed, since only V2 is accepted. - orm
RemoteReplyExpectationis a struct instead of an enum with one variant per envelope version. - Rust connections:
SchemaPackage::connect(policy)takes aDirectConnectionPolicyor aProxyConnectionPolicyand returnsConnection<S>(Direct(Database<S>)orProxy(ProxyDatabase<S>)) instead ofDatabase<S>; matchConnection::Directfor CRUD managers. Renamed:RemoteDatabasetoProxyDatabase,RemoteQueryTransporttoProxyExchange,RemoteConnectionOptionstoProxyConnectionPolicy(generated(limits, transport)iswith_exchange(transport).answer_limits(limits);new(scope, profile, limits, transport)adds.authority(scope, profile)), andDirectTlstoTlsPolicy; passQueryExecutionResourceLimitswhere 2.2 tookRemoteQueryLimits. The 2.2 names remain as deprecated aliases (see Deprecated), so 2.2RemoteDatabasecode compiles. What breaks is theConnection<S>return ofconnectand ofconnect_with_cancellation; both takeimpl Into<ConnectionPolicy>, andconnect_with_cancellationno longer needs thetypedbfeature. - Two exhaustive enums gain a
Completevariant for the newcompleterow cardinality: ormmatch_request::RowCardinalityand contractquery_plan::QueryRowCardinalityV2. Add an arm to amatchover them. - The server's
config::V2Sectiongains the public fieldsquery_limits,answer_limitsandallow_unauthenticated_staged_writes. A struct literal needs them or..Default::default(); TOML configuration is unaffected. - Generated Python packages have one async session.
QuerySession,Query, andGroupedQueryrun on every connection, and every terminal (one,first,rows,page_by,count_by,exists_by,aggregate, groupedaggregate) is a coroutine, direct included; composition stays synchronous.QuerySession(connection, *, resources, cancellation, query_limits)takes the connection first and no projection, andModel.query(connection, ...)accepts the same options. Removed:QuerySession.remote_factoryand the nativePyRuntimeProjection.match_session()(usematch_session_with_resources); the 2.2 remote names remain as deprecated aliases (see Deprecated). To migrate: awaiteach terminal; a script without an event loop wraps the session intype_bridge_core.blocking(session), which runs each terminal to completion on a private thread.RemoteQuerySession(advertisement, exchange, limits)becomesQuerySession(ExchangeConnection(advertisement, exchange), resources=limits), orQuerySession(connect_proxy(url))for the built-in HTTP route.RemoteQueryLimits(max_items=..., ...)becomesQueryExecutionResourceLimits(items=..., ...); its defaults are the statement count and deadline the flat limits used.- The handwritten Python typed-query facade
type_bridge.typedis removed:QuerySession,Query,RemoteQuerySession,RemoteQuery,RemoteQueryExchange,RemoteQueryLimits,Page,BoundVar,BoundField,BoundRole,Collected,Predicate,QueryOrder,Selection,FieldRef,RoleRef,TypedQueryCapabilityError,TypedQueryConnectionError,TypedQueryMaterializationError, andTypedQueryWindowError. The generated packages' 2.2 remote names stay as deprecated aliases (see Deprecated). Use the generated package's ownQuerySession,Query, and tokens (from your_generated_package import Query, QuerySession); every terminal is awaited, and a script without an event loop wraps the session intype_bridge_core.blocking(session). Generated model stubs import their static descriptor protocols fromtype_bridge.fields._generated_descriptors; a package generated earlier still runs, but a type checker reports the missing module until it is regenerated. Removed with it, fromtype_bridge_core: the flat-limitquery_v2_remote_model_context(usequery_v2_remote_model_context_with_resources),revalidate_match_diagnostic, andvalidate_match_order_term_count. - Rust:
ast::FetchItemgainsRaw(String)for raw fetch entries; an exhaustivematchon it needs that arm. - Generated TypeScript packages have one session.
QuerySession,Query, andGroupedQueryrun on every connection, and every terminal (one,first,rows,pageBy,countBy,existsBy,aggregate, groupedaggregate) returns aPromise, direct included; composition stays synchronous, and direct terminals no longer block the event loop.new QuerySession(connection, { resources, cancellation, queryLimits })takes aRustDatabase, a transaction, aProxyConnection, or anExchangeConnection; the 2.2 remote names remain as deprecated aliases (see Deprecated). Removed from@type-bridge/node/runtime-projection:RuntimeProjectionRemoteLimits, the sevenInstalledRuntimeProjection.execute*methods (usedirect(connection)), and the nativesmatchSession()without resources and the flat-limitqueryV2RemoteModelContext(usematchSessionWithResourcesandqueryV2RemoteModelContextWithResources). To migrate: awaiteach terminal.new RemoteQuerySession(advertisement, exchange, limits)becomesnew QuerySession(new ExchangeConnection(advertisement, exchange), { resources }), ornew QuerySession(await connectProxy(url))for the built-in HTTP route. Flat limits{ maxItems, maxBytes, ..., deadlineMs }becomenew QueryExecutionResourceLimits({ items, bytes, ..., timeoutMilliseconds }).- Generated Python and TypeScript packages no longer check query windows,
selection and aggregate caps, group-by keys, or reachability depth
themselves; the Rust core refuses them with its structured diagnostic
(in Python
InvalidQueryRequestError, still aValueError; in TypeScript the structured error withcategoryandcode), the same on every connection. TypeScript callers catch the core codes instead of the old host errors: - a zero limit is
zero_window_limitand an offset plus limit past the unsigned 64-bit range iswindow_overflow(TypeScript acceptedlimit: 0nand now refuses it); - more selections than
selected_slotsisselection_cap_exceeded, no or too many aggregate terms areempty_reducers/reducer_cap_exceeded, and too many group-by fields arefield_group_tuple_cap_exceeded, still raised bygroup_by()/groupBy()(TypeScript raisedRangeError); - a reachability minimum depth above its maximum is
reachable_bounds, and a maximum above the predicate-depth ceiling (64) isreachable_depth_limit.
The caps follow the session's QueryLimits: a session that lowers
selected_slots is refused at its own limit, where the hosts used to
apply a fixed sixteen. Marshalling stays a host error with the 2.2
classes in Python: a malformed window (a bool, a non-int, or a value
outside the unsigned 64-bit range) raises ValueError, and a depth that
is not an int raises TypeError or outside 0 to 255 ValueError; in
Node a window that is not a u64 bigint or a depth that is not an
integer from 0 to 255 is a native argument error (it was a RangeError).
These are the same on every connection: a caller-exchanged session no
longer reports a malformed window as query_remote_limit_invalid.
C query descriptors get the same codes instead of
c_query_descriptor_layout_invalid for a zero limit, no selected slots
(empty_output) or reducers, a slot, order, group-field, or reducer table
above the core's ceiling, and an invalid output name
(invalid_output_name); a terminal now accepts up to 64 order terms, the
core's limit, instead of 16.
- Every enum the native modules accept as text (comparison operator, sort
direction, missing-key order, row cardinality, reducer, transaction type,
value type, record kind, manager lookup and comparison, owner lookup,
match mode, given-row column type) is parsed by the Rust core. An unknown spelling is one structured diagnostic
in every language: category invalid_input, code unknown_enum_value,
details kind, accepted, and value (the rejected text, left out when
it is not a bounded identifier). Python raises the new
type_bridge_core.UnknownEnumValueError, a subclass of both
MatchRequestError and ValueError, so except ValueError still
catches it; TypeScript raises the structured error with that code
instead of a plain native argument error. The old message texts are gone.
As in 2.2, transaction types are trimmed and ASCII case-folded (" READ "
opens a read transaction), and Node compareValueJson /
functionValueJson accept the TypeQL spelling datetime-tz as an alias
of the scalar domain datetime_tz. Accepted spellings changed:
- row cardinality also accepts complete, which the core validates;
- TypeScript QuerySession.var(model, mode) refuses a mode other than
exact or subtypes with the structured error (was TypeError); the
native match session's new binding(typeName, matchMode) parses it;
- Python execute_with_rows column types are boolean, integer (alias
long), double, string, date, datetime, and datetime-tz; any
other raises UnknownEnumValueError before a row is read (was a
ValueError naming the row);
- the manager lookup aliases exact (for eq) and like (for regex)
and the owner lookup alias exact remain, now defined by the core.
The low-level query-v2 builders (Python and Node) report an unknown
value type, type kind, comparator, order direction, or reducer the same
way, with code unknown_enum_value and the same details; the category
stays invalid_contract, like every builder refusal. The codes
query_builder_value_type_unknown, query_builder_type_kind_unknown,
query_builder_comparator_unknown, query_builder_order_direction_unknown,
and query_builder_reducer_unknown are gone.
Rust: ValueType::parse (returned Option) is replaced by
str::parse::<ValueType>(); the core enums gain FromStr, ACCEPTED,
KIND, and spelling(), and ValueType / ValueTypeTag convert with
From.
- A structured SDK diagnostic reaches Python and Node in one JSON form,
defined by the Rust core (SdkExecutionDiagnostic::host_json): version,
category, sdk_category, query_category, code, message, path,
details. In the JSON form count, byte_count, and signed detail
values are decimal strings, because a u64/i64 does not fit a
JavaScript number; path positions (index, output_slot, binding,
role_edge) stay numbers.
- Python: MatchRequestError (and UnknownEnumValueError) keep their
classes and attribute names, and count, byte_count, and signed
detail values stay int, as in 2.2. The exception gains a version
attribute.
- Node: the native error message of a structured diagnostic uses the keys
sdk_category and query_category (was sdkCategory,
queryCategory) and adds version. QueryV2Error properties are
unchanged. TypeScript no longer re-validates the native JSON field by
field; it takes the core's form as given (internal failures still stay
plain errors).
- Rust and C are unchanged: the C ABI keeps its typed accessors, and its
contract diagnostic JSON is the same serde form Python and Node give a
QueryV2Error.
The cases in tests/contracts/diagnostic-json.json are checked to be
identical in Rust, Python, Node, and C (for the cases C can produce).
- Generated Python and TypeScript packages no longer check a model member's
cardinality themselves; the Rust core checks it at the same call (Python
field assignment and construction, TypeScript create and
decodeCreate) with the rule and codes encoding uses: no value for a
required member is missing_required_field / missing_required_role,
any other count outside the cardinality is field_cardinality_violation
/ role_cardinality_violation, with actual_count, minimum_count, and
maximum_count details.
- Python raises the new type_bridge_core.ProjectedCardinalityError, a
subclass of both MatchRequestError and ValueError, so
except ValueError still catches it; the old message texts are gone.
- TypeScript raises the structured error with that code instead of a
RangeError. Hydrated values are no longer re-checked in TypeScript;
the core checked them when it hydrated them.
- A provider row whose member count is outside the projected cardinality
is refused by the core with the same codes in category integrity
(Python MatchRequestError, Node the structured error) instead of a
RuntimeError reading "provider row violates projected cardinality".
- A generated manager write (insert, put, update, and their batch forms)
whose model holds a member count outside the cardinality, such as a
hand-built Node wire, is refused by the core with the same codes in
category invalid_input (Python ProjectedCardinalityError, Node the
structured error) instead of a ValueError reading "projected value
violates resolved cardinality" or a Node error reading "projected member
violates resolved cardinality".
- Mixed versions: clients and executors must both be 2.3.
- A 2.3 executor refuses a V1-format request with
query_remote_v2_format_unsupported and a supported detail naming the
accepted format.
- A 2.3 client prepares authored plans only for an executor that
advertises query.plan.v2, query.remote.envelope-v2, and
query.remote.structured-diagnostic.
- A client older than 2.3 cannot decode the advertisement of an executor
configured with non-default query or answer limits.
Added¶
- TypeDB 3.13 servers are supported for queries and CRUD. The support window
is 3.11.0โ3.13.x; 3.13 servers negotiate the band-9 driver and use the
semantic profile
typedb-3.13.6/v1. Generated packages on that profile connect to exactly TypeDB 3.13.6. TypeDB 3.14 and newer are refused. A connection whose band-8 discovery probe finds a 3.13 server reconnects on band 9 instead of refusing it. - Connected migrations (
migration apply,verify,adopt, androllback) run on TypeDB 3.13.6 with the workspace profiletypedb-3.13.6/v1. Each profile runs on exactly one server:typedb-3.12.1/v1on 3.12.3 andtypedb-3.13.6/v1on 3.13.6; any other pair is refused withmigration_typedb_server_version_unsupported, which names the server the profile expects, and any other profile withmigration_typedb_semantic_profile_unsupportedbefore credentials or the filesystem are touched. An existing 3.12 history moves to the new profile withmigration upgrade-profile --to typedb-3.13.6/v1(below).require_supported_migration_server_for_profile,require_supported_migration_profile, andmigration_server_for_profileintype_bridge_schema_migration_typedbexpose the pairing. type-bridge migration upgrade-profile --environment <env> --to typedb-3.13.6/v1moves a migration history to a newer TypeDB line. After the databases are moved to the new server andcompatibility.semantic-profilenames the new profile, it writes one zero-operation profile bridge manifest and records it in that environment's ledger. It requires the ledger at the history head and the live schema unchanged (migration_upgrade_profile_live_drift), is idempotent, and cannot be rolled back (migration_rollback_profile_bridge).migration make,plan,apply, andverifyon a history still on the older profile refuse withmigration_history_profile_upgrade_requiredand print the command to run. A bridged history also replays into a new, empty database on the newer server:migration applyapplies the older migrations under their own profile, the bridge as a profile flip, then the newer ones, all verified. Older-profile migrations are refused anywhere else.typebridge.query-plan/v3, an open canonical plan format for one typed TypeQL pipeline: an optional match with comparisons andletvalues (typed arithmetic and builtin expressions, checked against TypeDB numeric rules), boundedgiveninput rows,insert,put,updateanddeletewrite stages, and a read (Rows,Count,Exists) or write operation. A plan is validated against schema authority (write targets, concrete types, ownerships, roles, key immutability, binding lifetimes). Rust owns the canonical bytes and every SDK calls it, so one program has the same bytes in every language; released V2 read plans lift into V3 without changing their representation. The format, its capabilities and the staged envelope are specified in the Query-plan V3 reference.query-plan/v3match stages accept aniidpattern that identifies an already typed entity or relation binding by its canonical IID (query.pattern.iid).query-plan/v3gains a terminalfetchstage that answers a thing's hydration document (IID, exact type, owned attributes, and the players of listed roles) in the same pipeline (query.fetch.thing, not yet advertised by proxies).query-plan/v3gains anattachwrite stage that adds an ownership value or a role player to an already bound thing, keeping the existing ones (query.write.attach, not yet advertised by proxies).- Conditional writes in one transaction. A
query-plan/v3write plan puts its checks (wherecomparisons,letvalues) and its writes in one TypeQL pipeline, and a staged transaction commits all its staged plans atomically: a failing plan stores nothing, and a lost race is a typed conflict failure (PythonCommitConflict) to rerun whenretry_safeis true. A condition that matches nothing is not an error: the commit succeeds and the plan answersMatched(0), so check the answer. See Concurrency and conditional writes for the purchase example in every SDK, and Checkout: a whole cart in one query for a cart whose stock checks, total, balance check and writes are one plan (#253). query-plan/v3delete stages gainDeleteItem::Players { relation, role }, which removes every player of a role, so a relation update can clear a role and attach its new players in one plan.DeleteItem,AttachItemandStagearenon_exhaustive.- Rust staged transactions run
query-plan/v3programs and typed reads.Transaction::stage_planlowers a plan to one provider query when it is staged and resolves to aPlanAnswer(Rows,Count,ExistsorMatched) only after the commit succeeds; plan inputs need the TypeDB 3.12+givenstage.Transaction::stage_matchstages a validated typed read, including in aWritetransaction, where it sees the writes staged before it. Staged reads honour the transaction's answer limits, deadline and cancellation. ASchematransaction refuses both withborrowed_target_not_read_only. - The Rust SDK builds typed
query-plan/v3programs and stages them.type_bridge::plan::Plan::builder()declares things (exact,subtypes), field values (field), inputs and input rows (input,row), comparisons (where_), role links (links) andletvalues from generated model, field and role tokens, thenupdate,insert,putanddeletewrites;build(&SCHEMA)validates it against the generated package.Database::transaction(TransactionOptions)returnstype_bridge::staged::Transactionwithstage,commit,rollbackandclose; nothing opens beforecommit.ProxyDatabase::transactionreturns the same type, and commit and pending-answer errors convert intotype_bridge::Error. The rules that number handles, order terms and name variables live in the contract'squery_plan::v3::PlanBuilder, so a program has one canonical encoding. - Python builds the same plans with
type_bridge.plan.Plan.builder()(where_,let_, and otherwise the Rust names in snake_case) from generated model, field and role tokens;build(schema_authority())validates it, and generated Python packages exportschema_authority().Database.staged_transaction(kind=None, *, commit_on_exit=True)andRustDatabase.staged_transactionopen a direct staged transaction beside the releasedtransaction(); it andProxyConnection.transactionstage built plans and answer typedRows,Count,ExistsorMatchedvalues fromPending.result(). - TypeScript builds the same plans with
Plan.builder()from@type-bridge/node(exact,subtypes,field,input,optionalInput,where,links,let,update,updatePlayer,insert,put,delete,deleteField,deletePlayer,row,returning,count,exists, thenbuild(authority)) from generated model, field and role tokens; a token of another model is a type error.RustDatabase.stagedTransaction(kind)opens a direct staged transaction withstage(plan),commit,rollback,close, and an async dispose that closes without committing (await using). Generated packages exportschemaAuthority().RustDatabase.transaction(kind)keeps its released eager context. - C ABI 1.7, a strict superset of 1.6: every 1.6 symbol keeps its behaviour. It adds:
- staged transactions over
query-plan/v3plans:type_bridge_plan_v3_decode(canonical plan bytes under declared schema bytes),type_bridge_database_transaction,type_bridge_proxy_connection_transaction,type_bridge_staged_transaction_{stage,commit,rollback,close}andtype_bridge_pending_answer. As in the other SDKs, the handle is a reusable logical transaction: commit and rollback take it by pointer and keep it usable, andcloseis the only release; - the plan builder (
type_bridge_plan_builder_*), which forwards to the core builder, so a C program has the same plan bytes as any other SDK; type_bridge_execution_diagnostics_failure_get_v1, which reads a typed failure (outcome, phase, reason, lock kind, annotation,retry_safe, stagedop_index, provider code) intotype_bridge_execution_failure_v1_t;type_bridge_write_transaction_rollback_keep;- the
TYPE_BRIDGE_DEPRECATED(msg)header macro, not yet applied.
Schema package descriptors of ABI 1.6 and 1.7 are both accepted. The
installed CMake package reports ABI 1.7.0 and accepts 1.6 and 1.7
requests, EXACT included, so find_package(TypeBridge 1.6.0 EXACT)
keeps resolving and find_package(TypeBridge 1.7) requires the new
minor. pkg-config keeps Version: 1.6.0 for exact pins and provides
type-bridge-abi = 1.7.0 (Requires: type-bridge-abi >= 1.7.0).
- Staged transactions cross the proxy. ProxyDatabase::transaction
(Rust), ProxyConnection.transaction(kind) (Python and TypeScript) and
type_bridge_proxy_connection_transaction (C) return the same staged
transaction: commit sends every staged plan in one
typebridge.query-remote-request/v3 envelope to POST /v3/staged,
verifies the signed reply, and resolves the answers and typed failures
direct execution gives. The server keeps no replies: a lost or
unverifiable reply is commit_outcome_unknown, as a lost direct commit
is, and the application reads the database to learn whether it applied.
The server runs each request at most once; resent bytes are refused, as
commit_outcome_unknown for a write. Only plans stage over the proxy; raw TypeQL and stage_match are refused
with staged_proxy_unsupported.
- The TypeBridge server runs staged query-plan/v3 transactions at
POST /v3/staged and advertises them at GET /v3/capabilities. Every
configured interceptor must declare supports_v3, or each V3 request is
refused with query_remote_policy_rejected. A write transaction needs an
interceptor to vouch for the caller through on_v3_write_authority,
unless [v2] allow_unauthenticated_staged_writes = true (default
false); otherwise it is refused with staged_write_not_authorized.
- Server interceptors can authorize each staged plan with on_v3_plan,
which sees a redacted V3PolicyPlan (capabilities, touched types,
operation, writes; input rows only when wants_v3_plan_rows opts in) and
refuses the whole request before anything is reserved or opened, and can
observe each staged transaction's outcome with on_v3_commit
(V3CommitOutcome: committed, code, commit certainty, typed failure).
Both default to no-ops.
- Typed provider failures. Every query and commit failure is classified
once, from TypeDB's error code and fixed message text, into a value-free
Failure: Rejected (definitely not stored, with phase query or
commit, a reason, and the staged op_index) or Indeterminate (the
commit may have applied). Reasons are a conflict with its lock kind
(exclusive, require_deleted_key, deleting_required_key,
unknown), cardinality, uniqueness, a constraint with its annotation, or
another code. retry_safe says whether rerunning the whole transaction
on a fresh snapshot is safe; an indeterminate commit must be reconciled
first. The winner of a conflict is not reported: TypeDB does not expose
it.
- Rust: error.failure() on type_bridge::Error and the ORM, runtime
and server errors, in the type_bridge::failure vocabulary.
- Python: an immutable error.failure (phase, reason, lock_kind,
annotation, op_index, retry_safe, code). Commit errors raise
type_bridge.CommitRejected, its subclass CommitConflict, or
CommitOutcomeUnknown, all RuntimeError subclasses, from released
and staged commits alike; staged pending answers that observe the
commit outcome raise the same class, while staged query-phase failures
keep MatchRequestError.
- TypeScript: readonly failure on QueryV2Error.
- C: ABI 1.6 keeps its statuses (TYPE_BRIDGE_STATUS_EXECUTION_FAILED,
TYPE_BRIDGE_STATUS_COMMIT_OUTCOME_UNKNOWN), now chosen from the
typed outcome, and its released detail set; ABI 1.7 reads the failure
through its accessor.
- Server: HTTP error.details carry the failure.
Diagnostics keep their released codes and add the details retry_safe,
code, rejection, lock_kind and annotation.
- One connection, direct or proxy, chosen by configuration, in every
language; the same query program runs on either and returns the same
results and refusals. A proxy connection uses a built-in HTTP route to a
TypeBridge server's /v2/capabilities and /v2/query over plaintext or
TLS (native roots or a custom root bundle), with optional request headers
such as Authorization and an optionally pinned advertisement; it follows
no redirects and ignores proxy environment variables. Every proxy
connection takes an answer-limit ceiling.
- Rust: SchemaPackage::connect(policy) with
ProxyConnectionPolicy::new(ProxyEndpoint::new(url)) (TlsPolicy), or
ProxyConnectionPolicy::with_exchange for a host-owned ProxyExchange.
- Python: connect_proxy(endpoint, ...), or
ExchangeConnection(advertisement, exchange, *, answer_limits=None) for a
host-owned exchange; pass either to QuerySession or Model.query. The
native ProxyConnection behind it has execute_*_proxy terminals.
- TypeScript: connectProxy(endpoint, options) resolves to a
ProxyConnection, and new ExchangeConnection(advertisement, exchange,
{ answerLimits }) is the host-owned exchange; pass either to
QuerySession.
- C: type_bridge_proxy_connection_open_v1 opens a synchronous connection
from type_bridge_proxy_connection_options_v1_t (endpoint, TLS mode and
custom root, headers, pinned advertisement, connection and answer
limits), and type_bridge_proxy_query_execute_v1 runs a terminal on it
with the same arguments and result family as
type_bridge_database_query_execute_v1. Generated C packages emit
{prefix}_proxy_query_execute_{kind}. The remote context stays as the
exchange extension point for hosts that own the route. These entry
points and types are new in ABI 1.7; the 2.2.6 (ABI 1.6) header does
not declare them. Generated packages that call them carry an ABI 1.7
descriptor, and their CMake and pkg-config files require ABI 1.7
(find_package(TypeBridge 1.7.0 EXACT), type-bridge-abi >= 1.7.0),
so a 2.2.6 runtime is refused at build time.
- Configurable query limits. QueryLimits replaces the fixed ceilings on a
query's encoded size, nesting depth, and structure, and a session can lower
or raise them, including plans larger than 16 MiB. Python, TypeScript/Node,
and Rust sessions accept it (query_limits, queryLimits,
with_query_limits); C ABI 1.7 adds
type_bridge_query_limit_override_v1_t and
type_bridge_query_session_open_with_limits_v1. Defaults are unchanged.
- Remote executors advertise the query limits and answer ceilings they
enforce. A client holds a request to the stricter of its own and the
advertised limits, refuses a query limit before sending, and asks for no
more answer than was advertised. The standalone server reads
[v2.query_limits] and [v2.answer_limits].
- Configurable answer limits. How much a query may return is one policy,
QueryExecutionResourceLimits, on both transports. A caller may raise a
dimension as well as tighten it: more than its transport's default can be
returned when the session, and through a proxy the executor too, are
configured for it. Only timeout_milliseconds (one day) and statements
(3) have a supported maximum; a value past it is refused by name.
- Query-limit and answer-limit refusals report limit, maximum, and
source (default, configured, or advertised).
- type_bridge_core.DEFAULT_DIRECT_QUERY_* and
type_bridge_core.DEFAULT_PROXY_QUERY_* (TIMEOUT_MILLISECONDS, ITEMS,
BYTES, GRAPH_NODES, ATTRIBUTE_VALUES, COLLECTION_MEMBERS,
ROLE_PLAYERS, STATEMENTS), and the same names on the native Node
module: the answer-limit defaults of each transport, read from the Rust
core. The TypeScript package no longer carries its own copies of
these defaults or of the codec byte ceilings; an omitted
QueryExecutionResourceLimits dimension takes the core default in every
language.
- type_bridge_core.InvalidQueryRequestError, a subclass of both
MatchRequestError and ValueError, for the query refusals 2.2 raised as
ValueError (codes zero_window_limit, window_overflow,
selection_cap_exceeded, empty_reducers, reducer_cap_exceeded,
field_group_tuple_cap_exceeded, reachable_bounds,
reachable_depth_limit), so except ValueError still catches them. Python
exception details keep int counts; only the JSON form uses strings.
- type_bridge_core.canonical_enum_spelling(kind, value) and the native
Node canonicalEnumSpelling(kind, value): check a spelling against the
core enum named by kind and return its canonical spelling (exact
becomes eq). Generated Python owner lookups (has(), owners()) use
it instead of their own list. The cases in
tests/contracts/enum-spellings.json are checked in Rust, Python, and
Node; C checks that its integer constants spell the same enums.
- The core's TypeQL compiler renders any single legacy node:
QueryCompiler::try_compile_node over the new ast::QueryNode, and a raw
fetch entry ast::FetchItem::Raw. The String-returning compile_node,
compile_pattern, compile_statement, compile_constraint, and
compile_value are public for bridging only and deprecated on arrival
(see Deprecated). Python's native QueryCompiler.compile_node(dict) takes
the tagged node form.
- type_bridge_core.blocking(obj): a blocking view of an object with
coroutine methods, such as a generated session, for code without an event
loop.
- A complete row cardinality in the request model and the V2 plan: every
distinct selected row, or a refusal when there are more than the limit. It
needs no order and no unique key. Plans that use it require the new
query.operation.complete-rows capability, which an executor older than
this release does not advertise.
- The pipeline stages emit field-free tracing spans a subscriber can
time: tb.orm.plan (plan build and staging), tb.query.compile
(lowering and rendering), tb.runtime.execute, tb.commit and
tb.decode. They record no query text or values; with no subscriber a
span costs one callsite check.
Changed¶
- A successful rollback keeps the transaction usable: the writes are
discarded, and more work can run and be committed on the same
transaction until
close(). This holds for Python and TypeScript transaction contexts (a Pythonwithblock commits work done after an explicit rollback when it exits normally) and for the staged transaction in every SDK. RustWriteTransaction::rollback(self)and C ABI 1.6type_bridge_write_transaction_rollbackstill consume the transaction; use the newWriteTransaction::rollback_keep(&mut self)and ABI 1.7type_bridge_write_transaction_rollback_keepto keep it. - TypeDB-origin errors now expose a bracketed code and fixed description instead of provider prose, including ordinary SDK errors, debug output, HTTP messages, migration diagnostics and Rust source chains. Existing exception ancestry, error variants, HTTP statuses and C ABI 1.6 statuses are preserved. Query values, credentials and endpoint text are excluded. Locally authored validation and application transport errors retain their existing messages.
- TypeDB transport failures keep a fixed failure kind and the operation name.
- A close failure after a successful commit is logged and no longer reported as an error: the write is durable, and reporting failure invited duplicate retries.
- Schema generation, TOML conversion, migration statements, V2 read plans, local functions, bounded fetch lists and prepared control reads render through the official TypeQL AST. Whitespace, stage separators, block indentation, capability commas, fetch objects and numeric spelling follow its plain display form; plan bytes and ordered given rows are unchanged. Snapshots, migration sources, carried queries, caller-owned function bodies and checksums keep their original bytes; new artifacts hash their new rendered bytes. Updates use the TypeQL 3 equality constraint.
- Active schema and query parsers use the official grammar and refuse
unofficial syntax or constructs legacy nodes cannot hold; empty legacy input
still parses to an empty clause list. The deprecated archive reader keeps
released inputs until 3.0. Checked lowering refuses non-
Hasrelation attributes and ownership deletes whose attribute type it cannot retain. - Retained Python schema, migration, CRUD and query helpers pass typed metadata to Rust for rendering; their signatures are unchanged.
- TOML function bodies the official parser rejects report
MalformedFunctionBody. - Ordered ownership and role lists in live schemas are read through the
official AST. List drift reports
migration_typedb_observation_no_candidate_matchinstead ofmigration_typedb_export_invalid, while refusing the migration. - The published
type-bridge-ormandtype-bridge-schema-compatcrates pintypeql =3.13.4(was=3.12.0). - Generated manager writes that go through the projected executor run as
query-plan/v3write plans; the next entries describe them. Where they go through it: - Rust SDK: single insert, put, update and delete in every generated
package; batches (
*_many) only in packages generated with ordered collections (projection handler version 2). - C SDK: every single write and batch in every package; C has no handler gate.
- Python and TypeScript/Node: single writes and batches only in packages
generated with ordered collections (handler version 2). A TypeScript
single
deletekeeps the released path in every package. - The exceptions each entry names (ordered models, relation puts) keep the released path inside the executor.
Packages generated without ordered collections carry handler version 1,
and the handler version is the package's behaviour version. In 2.3 those
packages keep the released write path in Python and TypeScript (every
write) and for Rust batches, because routing them would change error
classes, rollback-only latching and batch limits without a regeneration.
Routing them to plans is a later opt-in (a handler bump on regeneration,
or 3.0).
- A projected relation insert resolves its role-player references inside
the write: each reference is an exact isa! match, or a disjunction over
the concrete candidate types, in the insert's own pipeline, so no lookup
query runs first. A reference that matches nothing still fails with
provider_identity_cardinality_invalid and writes nothing. A polymorphic
reference that matches several things, and two references of one role
that resolve to one player (duplicate_resolved_role_player), are now
refused after the write instead of before it.
- A projected entity put with a key value is one write: it puts the key
on exactly the declared type, clears the non-key fields the input omits
and updates the given ones in the same pipeline, so no key lookup runs
first. A multi-valued field it gives is emptied and its values attached
in the same plan. A put on a model with an ordered field, and every
relation put, still look the key up first.
- Projected entity insert, update and delete, and relation update and
delete, are each one write plan; inserts and updates answer their own
hydration document, so no read-back follows. Updates keep the complete
replacement: every non-key field (and, for a relation, every role) is
cleared and the given values and players attached, references resolved
in the same plan. Inserts and updates on models with ordered fields or
roles, and relation updates without players, keep the released path;
every delete that reaches the executor runs as a plan. For the Rust SDK
single insert, provider answers that do not describe exactly one
canonical thing now report missing_post_write_row,
provider_identity_cardinality_invalid or provider_identity_mismatch
instead of invalid_provider_evidence.
- When a projected insert, update, keyed put or delete (entity or
relation) fails after its write plan was dispatched (including
hydration), a borrowed transaction is now rollback-only. A plan that
could not be lowered reached no provider and latches nothing.
- A projected relation insert or keyed entity put hydrates its result from
the write's own fetch, so one query does the whole call and no read-back
follows it. If that answer names two relations, the call fails with
provider_identity_cardinality_invalid (the write made two) instead of the
read-back's provider_hydration_failed.
- In Python packages generated with ordered collections (handler version
2), a generated model's single delete goes through the projected
executor, as one query-plan/v3 delete plan, like its batch deletes.
Packages generated without ordered collections keep the released delete
path. An absent thing is still a successful no-op on both paths.
- A projected batch write (Rust, Python and TypeScript batches in packages
generated with ordered collections; every C batch) runs each
stage as one statement over all its rows and splits only past the
limits: contiguous, ordered chunks of at most 4,096 rows within the
32 MiB envelope less the plan bytes, fired on the same transaction, so a
split batch stays all-or-nothing. Every binding and the proxy split a
batch the same way. Before, a batch past those limits could not be sent;
a single row too large for any chunk keeps the batch_statement_limit
refusal. Batches in packages generated without ordered collections
(Python, TypeScript, Rust) keep the released path and its limits.
- Migration lease acquisition is one conditional write. A concurrent
acquirer that commits between this acquirer's read and write now fails it
with migration_execution_stale_fence instead of letting it silently take
the newer fence.
- Band 9 runs on the official Rust typedb-driver 3.13.6 (with
typedb-protocol 3.13.4), up from 3.12.3. It serves TypeDB 3.12 and 3.13
servers (band 8 does not serve 3.13) and includes upstream's fetch-kind
decoding fix. The release pin check now also fails when crates.io publishes
a stable driver on a newer minor line.
- TypeDB 3.13.6 is the recommended server, the V2 conformance baseline, and
the default image in docker-compose.yml, docker-compose.proxy.yml, and
test.sh. The installation guide lists the TypeDB window of every
TypeBridge release and recommends the newest supported TypeDB. New
workspaces and the shipped examples use the semantic profile
typedb-3.13.6/v1; existing workspaces keep the profile they declare. The
CLI --version output lists typedb-3.13.6/v1 among its semantic profiles.
- The Python typedb-driver extra accepts >=3.11,<3.14, and
>=3.12.3,<3.14 on CPython 3.14. CPython 3.14 remediation messages name
the 3.13 driver line.
- Answer-limit defaults are per transport. A direct session keeps the 2.2
values: 100,000 items, 64 MiB, 1,000,000 graph nodes, 4,000,000 attribute
values, 1,000,000 collection members and role players, 30 seconds, and 3
statements. Proxy connections and the server use the wire limits, as in
2.2: 65,536 items, graph nodes, attribute values, collection members, and
role players, and 32 MiB. One constructor chooses between them:
QueryExecutionResourceLimits::default_for(AnswerTransport); Default is
the direct policy. An answer between the two defaults is returned direct and
refused through a proxy as a wire limit (limit items or bytes,
source default).
- C: a direct database, transaction, call, or batch without a limits
descriptor now gets the direct defaults, looser than 2.2's 65,536
items; a proxy connection or remote context gets the proxy defaults. ABI
1.7 adds TYPE_BRIDGE_QUERY_DIRECT_DEFAULT_* and
TYPE_BRIDGE_QUERY_PROXY_DEFAULT_*; the released
TYPE_BRIDGE_QUERY_DEFAULT_* keep their 2.2 values.
- Node: ProxyConnection.answerLimits reports the connection's ceiling,
as Python's answer_limits does.
- C database, read-transaction, and proxy executes run through the Rust
query target that the other SDKs use, and the C remote context (the
caller-owned exchange) prepares requests through the Rust proxy
connection, so a connection's answer limits bind them the same way. The
header no longer describes limit values as clamped: they are kept, and a
value above its maximum is refused.
- A generated package runs direct queries on the executor a proxy uses. Each
request is adapted to a V2 plan under the package's embedded schema
authority, so the same query is accepted or refused the same way direct and
remote. The second selected-row executor is removed.
- Generated manager all and first run as complete fetches on the same
executor. Results and the manager_first_identity_not_unique refusal are
unchanged.
- A hydration graph and a row sequence in a reply are no longer capped at
65,536 by the container; the caller's budget bounds them.
- selected_slots validation messages no longer spell the number sixteen;
the ceiling is reported in the maximum detail.
- Python's raw builders render TypeQL through the Rust core only. Raw
Query/QueryBuilder, expressions, CRUD patterns, to_insert_query, and
QueryCompiler.compile/compile_batch send every node (clause, pattern,
statement, constraint, value, raw fetch string) to the core; the Python
renderer and its silent fallback are gone, and a node the core cannot
decode raises ValueError. Output is unchanged except:
- a str literal with a non-string declared value type
(LiteralValue("2024-01-01", "date")) renders unquoted in a pattern,
statement, constraint, or value compiled on its own, as it already did
inside a clause;
- a small double whose Python form has a negative exponent renders
positionally (0.00001, was 1e-05) where Python rendered it;
- an integer outside the signed 64-bit range and a non-finite double have
no TypeQL literal and raise ValueError (they were rendered as a quoted
string or nan).
- A generated Rust package verifies its embedded plan authority once per
process instead of on every plan build (3.4 to 9 ms per plan before).
A package that fails verification still fails every build.
Deprecated¶
Unless an entry says otherwise, each name below keeps working until it is removed in 3.0; the deprecated aliases build their replacement. 2.2 remote terminals were already awaited, so 2.2 remote-session code runs unchanged.
The released transaction entry points (Python Database.transaction(),
TypeScript RustDatabase.transaction(), Rust ReadTransaction and
WriteTransaction, the C ABI 1.6 functions) and the generated managers'
write paths are not deprecated in 2.3: the staged transaction does not yet
carry managers or typed queries.
- TypeDB 3.11 support is deprecated in 2.3.0 and removed in 2.4.0. 2.3 still runs queries and CRUD on 3.11 servers; move to TypeDB 3.12 or 3.13 (3.13.6 recommended) before upgrading to 2.4.
- Python
update_with(func)on filtered queries and generated managers is deprecated since 2.3.0 for removal in 3.0 and emits aDeprecationWarning. It runs a host callback over rows it read; compute the new value withlet_()in an update plan and stage it in a transaction instead (see the typed-queries guide). - Python
type_bridge.session.Transaction, the direct-driver transaction wrapper, emits aDeprecationWarning; useDatabase.transaction(). - Rust String schema-generation and fragment helpers (the ORM's
schema::generatorfunctions such asgenerate_define_block,attribute_definitionandcard_annotation) are deprecated since 2.3.0 for removal in 3.0. Use checkedSchemaInfo::to_typeqlor adapter builders. Python schema generation propagates checked errors asValueError. - Legacy query nodes and String-returning compiler methods are deprecated
since 2.3.0 for removal in 3.0: the
asttypes (Clause,Pattern,Statement,Constraint,Value,FetchItem,QueryNode, and their parts) andQueryCompiler::compile,compile_node,compile_clause,compile_pattern,compile_statement,compile_constraintandcompile_value. Use generated typed query plans, ortry_compile/try_compile_node, which returncompiler::TqlError, when bridging legacy nodes. PythonQueryCompiler.compile,compile_clause_body,compile_batchandparse_typeql_queryemitDeprecationWarning; type-bridge's own helpers do not. - The frozen schema archive reader is deprecated since 2.3.0 for removal in
3.0: Python
type_bridge_core._ArchivedTypeSchema.from_typeqlemits aDeprecationWarning, and Rusttype-bridge-core-lib_parser::parse_typeqland_schema::TypeSchema::from_typeqlare#[deprecated]. Use Split-YAML schema authority. - Generated Python packages (each constructor emits a
DeprecationWarning): RemoteQuerySession(advertisement, exchange, limits, *, cancellation=None)is aQuerySessionsubclass that only buildsQuerySession(ExchangeConnection(advertisement, exchange), resources=limits, cancellation=cancellation).RemoteQueryLimits(max_items=..., max_bytes=..., max_collection_members=..., max_graph_nodes=..., max_attribute_values=..., max_role_players=..., deadline_ms=None)returns aQueryExecutionResourceLimits(items=,bytes=, ...,timeout_milliseconds=);isinstance(limits, RemoteQueryLimits)still holds, but read the new field names (limits.items, notlimits.max_items).RemoteQueryisQuery;RemoteGroupedQueryisGroupedQuery.- Generated TypeScript packages (
@deprecatedin the declarations): new RemoteQuerySession(advertisement, exchange, limits, cancellation?)is aQuerySessionsubclass that only buildsnew QuerySession(new ExchangeConnection(advertisement, exchange), { resources, cancellation }).RemoteQueryLimitsis the 2.2 shape{ maxItems, maxBytes, maxCollectionMembers, maxGraphNodes, maxAttributeValues, maxRolePlayers, deadlineMs? }or aQueryExecutionResourceLimits;RemoteQuerySessionconverts the former. UseQueryExecutionResourceLimits.RemoteQueryisQuery,RemoteGroupedQueryisGroupedQuery, andRemoteQueryExchangeis theExchangeConnectionexchange callback type.- Rust (
#[deprecated]): SchemaLoweringProfileFingerprint::compute(bytes)scopes the fingerprint to the TypeDB 3.12.1 lowering profile, as in 2.2. Usecompute_for_profile(profile_id, bytes).SchemaLoweringBinding::current(capabilities)binds the TypeDB 3.12.1 lowering profile, as in 2.2. UseSchemaLoweringBinding::for_semantic_profileorfor_context, which select the registry of the profile in use.RemoteDatabase<S>isProxyDatabase<S>.RemoteQueryTransportis the 2.2 trait; every implementation is aProxyExchange. ImplementProxyExchange.RemoteConnectionOptions::generated(limits, transport)returnsProxyConnectionPolicy::with_exchange(transport).answer_limits(limits), andRemoteConnectionOptions::new(scope, profile, limits, transport)adds.authority(scope, profile).RemoteConnectionOptionsitself is only these constructors, becauseProxyConnectionPolicy::newnow takes aProxyEndpoint; nameProxyConnectionPolicyin type positions.RemoteQueryLimits::new(max_items, max_bytes, max_collection_members, max_graph_nodes, max_attribute_values, max_role_players)with.deadline_ms(ms)converts intoQueryExecutionResourceLimitswith the matching fields, the proxy default statements, and the proxy default timeout unlessdeadline_mssets one. UseQueryExecutionResourceLimits.DirectTlsisTlsPolicy(type_bridge,type_bridge_orm, andtype_bridge_orm::session).MAX_QUERY_ITEMS,MAX_QUERY_BYTES,MAX_QUERY_GRAPH_NODES,MAX_QUERY_ATTRIBUTE_VALUES,MAX_QUERY_COLLECTION_MEMBERS, andMAX_QUERY_ROLE_PLAYERS(type_bridgeandtype_bridge_orm) equal the matchingDEFAULT_PROXY_QUERY_*, their 2.2 values.type_bridge_schema_migration_typedb::require_supported_migration_serverstill requires exactly TypeDB 3.12.3, thetypedb-3.12.1/v1server. Userequire_supported_migration_server_for_profile.type_bridge_orm::Transactionandtype_bridge_orm::session::TransactionareOwnedTransaction; nameOwnedTransaction. In 3.0 the staged transaction takes the session-levelTransactionname.DriverBackend::open_schema_fenced_read_transaction, the custom backend schema-fence hook; use the core transaction options.
Fixed¶
- Generated entity models'
insert_many(Python, Node) sends one batched insert again on TypeDB 3.12+, instead of one query per row (regression since 2.1.0). Transaction::stage_planrefuses aquery-plan/v3program lifted from a V2 plan that keeps its filter or model terminal as compatibility evidence (query_plan_compatibility_unsupported), instead of running it without the filter and answering unfiltered rows.- Legacy query compilation no longer emits TypeQL that the TypeQL 3 parser
rejects: attribute values render as one
isaconstraint instead of$a isa T; $a "v", keyed wildcards as fetch objects, zero-argumentcountas a reducer, and optional blocks parse back astry. Decimals keep exact digits and fetch keys are escaped. - Deprecated String compile and schema helpers return empty output for structured
shapes the official AST rejects, instead of invalid TypeQL. Python
QueryCompiler.compileand the server pipeline raise on non-Hasrelation attributes that earlier releases silently dropped. - Python
compile_batch(..., "match")terminates each pattern with a semicolon, correcting batches rejected by TypeDB with TQL03. - Native schema migrations preserve ordered ownership and role list markers, including annotations, specialisations and removals, preventing scalar drift.
- Backfill count queries retain unrelated negative filters and accept equivalent compact carried statements, correcting overstated matched/skipped totals.
- Structured migration tuple functions emit comma-separated return types,
correcting headers rejected with TQL03. Ordered role specialisations emit
matching list markers on the parent, correcting invalid
asclauses. - TOML
long/intandboolaliases now emit TypeDB builtinintegerandbooleandomains instead of unresolved type labels (SYR4). - Schema generation omits unchanged inherited plays declarations on subtypes, correcting schemas rejected by TypeDB with SVL42. Introspection stores scoped role labels as local role names.
- TOML structs now use TypeQL 3
struct name: field value type;syntax. Schema introspection binds type labels withlabel, correcting the obsoletetypeconstraint in ownership and role queries. - Python and Node generated queries on a direct connection now run under
the connection's answer limits (
answer_limits/answerLimitsgiven when connecting). They used only the session's own limits, so a session could return more, or run longer, than its connection allowed. Rust and C already applied the ceiling; every binding now shares one rule. - Generated manager filters in every binding now stop at the connection ceiling's timeout. They tightened resources to the ceiling but kept the deadline captured before it.
- Repeated
whereclauses and chainedand/orpredicates build one flat conjunction or disjunction in every binding. A query with more than about thirty clauses used to nest past the canonical JSON depth of 64, so remote sessions refused it withcanonical_json_too_deepand direct sessions ran it on a separate fallback path.
Security¶
- Prebuilt distributions use rustls-webpki 0.103.16, which fixes RUSTSEC-2026-0382 (certificate verification could accept distrusted intermediates).
- No distribution bundles the webpki root store any more
(RUSTSEC-2026-0381, distrusted emSign intermediates in webpki-roots).
The HTTP version probe and the proxy client already trusted only the
operating-system roots or the configured PEM bundle; they now reach
HTTPS through their own rustls connector instead of ureq's
tlsfeature, which linked webpki-roots.
Tests and tooling¶
- SDK conformance test contracts are named by concern: queries, models, administration, serialization and artifacts. The sdk-v1 smoke report is folded into queries, and administration runs natively on each TypeDB profile.
- The
writesSDK conformance suite runs its staged programs (the purchase, key constraints, and the shop checkout ofexamples/shop) in Python, TypeScript, Rust and C, directly and through the proxy, and checks that plan bytes, answers and stored state are identical, on TypeDB 3.13.6. - The SDK conformance sets (
sdk-v1tosdk-v6) run on TypeDB 3.12.3 and 3.13.6 through a per-profile matrix: each set lists the expected server and fingerprints for every supported semantic profile, and a report set must share one profile. ./test.sh --typedb <line|all>runs the live tier on one supported TypeDB line (3.11.5, 3.12.3, or 3.13.6; default 3.13.6), or on every line followed by the two-server profile-upgrade run. Each line runs under its own semantic profile.- Generated live fixtures follow
TYPE_BRIDGE_ACCEPTANCE_SEMANTIC_PROFILE(defaulttypedb-3.13.6/v1) and require the exact server their profile names: 3.12.3 fortypedb-3.12.1/v1, 3.13.6 fortypedb-3.13.6/v1. - Perf tracking groundwork: the
Perfworkflow runs the core and ORM micro benchmarks on pushes to master, nightly, on dispatch and on pull requests, and uploads Criterion wall times and gungraun instruction counts as one validatedperf-result/v1file. Master, nightly and dispatch runs are stored on theperf-databranch, and the docs site charts that history at/perf/. - The same
Perfrun records the Python binding benchmarks inbenchmarks/(native query compilation, clause marshalling and validation throughtype_bridge_core) asbinding.python.*metrics. The suite drops its pure-Python comparison benches andbenchmarks/run_benchmarks.pywith its TOML reports, and thebenchmarkpytest marker is gone: runuv run pytest benchmarks --benchmark-only. - The
Perfworkflow also records build times, artifact sizes and test-suite durations, and compares base and head on pull requests. On master, nightly and dispatch runs it times the Rust SDK pipelines (insert, fetch by key and filtered, update, delete, a 1,000-row batch, a staged purchase, migration apply) against TypeDB 3.13.6 and draws each pipeline's stage medians on/perf/.
[2.2.6] - 2026-10-16¶
Fixed¶
- Commit failures report a definite abort only for TypeDB codes that prove the commit was rejected; other server failures now report unknown certainty, as transport failures already did, so callers no longer retry an unproven abort (#251).
- Invalid given-row values report the column and type without exposing the value or parser details.
- The local test harness validates every SDK report and comparison summary before logging SHA-256 evidence, and fails when validation fails.
[2.2.5] - 2026-10-14¶
Added¶
TypeDBClient::execute_classifiedpreserves commit-failure certainty and driver text, distinguishing rejected commits from indeterminate outcomes while retaining the existingexecuteerror contract (#251).
Fixed¶
- Write queries ending in
fetchnow return commit failures instead of returning documents for writes that were never stored (#252).
Security¶
- Updated
quinn-prototo 0.11.19 for RUSTSEC-2026-0338 through RUSTSEC-2026-0342, addressing memory-exhaustion and connection-ID retirement issues in QUIC handling. - Updated
rustlsto 0.23.46 for RUSTSEC-2026-0346 through RUSTSEC-2026-0349, addressing TLS secrets inDebugoutput, a key exchange downgrade, certificate decompression memory use and data sent after ECH rejection.
[2.2.4] - 2026-10-08¶
Fixed¶
- Closing a transaction after a bounded query stops early no longer wedges the TypeDB server. Bounded queries asked the server to stream one answer per batch; with that prefetch, TypeDB 3.11 to 3.13 could deadlock while closing the paused stream whenever the driver's latency estimate rounded to 0 ms. The close then never completed, the transaction never timed out, and its database stayed "in use" until the server restarted. Bounded queries now request two answers per batch, which leaves room for the stream's trailing messages.
- Python batches running on several threads no longer leave the garbage collector disabled. Each batch disabled the collector and restored the state it had seen on entry, so batches ending out of order could turn collection back on mid-batch or leave it off for the rest of the process. The collector is now restored only when the last running batch ends.
[2.2.3] - 2026-10-07¶
Security¶
- Install Debian's fixed Bookworm PCRE2 (
10.42-1+deb12u2) and Perl (perl-base 5.36.0-7+deb12u4) packages in the server image for both architectures, pinned by checksum. The pinned base image predates fixes for CVE-2026-103111, CVE-2026-13221, CVE-2026-42496, CVE-2026-8376, CVE-2026-42497, CVE-2026-48962, CVE-2026-57432, and CVE-2026-57433.
Fixed¶
- Bounded projections sorted by a unique key now validate when they select
mandatory single-valued fields, such as a
[1,1]Double. The window-order proof derives each[1,1]attribute from its determined owner, and each player of a[1,1]role from its determined relation; a key it cannot use on its own, such as a Double, may sort alongside the keys that determine it. Optional, negated, and disjunctive patterns do not propagate, and a Double alone is still refused withquery_plan_window_order_not_total. Plans that validated before keep their canonical bytes (#244).
[2.2.2] - 2026-09-14¶
Security¶
- Require rustls 0.23.45 and update resolved TLS dependencies to fix RUSTSEC-2026-0285, which rejects TLS 1.3 handshake messages crossing encryption levels.
Fixed¶
- Avoid unused imports and empty function/struct re-exports in generated Rust for schemas containing attributes and entities without roles, functions, or structs. Pristine consumer test modules pass strict Clippy.
[2.2.1] - 2026-09-14¶
Fixed¶
- Add per-binding canonical type-name overrides through workspace
type-namesand RustProjectionConfig. Resolve generated model/reference collisions without changing database labels or semantic schema identity. - Generate Rust validation checks on separate lines and emit Clippy-clean
reference validation and collection encoding. Cover pristine generated
consumer test modules under
-D warnings.
[2.2.0] - 2026-09-14¶
Fixed¶
- Apply Debian's PCRE2 security update to both server-container architectures, fixing CVE-2026-86145 and CVE-2026-89161 with checksum-pinned packages.
- Fix generated TypeScript construction for unbounded roles and list fields by
recognizing canonical
"unbounded"cardinality metadata. - Project model fields and roles that collide with runtime members to names with
a trailing underscore, including the physical string key
nameasname_. Preserve schema identity and existing non-colliding names. Regenerate complete TypeScript packages after updating the generator and compatible runtime.
C SDK and standalone CLI¶
- Release the standalone CLI and ABI 1.6 C shared runtime for Linux x86_64 on Ubuntu 24.04, with independent generated schema packages and complete V1โV6 application acceptance. Signed public artifacts passed independent provenance, installation, C17/C++17, and live-consumer checks.
- Add exact-source artifact verification and signed promotion to the GitHub release draft, preserving accepted archive bytes and supporting only absent-or-identical partial-upload recovery.
- Use TypeDB 3.12.3 for the exact connected migration baseline while retaining
the canonical
typedb-3.12.1/v1semantic profile.
[2.1.0] - 2026-09-08¶
Security and release reliability¶
- Forward-ported the patched PyO3 0.29.2 and dependency graph from the 2.0.2 maintenance release, preserving the generated-only 2.1 boundary, abi3-py312 and GIL-required semantics. CI and releases require fresh dependency audits.
- Pinned deterministic native license selection and the metadata-2.5-compatible PyPI publisher; validate facade metadata before cross-registry publication.
Changed¶
- Generated-only application bindings (#189) - Split YAML plus
type-bridge schema generateis now the sole active schema/model authoring path. Generated Python, TypeScript/Node, and Rust packages retain the supported CRUD, transaction, hook, query, reducer, local/remote, hydration, and diagnostic outcomes previously exercised through handwritten models. Python keeps the concise generated single-type manager API, includingPerson.manager(db).put(...)and lookup-suffixedfilter(...)terminals. - TypeDB 3.11/3.12 support window - Native packages now contain only bands 8 and 9. Active TypeDB 3.8/3.10 support, provider sources, warning APIs, build features, matrices, and release inputs are removed; retired versions fail before data work.
- Authoring cutover with recovery retained - Handwritten Python/Node/Rust schema declarations, direct TOML generator routing, programmatic TypeQL model generation, and root Python/JSON migration authoring are removed. Read-only TOML conversion and archived migration loading, checksum verification, ledger import, snapshots, adoption, and recovery remain.
- 2.1.0 artifact identity - Python, npm, Cargo, generated Rust templates, documentation, and release validation share the 2.1.0 identity. See the 2.1.0 release notes for the complete cutover inventory and upgrade guidance.
[2.0.2] - 2026-09-07¶
Security and compatibility notice¶
- Patched PyO3, crossbeam-epoch, h2, rustls-webpki, anyhow, rand and chacha20 while retaining 2.0.x APIs, provider support, existing warnings and abi3-py312.
- Published the expanded, fully qualified 2.1 removal/replacement inventory
and safe
<2.1pins in the 2.0.2 release notice. This new notice does not rewrite the historical 2.0.0/2.0.1 commitments. - Recovered the unchanged Python facade artifacts with a metadata-compatible publisher; the release notice records original source and recovery-control provenance. Existing tag and registry bytes were not replaced or rebuilt.
[2.0.1] - 2026-08-03¶
New Features¶
- Cargo-distributed Rust SDK -
type-bridgeand its complete supporting Rust graph are publishable to crates.io in dependency order. Release gates package and preflight every candidate without mutation, preserve the checksum-pinned historical TypeDB band-7 crates, and publish the authorized band-8 compatibility packages only from the accepted stable tag. Python and Node native binding crates retain their separate PyPI and npm identities.
Documentation¶
- Added a linked crates.io version badge and crates.io-first Rust installation guidance while retaining the exact Git instructions for historical 2.0.0.
[2.0.0] - 2026-07-31¶
New Features¶
- Canonical Split-YAML schema and multi-language projections (#188) -
TypeBridge V2 workspaces now make versioned
typebridge.schema-set/v1manifests andtypebridge.schema/v2fragments the canonical schema authority. The strict, bounded YAML subset rejects unknown or duplicate facts, unsupported future shapes, unsafe paths, and nondeterministic discovery before provider I/O. Rust resolves the complete document set once and projects the same declared meaning into Python, TypeScript/Node, and Rust bindings. The workspace CLI validates schemas offline withschema check, generates every configured SDK withschema generate, and emits the deterministic authority consumed by V2 executors withschema export-declared. - Offline history-based migrations and workspace CLI (#188) - Rust now
authors immutable
migrations/v2programs from the desired schema and committed history, orders and verifies the chain, detects drift, and never infers destructive approval. Thetype-bridge migrationCLI exposesmake,plan,apply,verify, andadoptagainst named workspace environments. Legacy adoption validates the complete dependency graph, applied ledger, original checksums, portable sidecars, and snapshot authority; it records a writer cutover and canonicaladopted-genesis.typeqlwithout re-executing legacy operations such asRunPython. Failed adoption remains retryable, while retained legacy readers and historical artifacts stay available. - Authenticated local/remote Query V2 and standalone executor (#188) -
the same Rust-owned canonical plan, invocation, schema/profile validation,
capability checks, limits, and structured diagnostics now govern direct
execution and the standalone server's
/v2/capabilitiesand/v2/queryroutes. Prepared remote requests bind the executor identity, nonce, fingerprint, expiry, capability set, and response budget before provider transaction construction; signed successes and failures are authenticated before hydration. The capability advertisement is an explicit trust input that callers obtain over authenticated TLS or pin out of band. One awaited remote terminal performs exactly one caller-owned exchange with no built-in discovery, credential, HTTP-client, retry, traversal, or follow-up hydration behavior. - Complete V2 query authoring and remote model facade (#195) - Python now
exposes the complete low-level Rust plan builder from
type_bridge.query_v2, with the equivalent Node API at@type-bridge/node/query-v2. Opaque handles cover the full V2 pattern, function, reduction, stage, document, reachability, typed-input, and invocation vocabulary while Rust alone owns validation, canonical bytes, fingerprints, and capabilities. The model-orientedRemoteQuerySession/RemoteQueryfacade reuses the released immutable direct grammar with explicitly awaitable terminals: composition performs no I/O, and one awaited terminal performs exactly one caller-owned exchange with no built-in discovery, authentication, HTTP client, retry, traversal, or hydration query. Authenticated graph validation and caller ceilings precede model construction; direct and remote paths preserve result order, structured diagnostics, and registered concrete-subtype hydration. V1 query facades remain operational with no removal schedule. The Rust-ownedcount/max/mean/median/min/std/sumreducer vocabulary is pinned through Python and TypeScript source and packaged declarations. The Python and Node V2 binding smokes now author plans at runtime, and exact-artifact parity covers documents, bounded reachability, and authenticated structured failures; canonical, fingerprint, hostile, V1 wire, MatchRequest, and released compatibility fixtures remain retained. - Bounded typed reachability (#193) - Python and Node typed query sessions can now express an inclusive finite directed walk over an exact relation and ordered endpoint roles. Zero depth is concept identity; positive depths admit cycles and repeated vertices while proof paths remain existential, so selected result identity and stable ordering retain the ordinary typed-query contract. Bounds and expansion budgets fail during construction before provider I/O, and Rust lowers the full range into one query without client-side traversal.
- Public generated Rust application client -
type-bridgeand generated schema crates now expose owner-branded entity/relation CRUD, exact and subtype reads, complete replacement, reusable write/read transactions, typed expressions and reductions, selected/collected pages, bounded reachability, and identical local/one-exchange remote materialization. The generated crate has only one direct TypeBridge dependency and the complete consumer contract is accepted on Rust 1.88. PublicErrorCategory, stable codes, structured paths, and validation phases now survive both direct and remote adapters; caller-owned transports useError::remotefor classified transport failures. - Hardened server OCI distribution -
ghcr.io/ds1sqe/type-bridge-server:2.0.0is built once forlinux/amd64andlinux/arm64from digest-pinned bases with the locked V2-capable server. Exact layouts run as UID/GID 10001 with a read-only root, no capabilities, and no-new-privileges; acceptance covers V1 compatibility, authenticated V2, and the external generated Rust application. Stable publication imports the accepted manifests without rebuilding, verifies all aliases and digests, and attaches keyless signatures, SPDX SBOMs, provenance, and scan evidence.
Changed¶
- Fail-fast schema-annotation compatibility - all ORM schema-query
boundaries now reject
@doc/@metabefore provider dispatch when the known TypeDB server is older than 3.12. One-shot execution rejects before opening a transaction, while caller-owned schema transactions reject before their provider query. The 3.12 generated-projection fixture remains annotation preserving and runs only in the 3.12 TLS lane; older lanes continue to prove transport compatibility. -
Legacy TypeDB server notices (#189) - each successful TypeDB 3.8/3.10 connection now emits one filterable compatibility notice while continuing normally: Python uses
TypeDBServerDeprecationWarning, Node uses standard warning typeDeprecationWarning, and Rust tracing uses codeTYPE_BRIDGE_TYPEDB_LEGACY_SERVER. The conservative unknown-version notice is limited to an actually negotiated band-7 fallback and does not claim an exact server version; missing HTTP identity on band 8 or 9 does not warn. TypeDB 3.11 and 3.12 connections do not emit it. Active 3.8/3.10 support remains operational throughout every 2.0.x release and is removed in the 2.1.0 minor. Warning lookup or delivery cannot turn a successful connection into a failure: Python warning-to-error promotion and synchronously throwing replacements of Node'sprocess.emitWarningare contained, while Node--throw-deprecationsuppresses this compatibility notice. Exceptions raised later by application-owned Nodewarninglisteners retain ordinary Node process semantics. The removal schedule names a single release, documented exactly in V2 Deprecations. Every scheduled removal lands in the 2.1.0 minor release as a deliberate, exactly-enumerated exception to ordinary major-version scheduling: active TypeDB 3.8/3.10 provider and driver support ends (the wheel then embeds only the band-8 and band-9 driver lines), and directschema.tomldesired-schema authoring,generate_models(..., format="toml"), and Python.tomlgenerator auto-routing are removed; both TOML authoring routes emit a filterable PythonDeprecationWarning. Deployments retaining a 2.1.0-scheduled surface pintype-bridge>=2,<2.1. V1 query facades have no removal schedule, and archival migration readers, checksum verification, ledger import, snapshots, converters, and the legacy-frontier bridge remain retained. The 2.1.0 removal inventory further includes: -
type_bridge_core.TypeSchema,type_bridge_core_lib::schema::TypeSchema,type_bridge.SchemaInfo,type_bridge.migration.SchemaInfo,type_bridge_orm::SchemaInfo,type_bridge.SchemaManager,type_bridge.migration.SchemaManager, andtype_bridge_orm::SchemaManager; - the fused
type_bridge.Role[T]/type_bridge.models.Role[T]declaration surface; and - authoring new legacy root
NNNN_*.pymigrations and sibling JSON files, plus treating those files as active migration authority.
type_bridge.MigrationManager /
type_bridge.migration.SimpleMigrationManager; the Python V1
type_bridge.Query and type_bridge.QueryBuilder; the Node V1
TypedQuery<T, Row> and TypedGroupByQuery<Row>; and the Rust V1
type_bridge_orm::MatchRequest entity, relation, and group-by query facades
are each deprecated without a removal schedule. Read-only TOML conversion,
legacy migration readers, original checksums, applied-ledger import,
snapshots, historical server metadata, and the legacy-frontier bridge are
explicitly retained. Apart from the named 2.1.0 removals there is no
other removal or calendar cutoff โ there is no 3.0.0 removal plan;
deployments retaining any scheduled surface can pin
type-bridge>=2,<2.1.
- Rust V2 source/Git distribution boundary - the internal V2 semantic,
migration, projection, workspace, and CLI crates remain first-party
workspace packages with publish = false; they are not crates.io release
identities. The public type-bridge package still depends on that
unpublished graph, so 2.0 distributes it from the exact release Git
revision instead of publishing a broken crates.io package. The release gate
blocks Cargo mutation and names the exact source/Git SDK in the closed
artifact set.
- Direct Python driver 3.12.1 - CPython 3.14 dependency markers, native
artifact probes, and live compatibility cells now use the current 3.12.1
Python driver patch; CPython 3.12โ3.13 retains the released multi-line
compatibility contract.
- Upstream-native TypeDB 3.12 runtime - the default band-9 path now uses
the official upstream Rust driver/protocol packages directly and is
exercised against the TypeDB 3.12.1 conformance server. The exact source pin
is the newest non-yanked stable 3.12.x release at the first-publish cutoff
(currently 3.12.1); retries after that cutoff retain the exact release graph
already started. No active, consumed, or release-input TypeBridge band-9
fork exists.
- Terminal embedded-driver close dispatch (#196) - Python, Node, and Rust
database close boundaries now invoke the selected driver's upstream
idempotent force_close() API and immediately reject new work. Upstream
3.12.1 dispatches shutdown but releases its final callback worker only when
the last shared driver lease drops, so TypeBridge does not promise a
synchronous worker join from a retained closed handle. This is a temporary
downstream lifecycle workaround, not a driver or protocol patch;
#196 is its removal gate.
- Legacy multi-band compatibility packaging - band 7 reuses the already
published type-bridge-typedb-driver-b7 3.8.1 and protocol 3.7.0 packages;
band 8 uses namespaced driver 3.11.5 and protocol 3.11.0 source-unmodified
packaging candidates. The later Cargo-distribution authorization permits
first publication; these exact source-unmodified packages remain the
authorized compatibility artifacts, with protocol preceding driver. Their
Rust source behavior is byte-identical to the respective upstream archives,
with no downstream transaction-close or other behavioral patch.
Namespacing is solely a Cargo package-identity mechanism that permits all
protocol bands in one native graph. TypeDB remains the original upstream
owner, and its Apache-2.0/MPL-2.0 licenses are preserved.
Documentation¶
- Multi-surface documentation and contributor workflow (#200) - the
public README and MkDocs site now present TypeBridge as one Rust semantic
engine exposed through Python, TypeScript/Node, generated Rust, schema and
migration tooling, immutable queries, and the standalone server. The
README is kept below 200 lines with a runnable schema-before-CRUD quick
start and an accessible repository-owned hero that renders on package
pages. Stable detailed URLs now sit behind focused SDK, modeling, data,
schema, operations, Python API, and maintainer routes.
DEVELOPMENT.mdis the canonical contributor guide, with regular cross-platformAGENTS.mdandCLAUDE.mdpointers; stale test totals and directory snapshots are removed, anddocs/SKILL.mdnow validates and routes workflows across every supported product surface.
[1.5.11] - 2026-07-19¶
Bug Fixes¶
- Declared role-player migration authoring (#190) - Migration authoring
now reduces inheritance-flattened role-player vectors to the capabilities
actually declared in each schema. This prevents phantom
playsoperations, preserves declaration changes hidden behind identical effective player sets, and orders player changes safely around entity and relation hierarchy updates.
[1.5.10] - 2026-07-16¶
Bug Fixes¶
- Sub-type migration planning and apply (#190) - Planning a migration
that adds an entity or relation with a parent no longer panics with
no entry found for key. Authored add operations now emit parents before children and carry only declared capabilities, so the child's define step keeps itssubclause without redeclaring inherited attributes or roles, which TypeDB rejects at apply time. Verified against live TypeDB servers from 3.8.3 through 3.12.1.
[1.5.9] - 2026-07-15¶
New Features¶
- Public migration and TOML-transpiler crates -
type-bridge-migrationandtype-bridge-toml-transpilernow participate in the validated crates.io publication graph. The transpiler publishes as an independent crate; migration publishes only after itstype-bridge-ormdependency is visible in the registry index.
Bug Fixes¶
- Fail-closed Python relation players (#170) - Python typed queries reject
nested relation-player materialization during planning, before provider I/O,
while preserving legacy
Role[Relation]declarations and CRUD. Defensive result hydration also rejects unsupported evidence; Node retains its released shallow V1 result contract.
Testing & Tooling¶
- Exact F8 release-artifact gate (#170) - registry publication now waits for the exact Python wheels and packed Node tarball to prove the Python rejection and Node shallow-result contracts live on TypeDB 3.8.3, 3.11.5, and 3.12.1.
[1.5.8] - 2026-07-15¶
New Features¶
-
@doc/@metaschema annotations (#169) - TypeDB 3.12's schema documentation and metadata annotations are declarable from all three model surfaces:TypeFlags(doc=..., meta=...)/AttributeFlags(doc=..., meta=...)and theFlag(Doc(...), Meta(...))ownership markers in Python, with matching TypeScript typed-layer and Rust static-model options, plus role-leveldoc=/meta=onRole(...). Annotations are emitted in schema define lowering, round-trip through the generator with three-target surface parity, and are carried by schema export/introspection. -
Annotation-aware migrations (#169) -
makemigrationsdetects@doc/@metaadditions, value changes, and removals on types, ownerships, and roles, authoring newModifyTypeAnnotations/ModifyRoleAnnotationsoperations with reverse steps. Annotation transitions lower to per-annotation schema steps (groupeddefine/undefineblocks, oneredefineper value change; removals first) โ this also fixesModifyOwnershiptransitions involving parameterless annotations (@key/@unique), which the old blanket-redefinelowering rejected live (REX28). Annotation-only changes classify as metadata-safe. -
Version gate for schema annotations (#169) - the server version detected by the connect-time gate is retained and exposed as
Database.detected_server_version(). Schema-apply seams (SchemaManager.sync_schema, the migration executor) check annotated DDL against it before sending: annotated schemas bound for a pre-3.12 server fail client-side with an actionable versioned error instead of a server syntax error.Database.check_schema_annotation_support()exposes the check directly. -
Band-9 embedded driver (#169) - the TypeDB 3.12 Rust driver ships vendored as
type-bridge-typedb-driver-b9alongside the band-7 fork and the crates.io band-8 driver, so 3.12 connections negotiate the native band-9 protocol automatically. Live measurement surfaced a hazard: a band-9 connection attempt crashes a 3.11 server, so the gRPC fallback discovers unknown servers through band 8 and upgrades to band 9 only after the reported version proves it safe. -
given-stage parameterized queries (#169) - one compiled TypeQL pipeline runs over many input rows, with the rows passed through the driver API instead of interpolated into the query string.Database.execute_with_rows()/TransactionContext.execute_with_rows()expose the raw surface (requiring both TypeDB 3.12+ and the negotiated band-9 provider;Database.supports_given_stage()reports that effective capability), and entityinsert_many()automatically rides one given pipeline for homogeneous batches when available โ measured ~4x faster than the per-row path at 1000 rows โ while degrading transparently to per-row inserts on older servers, band-8 fallbacks, and heterogeneous batches. -
Unified immutable typed queries (#170โ#177) - added additive
type_bridge.typedand@type-bridge/node/typedfacades with owner-aware variables, fields, and roles; exact or subtype matching; exact 1โ16-slot positional and named output typing; collected pages; and distinct-root page/count/exists operations. Rust owns canonical validation, TypeQL lowering, bounded execution, result identity, and transaction lifecycle. On negotiated band-9 connections, supported predicate values travel separately from TypeQL in one compiler-ownedgivenrow; older bands retain the validated inline path, and both routes preserve bounded streaming; existing package-root query and manager APIs remain available unchanged. -
TypeDB 3.12 server support - the compatibility window now extends to 3.12.x. Compatibility was measured live: server 3.12 accepts band-8 (3.11) drivers, while a 3.12 driver is refused by a 3.11 server, so the version gate now models servers as accepting a set of protocol bands and negotiates the connect band from that set. The embedded band-9 driver is selected only after a server is confirmed as 3.12; unknown-server fallback starts with band 8 to avoid probing a 3.11 server with the incompatible band-9 client. Installed Python driver 3.12 (band 9) is dispatched with the band-8 option form and gated correctly against both 3.11 (reject) and 3.12 (accept) servers; the
typedb-driverextra now allows<3.13.
Bug Fixes¶
- Reliable band-7 fallback on remapped TypeDB endpoints - when the HTTP version probe is unavailable, a lazy band-8 connection failure now advances to band 7 instead of terminating negotiation early. Rust integration helpers and Node parity consumers also honor the configured HTTP port.
- CPython 3.14 direct-driver compatibility - optional and development dependencies now select TypeDB driver 3.12.0 on CPython 3.14, with native constructor coverage. The CPython 3.12โ3.13 development environments retain driver 3.11.5 for the default 3.11 server, while the public extra continues to permit driver lines 3.8โ3.12. The embedded ORM runtime remains compatible with TypeDB 3.8โ3.12 on every supported interpreter.
- CPython 3.12 typed-facade compatibility - package metadata, defaulted
owner generics, static-tool targets, CI, and exact-artifact acceptance again
cover the declared
>=3.12,<3.15release range.
Testing & Tooling¶
- Typed-query artifact and live parity gates (#170โ#177) - added isolated Python-wheel and packed-npm consumers, positive/negative static contracts, native resource/lifecycle/snapshot regressions, and shared Python/Node live query coverage on the TypeDB 3.8, 3.10, 3.11, and 3.12 server lines.
- Release-candidate acceptance (#170โ#177) - each package registry consumes only its accepted immutable candidate; crates.io publication additionally waits for both complete Python archive/metadata/payload validation and exact npm-package acceptance. Exact-wheel runtime and typing consumers run on CPython 3.12, 3.13, and 3.14, and exact npm-package runtime consumers run on the declared Node 18 and 20 lines. Registry retries accept an existing artifact only when its published hash matches the candidate.
- TypeDB 3.12.0 CI legs - all ordinary Python integration groups (including
sessioncoverage forgivennegotiation), node-integration, and cross-language-parity matrices gainedtypedb/typedb:3.12.0legs (paired with Python driver 3.12.0), and the version-gate cells gained aNEG-driver-band9regression for the asymmetric 3.12-driver / 3.11-server rejection.
[1.5.6] - 2026-07-10¶
New Features¶
-
Expose migration-state schema boundary for external ledgers (#165) - added a public migration-state schema descriptor and filtering helpers so callers can keep migration execution metadata in an external state store while leaving target application schema management untouched.
-
Pluggable migration state manager (#165) -
MigrationExecutornow accepts an optionalstate_managerso external orchestrators can inject their own state persistence backend while retaining the existing default TypeDB-backed behavior.
Testing & Tooling¶
- Integration coverage for external-state migrations (#165) - added live tests for external ledger execution paths and schema filtering behavior that validate default and injected-state modes across TypeDB live integration.
[1.5.5] - 2026-06-30¶
Bug Fixes¶
- Strict Boolean wrappers -
Booleannow rejects non-boolvalues at construction, Pydantic validation, Pydantic serialization, hydration, and Rust-backend dynamic value boundaries instead of truthiness-coercing strings such as"False"intoTrue.
Testing & Tooling¶
- Boolean strictness regressions - added unit coverage for direct Boolean
construction, Pydantic hooks, CRUD hydration through
wrap_attribute_value, and Rust backend boolean value marshalling.
[1.5.4] - 2026-06-26¶
New Features¶
- Generator name-case overrides (#163) - bindgen now accepts case
annotations case-insensitively, including
@case(PascalCase)and language-scoped forms such as@case(Python, SnakeCase). - PascalCase and TOML bindgen metadata (#163) - Python model generation now
maps PascalCase TypeDB names to
TypeNameCase.CLASS_NAME, and TOML schemas can carrybindgen_caseplusannotationsmetadata for generated bindings.
Bug Fixes¶
- Mixed-case generated names (#163) - class-name generation now preserves
mixed-case sub-segments such as
FirstPersoninstead of lowercasing them during Python and Rust bindgen output. - Explicit generated type names (#163) - generated attribute configs now
emit explicit
name="..."flags when the TypeDB name does not align with the default language-specific name inference.
Testing & Tooling¶
- Cargo CI isolation (#163) - CI now keeps Cargo homes and caches outside the workspace, isolates cache keys by lockfile, and pins the stable Rust toolchain to reduce release-run cache and registry churn.
- Cargo lock checksum repair (#163) - refreshed the affected Rust lockfile checksums so locked metadata validation passes cleanly in release checks.
[1.5.3] - 2026-06-24¶
New Features¶
- ORM-backed Python data migrations (#158) - migrations can now use
ops.RunPython(...)to run normal TypeBridge ORM code during migration execution, includingUser.manager(db).filter(...), bulk inserts, updates, deletes, and JSON/TOML-backed data loading. - Database-backed migration history (#158) - applied migration state and
execution attempts are stored in TypeDB through
type_bridge_migrationandtype_bridge_migration_run, including run IDs, checksums, direction, status, timestamps, errors, and executor metadata when available. - Historical snapshot bindings for generated migrations (#160) - generated
migrations now import stable time-state bindings such as
migrations.snapshots.v0001.Userinstead of the active generated model package, keeping old migrations replayable after later bindgen output removes or reshapes types.
Changes¶
- Snapshot drift protection (#160) - existing snapshot packages are validated by schema hash, generated file hash manifest, and top-level binding exports before reuse, so stale or hand-edited historical bindings fail clearly instead of silently changing migration semantics.
Documentation¶
- Migration guide added (#158/#160) - added a dedicated migration guide that
explains the generated migration workflow, why snapshots matter,
RunPythondata migrations, rollback, sidecar checksum drift, and TypeDB-backed migration/run history.
[1.5.2] - 2026-06-18¶
New Features¶
- Rust bindgen model renderer (#157) - Python, TypeScript, and Rust model
rendering now run through the shared Rust bindgen engine, with Python
generate_modelsand the Node generator facade delegating to nativerender_models_jsonbindings. - Renderer deduplication (#157) - The old Python Jinja renderer and duplicated TypeScript renderer implementation were removed, so future model generation changes land in one core implementation with cross-language parity coverage.
Bug Fixes¶
- Shared TypeDB runtime parity (#155/#154) -
type_bridge_server::typedb::TypeDBClientnow uses the same gRPC-only connect path, HTTP-probe fallback, and exactserver_versionoverride logic as the ORMDatabase.connectsurface. The ORM and server both depend on a shared TypeDB runtime crate for driver construction, database lifecycle, transaction execution, and JSON result conversion. - Node gRPC-only connect option parity (#154) -
@type-bridge/nodeensureDatabaseandRustDatabase.connectnow acceptserverVersion, letting Node callers skip the HTTP version probe for gRPC-only deployments while still validating the exact TypeDB server version.
[1.5.1] - 2026-06-17¶
Bug Fixes¶
- gRPC-only TypeDB connect support (#154) -
Database.connect(..., server_version=...)now accepts an exact server version across Rust, PyO3, and Python connect surfaces, letting deployments without a reachable HTTP version endpoint skip the HTTP probe while still validating the supported window. - HTTP probe fallback to embedded driver negotiation (#154) - when no
server_versionis supplied and the HTTP probe fails, the Rust runtime now falls back through gRPC band negotiation, trying band 8 and then band 7 and reporting every attempted path if neither driver can connect. - Version-gate CI coverage for fallback paths (#154) - CI now includes positive cells that force the HTTP probe onto a bad port and assert the gRPC fallback succeeds, with helper updates for both success and rejection expectations.
New Features¶
- Band-aware server database admin API (#155) -
type_bridge_server::typedb::TypeDBClientnow exposesdatabase_exists,create_database,delete_database, andreset_database, dispatching through the embedded TypeDB driver band selected at connection time. - Node database lifecycle parity (#155) -
@type-bridge/nodeRustDatabasenow exposesdatabaseExists,createDatabase,deleteDatabase, andresetDatabaseon the bound database handle, matching the Python/Rust ORM lifecycle surface.
[1.5.0] - 2026-06-15¶
Changes¶
Rust-SSOT typed migrations from generated schema diffs (#152)¶
- Generated migrations default to typed operations โ
makemigrationsnow renders schema diffs as operations such asops.AddAttribute(...),ops.AddEntity(...),ops.AddRelation(...),ops.AddOwnership(..., optional=True), and role/player changes instead of flattening schema diffs to raw TypeQL. - Rust remains the migration execution source of truth โ generated migration
sidecars preserve structured Rust
OperationSpecvalues, and the Rust planner lowers typed operations to executable TypeQL at planning/execution time. ops.RunTypeQLremains supported as an escape hatch โ handwritten data migrations and custom TypeQL can still useops.RunTypeQL(...); Rust planning infers schema vs write transaction kind so data scripts execute correctly.- Django-style
schema.tomllifecycle documented โ the generator guide andexamples/advanced/toml_migration/now show the user flow: editschema.toml, run bindgen/generator andmakemigrations, receive0001_initial.py, migrate, edit the TOML again, and receive a follow-up typed migration such as0002_add_email.py. - Real smoke coverage added โ integration coverage exercises TOML bindgen,
an initial typed migration, real data insertion, a typed optional-ownership
delta, an explicit
ops.RunTypeQLdata migration, and a failing migration path that remains unapplied while preserving prior data.
Rust runtime as the default Python execution backend¶
Database.connect()now opens the embedded Rust runtime by default โ the Python ORM no longer needs the optional externaltypedb-driverpackage for normal connection, schema, CRUD, query, migration, or database lifecycle operations.- Database lifecycle operations are Rust-backed โ
database_exists(),create_database(),delete_database(), and schema export use the same embedded Rust runtime path as query execution. - Direct Python driver access remains explicit โ
Database.driverstill opens the optional external Pythontypedb-driverand keeps its installed driver/server compatibility gate for callers that need direct driver APIs.
Dual-band TypeDB driver support: servers 3.8โ3.11 served by one artifact (#145)¶
- Both TypeDB Rust driver lines now embedded โ the wheel ships a vendored band-7 fork
(3.8.1) alongside the upstream band-8 driver (3.11.5). The runtime dispatches to the
correct driver at
Database.connect()time based on the server's protocol band; no user-side configuration is required. - TypeDB 3.11 newly supported โ band-8 (3.11.x) servers are now served in addition to the existing band-7 window.
- Existing 3.8/3.10 deployments keep working without change โ the band-7 embedded driver is a drop-in for the previous release line; upgrading type-bridge does not require a server upgrade.
- One release artifact covers TypeDB 3.8.0 through 3.11.x โ the per-band install
guidance is retired. Install
type-bridgeand connect to any server in the supported window. - CI proven on all three server lines โ
test-integration,node-integration, andcross-language-paritynow fan across 3.8.3, 3.10.4, and 3.11.5 (parity ร2). Theversion-gate-cellsjob retains only the true rejection cells (NEG-window, NEG-driver).
Cross-language CI and release coverage (#110)¶
- Node binding built, tested, and released โ the
@type-bridge/nodebinding is now built and gated in CI (native module, TypeScript surface, unit,.d.tsbaseline, and package smoke), runnable locally viascripts/check.sh node, and packaged as a tarball attached to each GitHub release (registry publish staged behind anNPM_TOKEN). - Cross-language parity enforced โ the Python/Node parity suite runs against live
TypeDB in CI under a strict mode that fails (rather than silently skips) when the
binding is unbuilt, so a semantic divergence between the two bindings reds CI; the
migrationintegration group is also covered. - Release hardening โ third-party GitHub Actions are pinned to commit SHAs, and a crates.io publish that fails for any reason other than an already-published version now fails the release instead of being swallowed.
- Node binding integration gated in CI โ a
node-integrationjob runs the binding's own live-TypeDB suites (test:integration, which chainstest:typed-integration) against a TypeDB service, mirroring the Python integration job. Previously only the offline Node gates and the Python-side parity suite ran; the binding's own integration assertions now red CI on a regression. - Consolidated test/check scripts โ
test.shis now the single full-test entrypoint (Rust + Python + Node, unit + integration) with--no-integration,--proxy, and--no-isolatedflags; it manages a TypeDB by default. Thetest-integration.sh,test-integration-dind.sh, andtest-proxy-integration.shscripts (and the Docker-in-Docker image stack) are retired into those flags, andscripts/check.shis the single canonical check (the redundant rootcheck.shis removed).
Generator parsing routed through the Rust core (#125)¶
larkremoved โ the generator no longer depends onlark. TQL schema parsing runs entirely through the Rusttype_bridge_corecore, which is the single source of the parsed schema. Thetypeql.larkgrammar and the lark-vs-Rust differential test have been deleted, andlarkis dropped from the runtime dependencies.- Structured function return types โ
FunctionSpec.return_typeis now a structuredReturnTypeSpec(ais_streamflag plus an ordered list ofReturnTypeItem(name, optional)) instead of a formatted string. Optionality is carried as a boolean, so the intermediate representation is language-neutral and additive for future bindings. Generated output is unchanged โ the renderer reconstructs any?tokens at its own emit site.
New Features¶
Plays-side role cardinality (#130)¶
- Cross-language plays-cardinality authoring โ Rust
SchemaInfo, PythonRole(..., plays_cardinality=Card(...)), TypeScriptrole(..., { playsCardinality: Card(...) }), and TOMLplays = [{ card = "..." }]now emitplays relation:role @card(...)through the shared Rust schema emitter/parser path. - Relates/plays separation โ relates-side
cardinalitystill constrains players per relation instance, while plays-side cardinality constrains how many relation instances a single player may participate in for that role. The two constraints may coexist on the same role. - Generated surface round-trip โ parsed TypeQL with plays-side
@cardrenders back to Python and TypeScript role declarations, preserving authoring/render parity.
TOML schema DSL (#138)¶
- TOML schema authoring โ schemas may now be authored in TOML as an
additive alternative to TypeQL. A new Rust/PyO3
toml_to_typeqltranspiles a TOML document to canonical TypeQL, which feeds the single existing parse path, so the intermediate representation, renderers, and generated packages are unchanged. Equivalent TOML and.tqlschemas produce byte-for-byte identical packages..tqlauthoring remains fully supported. - Full schema surface โ the DSL covers attributes (value types,
sub,abstract,@regex/@values/@range), entities (ownswith@key/@unique/@card,playswith optional per-plays@card,sub,abstract), relations (roleswith per-role@cardandassuper-role overrides,owns, relation-levelplays,sub,abstract), functions (signature plus verbatim body), and structs. - Generator routing โ
generate_modelstranspiles a.tomlsource by file suffix, or for raw text via an explicitformat="toml"argument. - Field-level diagnostics โ a semantic validation pass rejects malformed TOML
with a clear
ValueErrornaming the offending field or type (unknown value type,value/subconflict, danglingsubparent, missing role player, empty struct, malformed function body) before any TypeQL is emitted.
Node.js typed model layer (#124)¶
- Branded attributes โ
class Name extends attr.String("name") {}defines a hard-typed attribute whose class is nominally distinct from other attributes (Nameis not interchangeable withEmailor rawstring). One factory per TypeDB value type; the mandatory name is both the schema attribute name and the compile-time brand. - Typed
Entity/Relationclasses โclass Person extends Entity("person", { name: field(Name, Key), age: field(Age).optional() }) {}yields typed construction and field reads, mirroring the Python class surface. Relations support multi-playerrole(...)declarations. - Descriptor emission โ typed models emit registration descriptors byte-identical to the Python facade (verified against the shared parity fixture), so the same model definition drives the existing dynamic managers.
[1.4.5] - 2026-05-21¶
Bug Fixes¶
Python ORM¶
- Relation role-player hydration โ relation role players fetched as IID-only placeholders now hydrate correctly without requiring their own nested role players (#126).
- Optional relation roles โ
Relation.manager(...).all()/ fetch queries now include relations whose optional roles have no players (#127). - Optional role validation โ omitted optional roles normalize to
Noneinstead of leaking class-levelRoleRefdefaults, while required roles are still rejected when missing. - Role-player deduplication โ relation role players are deduplicated by IID when available, preserving distinct attribute-less relation players.
- TypeDB driver compatibility โ added
create_driver_options()helper and exported it fromtype_bridgeto support driver option construction across supported TypeDB driver APIs.
Rust Core / Server¶
- Raw TypeQL endpoint โ restored
POST /query/rawon the Rust server, parsing TypeQL text into clauses before running the existing query pipeline. - Server configuration โ TypeDB connection settings can now be overridden with
TYPEDB_ADDRESS,TYPEDB_DATABASE,TYPEDB_USERNAME, andTYPEDB_PASSWORD. - Clippy cleanup โ updated ORM role collection code to satisfy current Rust lints.
Compatibility¶
- Pinned TypeDB runtime โ Python dependency now pins
typedb-driver==3.10.0. - Python version bounds โ package metadata now declares
>=3.13,<3.15. - Integration environment โ Docker Compose defaults now use TypeDB 3.10.4 and expose a configurable
TYPEDB_PORT.
Testing & Tooling¶
- Pinned Docker-in-Docker integration runner โ added
Dockerfile.integration,docker-compose.dind.yml, andtest-integration-dind.shfor reproducible Python 3.13.5 + TypeDB 3.10.4 integration tests. - Added regression coverage for relation role-player hydration, optional relation fetches, raw proxy queries, and server environment overrides.
[1.4.4] - 2026-04-09¶
New Features¶
Cross-type attribute lookup (PR #117)¶
Entity.has / Relation.has / <Concrete>.has โ find all instances that own a
given attribute, optionally filtered by value or expression.
Python ORM โ type_bridge.crud.has_lookup¶
- Cross-type form โ
Entity.has(db, Name)returns mixed concrete subtypes across all entities owningName. - Concrete-class narrowing โ
HLPerson.has(db, Name)narrows to that type and its TypeDB subtypes viaisapolymorphism. Abstract base subclasses get subtype matching for free. - Role-player hydration โ relation results always include hydrated role players. Entity lookups remain single-query; relations are re-fetched per result through
concrete_class.manager(connection).get(_iid=iid). Attribute.get_owners()โ static discovery of attribute owners without a database connection, backed by a reverse_attribute_ownersindex inModelRegistry.
[1.4.3] - 2026-04-05¶
Bug Fixes¶
Rust Server โ type-bridge-server¶
- fix:
extract_crud_info()now reports the write-target type for Match + Insert/Put queries (#121)
Rust Core โ type-bridge-core-lib¶
- refactor: use idiomatic match guards in validation.rs
[1.4.2] - 2026-03-04¶
Rust Server โ type-bridge-server¶
CrudInfoonRequestContextโ operation, type_name, type_kind, attribute_names, iidCrudInterceptortrait withon_crud_request/on_crud_responseandshould_interceptCrudInterceptorAdapterbridgesCrudInterceptorinto the existingInterceptorchain
[1.4.1] - 2026-03-03¶
New Features¶
Lifecycle Hook System (PR #118, closes #116)¶
Three-layer hook system for reacting to CRUD lifecycle events (audit logging, validation, cache invalidation, async notifications).
Python ORM โ type_bridge.crud.hooks¶
CrudEventenum โPRE_INSERT,POST_INSERT,PRE_UPDATE,POST_UPDATE,PRE_DELETE,POST_DELETE,PRE_PUT,POST_PUTLifecycleHookprotocol โ implement only the methods you need (pre_insert,post_delete, etc.)HookCancelledexception โ raise in a pre-hook to abort the operation- Per-manager registration โ
manager.add_hook(hook)/manager.remove_hook(hook), chainable should_run(event, sender)filtering by event type or model class- Pre-hooks run in registration order; post-hooks run in reverse order (middleware unwinding)
- Zero overhead when no hooks are registered
Rust ORM โ type-bridge-orm¶
LifecycleHooktrait withHookContext,PreHookResult(Continue/Reject), andHookRunner- Integrated into
EntityManagerandRelationManagerviaadd_hook() - Same semantics as the Python layer (registration-order pre-hooks, reverse-order post-hooks)
Put (Upsert) Clause โ type-bridge-core-lib¶
- Added
Clause::Put(Vec<Statement>)variant for idempotent insert (upsert) operations - Parser:
parse_put_clausewith keyword lookahead in bothparse_patternsandparse_statements - Compiler: Generates
put\n<statements>;TypeQL output - Validation: Reuses Insert validation rules (
Clause::Insert | Clause::Put) - Full roundtrip support (parse โ AST โ compile โ parse)
Refactoring¶
Server API Simplification โ type-bridge-server¶
- Removed standalone CRUD module (
/entities/*,/relations/*endpoints,CrudQueryBuilder, raw query support) โ superseded by the interceptor-based design - Removed
crud_builderbenchmark andcriteriondev-dependency - Server now has 4 endpoints:
POST /query,POST /query/validate,GET /health,GET /schema
[1.4.0] - 2026-02-20¶
Highlights¶
- 5 new Rust crates:
core-lib,orm,orm-derive,server, andpython(PyO3 bindings) - Up to 40x faster validation and 2.5x faster query compilation via the Rust backend
- Async Rust ORM with derive macros, chainable queries, and batch operations
- Query-intercepting proxy server with REST endpoints
- MkDocs Material documentation site
New Features¶
Rust Core โ type-bridge-core-lib (PRs #95, #101-#108)¶
- TypeQL schema parser with inheritance resolution and PyO3 bindings
- TypeQL query parser with bidirectional AST roundtrip
- Schema-aware query validation with statement and pattern validators
- Rust-backed value coercion and
format_value - Custom validation rules with portable JSON DSL
- Wired Rust core into Python compiler and validation pipeline
Async Rust ORM โ type-bridge-orm (PR #114)¶
- Async ORM with entity CRUD and mock-testable session layer
- Derive macros โ
#[derive(TypeBridgeEntity)],#[derive(TypeBridgeRelation)],#[derive(TypeBridgeAttribute)] - Chainable query builders with expression filtering and aggregation
- Schema management โ registration, generation, diff, and sync
- Abstract types with inheritance and code generation
- Batch operations โ
insert_many,delete_many,update_many FieldRef<A>for type-safe query field referencesinclude_schema!proc-macro for compile-time TQL codegen- Schema introspection from live TypeDB database
- Group-by queries with
GroupByResult - Role player field access for relation query filtering
- Expression helpers โ
in_range(),startswith(),endswith() - Connection pooling with
Database::into_shared() - Serde support on all ORM model types
- Structured tracing spans on all public methods
Query Intercept Proxy โ type-bridge-server (PR #109)¶
- REST CRUD endpoints with schema-aware query building
CrudQueryBuilderPyO3 class for TypeQL generation from Python- Extensible library/framework โ pluggable
QueryExecutor,Interceptor,SchemaSource - 207 tests with 100% MC/DC coverage
Performance: Python vs Rust¶
Validation¶
| Operation | Python | Rust | Speedup |
|---|---|---|---|
| Single type name | 1.89 us | 354.75 ns | 5.3x |
| Long name (100+ chars) | 24.90 us | 620.52 ns | 40.1x |
| Batch 1,000 names | 5.32 ms | 266.80 us | 19.9x |
| Batch 5,000 names | 28.02 ms | 1.33 ms | 21.1x |
Query Compilation (via serde bridge)¶
| Operation | Python | Rust | Speedup |
|---|---|---|---|
| Standalone update | 93.28 us | 37.82 us | 2.5x |
| Large batch (200 clauses) | 2.26 ms | 1.07 ms | 2.1x |
| Heavy insert (100x6) | 1.71 ms | 896.19 us | 1.9x |
Documentation & CI¶
- MkDocs + Material documentation site with auto-generated API reference (PR #98)
- Rust crate CI with multi-platform wheel builds โ Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64) (PR #95)
- Comprehensive benchmark suite with TOML storage, comparison reports, and markdown generation (PR #103)
- Codecov integration for Rust coverage tracking (PR #109)
Bug Fixes¶
- Resolve Rust 1.93.0 clippy lint errors
- Pin Python 3.13 for Rust CI jobs and fix coverage script
- Add version specifiers to inter-crate path dependencies for crates.io publishing
- Make release workflow idempotent (skip already-published packages)
[1.3.0] - 2026-02-09¶
New Features¶
API DTO Generator (PRs #96, #97, #99, #100)¶
- Pydantic DTO generation from TypeQL schemas โ Generate typed Create/Out/Patch DTOs directly from parsed schemas
- Composite DTOs โ
CompositeEntityConfigfor flat/merged DTOs across entity types with name clash validation - Per-variant field requiredness overrides โ
FieldOverrideandEntityFieldOverrideto control field requiredness per DTO variant (Create, Out, Patch) skip_variantsโ Skip generating specific variant classes while keeping the type Literal enumextra_fields_outโ Per-variant override for extra fields on Out DTOsstrict_out_modelsโ Flag for required fields in Out DTOs- Reusable Jinja macros โ Refactored templates into
_dto_macros.jinja - CLI support โ
python -m type_bridge.generatornow supports DTO generation
Date Arithmetic and Query-Level Arithmetic Expressions¶
- Date arithmetic โ
__add__,__radd__,__sub__onDatefor Duration arithmetic, matching DateTime/DateTimeTZ - ArithmeticExpr โ New expression class with helpers (
add,sub,mul,div,mod,pow_) for TypeQL infix operators - ArithmeticValue AST node and compiler support
Improvements¶
- TypeDB 3.8.0 stable โ Bumped from 3.8.0-rc0 to 3.8.0 release
- TypeDB driver 3.8.0 โ Upgraded
typedb-driverdependency to 3.8.0 - Expression module cleanup โ Improved handling across boolean, comparison, and string expression modules
- Field module cleanup โ Enhanced field handling in base and role modules
Housekeeping¶
- Applied ruff formatting to all test files
- Added
.coverageto.gitignore(was accidentally tracked)
[1.2.7] - 2026-02-03¶
New Features¶
TypeDB 3.8.0 Support (PR #93)¶
- Full compatibility with TypeDB 3.8.0
- Updated driver integration
Performance Improvements¶
Batch Operations Optimization¶
- Batch delete operations with disjunctive IID matching
- Batch entity inserts/puts into single query
- Optimized IID retrieval with single-query insert+fetch
Bug Fixes¶
- HydrationError handling - Raise HydrationError instead of silently swallowing exceptions
- Variable collision prevention - Use double underscore separator to prevent variable collisions
- TypeDB 3.x relation syntax - Use correct relation insert syntax with
linkskeyword - Multi-variable let fix - Remove incorrect parentheses in multi-variable let assignment
- Polymorphic attributes - Restore polymorphic attribute fetching with nested wildcard
Refactoring¶
- Consolidate duplicated code and fix Python 3.13 warnings
- Unify entity identification logic across managers
- Extract shared attribute-to-AST logic into TypeDBType
- Remove
.caccessor for direct field access
Code Quality¶
- Remove all
type: ignorecomments for full type safety
Testing¶
- Add recursive relation tests
- Add validation performance benchmarks
[1.2.6] - 2026-02-01¶
New Features¶
Polymorphic Role Player Type Resolution (PR #92)¶
- Role players now resolve to their concrete Python types
- When querying relations with abstract role types, role players are resolved to concrete types (e.g.,
Personinstead ofProfile) - Uses TypeQL
label()function to fetch type labels and resolve to correct Python class - Location:
type_bridge/crud/relation/manager.py
Relations as Role Players¶
- Fixed hydration for relations serving as role players
- Relations can now properly participate as role players in other relations
- Comprehensive test suites added for this pattern
- Location:
type_bridge/crud/relation/manager.py
Improvements¶
Modular Helper Methods (PR #92)¶
- Extracted reusable helper methods for DRY refactoring
_resolve_entity_class_from_label()- Resolves concrete types using TypeQLlabel()function_hydrate_entity_from_data()- Helper for role player instantiation- Eliminates duplicate code in
get()andget_by_iid()methods
Generator Enhancements (PR #92)¶
- Improved code generation for relations
- Role cardinality annotations now properly rendered
- Docstrings and type annotations rendering improvements
- Location:
type_bridge/generator/
Bug Fixes¶
Polymorphic Role Validation (PR #92)¶
- Fixed polymorphic role validation and role player IIDs
- Correct handling of abstract types in role player resolution
- Fixed role player IID extraction in polymorphic queries
Test Fixes (PR #92)¶
- Fixed
manager.count()โmanager.filter().count()in tests - Renamed attribute types to avoid naming collisions
Testing¶
- 19 new integration tests (
tests/integration/queries/test_social_network_queries.py) - Deep inheritance (3-level: Entity โ Profile โ Person/Organization)
- Self-referential symmetric relations (Friendship)
- Geographic hierarchy chains (Person โ City โ Country)
- Polymorphic role players with concrete type verification
- Multi-value attributes with
@card(0..*) - Chained relations and complex filter combinations
Key Files Modified¶
type_bridge/crud/relation/manager.py- Polymorphic role player resolutiontype_bridge/generator/render/- Role cardinality and annotations renderingtests/integration/queries/test_social_network_queries.py- New comprehensive tests
[1.2.5] - 2026-01-31¶
New Features¶
IID-preferring Role Player Matching (PR #91)¶
- RelationManager now prefers IID for role player matching
- Uses IID for precise matching when available
- Falls back to key attribute matching when IID not set
- Raises clear
ValueErrorwhen neither IID nor key attributes available - Location:
type_bridge/crud/relation/manager.py
Affected Methods: insert(), put(), update(), delete() and *_many variants
Documentation¶
- Updated role player matching docs in
docs/SKILL.mdanddocs/api/crud.md
[1.2.4] - 2026-01-30¶
New Features¶
TypeDB 3.8.0 Built-in Functions (PR #88)¶
- Added support for TypeDB 3.8.0 built-in functions
- Identity functions:
iid(),label() - Math functions:
abs_(),ceil(),floor(),round_() - Collection functions:
len_(),max_(),min_() - Location:
type_bridge/expressions/builtins.py
Usage Example:
from type_bridge.expressions import iid, label, abs_, ceil, floor
# Get entity IID
query = Person.manager(db).filter(iid() == "0x1a2b3c").execute()
# Use math functions
query = Person.manager(db).filter(abs_(Age.value) > 18).execute()
Unicode XID Identifier Validation (PR #88)¶
- Added Unicode identifier validation for TypeDB 3.8.0 compatibility
- Validates identifiers follow Unicode XID_Start/XID_Continue rules
- Ensures TypeQL identifiers are compatible with TypeDB 3.8.0
- Clear error messages for invalid identifiers
- Location:
type_bridge/validation.py
Bug Fixes¶
Value Extraction Fix (PR #88)¶
- Fixed value extraction for
_Valueconcepts - Changed from
.as_value()to.get()for proper value extraction - Fixes issues with function return values and aggregations
- Location:
type_bridge/session.py
Driver Initialization Warning Fix (PR #88)¶
- Fixed "Failed to initialize logging" warning
- Suppresses fd 2 (stderr) during TypeDB driver initialization
- Eliminates spurious warning messages on startup
- Location:
type_bridge/typedb_driver.py
Documentation¶
- Added AI Assistant Skill Documentation (
docs/SKILL.md) - Guidelines for using TypeBridge with AI code assistants
Testing¶
- 32 new unit tests for builtin expressions
- 7 new integration tests for
iid()andlabel()functions - All existing tests pass with TypeDB 3.8.0-rc0
- Fixed hardcoded port 1729 in tests to use TEST_DB_ADDRESS
CI/CD¶
- Updated CI to TypeDB 3.8.0-rc0
- All tests now run against TypeDB 3.8.0-rc0
Key Files Modified¶
type_bridge/expressions/builtins.py- New built-in function expressionstype_bridge/session.py- Value extraction fixtype_bridge/typedb_driver.py- Driver initialization fixtype_bridge/validation.py- Unicode identifier validationdocs/SKILL.md- New AI assistant documentation
[1.2.3] - 2025-12-28¶
New Features¶
Enhanced FunctionQuery System (PR #84)¶
- Complete TypeQL query generation for function calls
- FunctionQuery generates full
match letqueries with variable binding - Support for scalar returns, stream returns, and composite tuples
- Query methods:
to_call(),to_match_let(),to_fetch(),to_query() - Pagination support with limit/offset/sort
- Location:
type_bridge/expressions/functions.py
Usage Example:
from myschema.functions import count_artifacts, get_neighbor_ids
# Simple count
fn = count_artifacts()
query = fn.to_query()
# โ match let $integer = count-artifacts(); fetch { "integer": $integer };
# Stream with pagination
fn = get_neighbor_ids(target_id="abc-123")
query = fn.to_query(limit=10, offset=5)
Driver Injection Support (PR #86)¶
- Share TypeDB driver instances across Database objects
- Optional
driverparameter inDatabase.__init__() - Ownership tracking with
_owns_driverflag for lifecycle control - Enables connection pooling and framework integration
- Location:
type_bridge/session.py
Benefits: - Resource efficiency (share one TCP connection) - Application-level connection pooling strategies - Centralized driver lifecycle management - Backwards compatible (default behavior unchanged)
Usage Example:
driver = TypeDB.driver("localhost:1729", Credentials("admin", "password"))
db1 = Database(database="project_a", driver=driver) # Shares driver
db2 = Database(database="project_b", driver=driver) # Shares driver
db1.close() # Just clears reference
db2.close() # Just clears reference
driver.close() # Actually closes connection
@independent Annotation Support (PR #83)¶
- Standalone attributes without entity/relation owners
- Add
independent = TrueClassVar to attribute classes - Generates
@independentannotation in TypeQL schema - Enables standalone attribute insertion and queries
- Location:
type_bridge/attribute/base.py
Usage Example:
class Language(String):
"""Can exist without an owner."""
independent = True
# Generated TypeQL: attribute Language @independent, value string;
@range Validation and Schema Generation (PR #82)¶
- Runtime validation with database enforcement
IntegerandDoublevalidaterange_constraintClassVar at initialization- Schema generation includes
@range(min..max)annotations - Also generates
@regexand@valuesannotations from ClassVars - Two-layer validation: Python-side (fail-fast) + TypeDB-side (enforcement)
- Location:
type_bridge/attribute/integer.py,type_bridge/attribute/double.py
Usage Example:
from typing import ClassVar
class Age(Integer):
range_constraint: ClassVar[tuple[str | None, str | None]] = ("0", "150")
Age(200) # Raises: ValueError: Age value 200 is above maximum 150
# Generated schema: attribute Age, value integer @range(0..150);
Batch IID Filtering (PR #81)¶
- Django-style
iid__inlookup for efficient batch queries - Filter entities/relations by multiple IIDs in single query
- Role player filtering:
employee__iid__in=[...] - Uses flat BooleanExpr to avoid stack overflow with many IIDs
- Location:
type_bridge/expressions/iid.py,type_bridge/crud/entity/manager.py
Usage Example:
# Fetch multiple entities by IID
persons = Person.manager(db).filter(iid__in=["0x1a2b3c", "0x4d5e6f"]).execute()
# Filter relations by role player IIDs
employments = Employment.manager(db).filter(employee__iid__in=["0x1a2b3c"]).execute()
Performance: O(1) query vs O(N) get_by_iid() calls.
TypeQL Annotation Validation (PR #86)¶
- Comprehensive validation for schema annotations
@card: Validates min โค max, non-negative values, detects comma syntax@regex: Validates patterns compile as valid regex@values: Validates at least one value, detects duplicates@range: Validates proper..syntax, rejects comma/single-value- Clear, actionable error messages
- Location:
type_bridge/generator/parser.py
Bug Fixes¶
Code Generator Fixes (PR #86)¶
- Fixed relation inheritance to include keys, uniques, and cardinalities
- Child relations now inherit
@key,@unique, and@cardfrom parent - Ensures complete type definitions in generated code
-
Location:
type_bridge/generator/render/relations.py -
Fixed optional relation attributes in generated models
- Correct type hints with
| Nonefor optional fields - Proper default values (e.g.,
timestamp: Timestamp | None = None) - Respects cardinality:
@card(1)= required, no annotation = optional -
Location:
type_bridge/generator/render/relations.py -
Fixed Python literal rendering for @range annotations
- Range values output as numeric literals:
(1, None)not("1", null) - Fixed type hint from
str | Nonetoint | float | None - Location:
type_bridge/generator/render/attributes.py
Query Generation Fixes (PR #84)¶
- Fixed composite variable lists in FunctionQuery
- Removed incorrect parentheses around variable lists
- Correct:
match let $a, $b in func() - Incorrect (previous):
match let ($a, $b) in func() - Location:
type_bridge/expressions/functions.py
Type Checking Fixes¶
- Proper type annotations for ty type checker
- Use
type[Attribute]instead of generic type - Use
type[Entity] | type[Relation]for model params - Core library passes ty with zero warnings
-
Location:
type_bridge/crud/relation/lookup.py,type_bridge/schema/introspection.py -
Added None checks for optional attributes
assert position is not Noneguards before accessing.value- Fixes pyright errors in tests
- Location:
tests/integration/crud/test_iid_feature.py
Development & Tooling¶
Project Restructuring¶
- Moved Python package to repository root
- Transitioned from monorepo (
packages/python/) to root-level package - TypeScript split into separate type-bridge-ts repository
- Simplified CI/CD configuration
Pre-commit Hooks¶
- Comprehensive code quality automation
- ruff linting and formatting
- pyright type checking
- ty type checker for enhanced type safety
- Location:
.pre-commit-config.yaml
Type Checker Configuration¶
- Configured ty rules for metaclass compatibility
- Overrides for tests/examples to handle metaclass-generated code
- Rules: unknown-argument, unresolved-attribute, call-non-callable
- Location:
pyproject.toml[tool.ty.overrides]
Documentation¶
- FunctionQuery documentation and integration tests
- Comprehensive examples of query generation patterns
-
All function patterns tested (scalar, stream, composite)
-
Database driver injection guide
- Connection pooling examples
-
Framework integration patterns
-
Generator relation cardinality documentation
- Clarified
@cardbehavior on relation attributes - Required vs optional attribute patterns
Testing¶
- 1096 unit tests passing (100% pass rate)
- All integration tests passing
- 0 errors with pyright and ty type checkers
Key Files Modified¶
type_bridge/expressions/functions.py- Enhanced FunctionQuerytype_bridge/session.py- Driver injection supporttype_bridge/generator/parser.py- Annotation validationtype_bridge/generator/render/relations.py- Inheritance and optional attributestype_bridge/generator/render/attributes.py- Python literal renderingtype_bridge/crud/relation/lookup.py- Type annotationstype_bridge/schema/introspection.py- Type annotationstype_bridge/attribute/base.py- @independent supporttype_bridge/attribute/integer.py- @range validationtype_bridge/attribute/double.py- @range validation.pre-commit-config.yaml- Pre-commit hooks configurationpyproject.toml- ty type checker configuration
[1.2.2] - 2025-12-25¶
Bug Fixes¶
RelationManager IID Correlation Fix (Issue #78)¶
- Fixed incorrect IID assignment in RelationManager.all()
- Problem: All relations were getting the same IID values for their role players instead of unique IIDs for each relation
- Root cause:
_populate_iidsmethod didn't properly correlate query results to the correct relation instances - Solution: Capture key attribute values as variables in the query and build a lookup map for correlating results back to the correct relations
- Impact: Critical for code relying on role player
_iidvalues for deduplication or correlation - Example: Multiple friendships now correctly show unique IIDs for each person instead of all showing the same IIDs
- Location:
type_bridge/session.py,type_bridge/crud/relation/manager.py
Testing¶
- Added 133 lines of regression tests for Issue #78
- Verifies multiple relations each get their own unique IIDs
Key Files Modified¶
type_bridge/session.py- Added value extraction for attribute concepts in_extract_concept_rowtype_bridge/crud/relation/manager.py- Fixed IID correlation logic (198 additions, 134 deletions)tests/integration/crud/test_iid_feature.py- Added regression tests for Issue #78
[1.2.1] - 2025-12-25¶
Bug Fixes¶
Stack Overflow Fix for __in Lookup (Issue #76)¶
- Fixed TypeDB stack overflow when using
__inlookup with many values (75+) - Root cause: Deeply nested binary OR expressions
((((a or b) or c) or d)...)caused TypeDB query planner to stack overflow - Solution: Use flat BooleanExpr structure for OR operations
- Example:
manager.filter(name__in=["Alice", "Bob", ...150 names])now works reliably - Location:
type_bridge/crud/entity/manager.py,type_bridge/crud/relation/lookup.py,type_bridge/expressions/boolean.py - Added automatic flattening of BooleanExpr operations
BooleanExpr.and_()andBooleanExpr.or_()now automatically flatten operands of the same operation type- Prevents deeply nested expression trees
- Improves query compilation performance
Testing¶
- Added 249 new tests for BooleanExpr flattening and __in lookup edge cases
- All tests passing
Key Files Modified¶
type_bridge/crud/entity/manager.py- Flat OR structure for __in lookupstype_bridge/crud/relation/lookup.py- Flat OR structure for relation lookupstype_bridge/expressions/boolean.py- Automatic flattening in and_() and or_()tests/unit/crud/test_lookup_parser.py- Entity lookup tests (37 tests)tests/unit/crud/test_role_lookup_parser.py- Relation lookup tests (31 tests)tests/unit/expressions/test_boolean_expr.py- BooleanExpr flattening tests (181 tests)
[1.2.0] - 2025-12-22¶
New Features¶
TypeDB 3.0 Structs Support (PR #71)¶
- Parse and generate Python code for TypeDB struct types
- Structs are value types composed of named fields
- Full code generator support for struct definitions
- Location:
type_bridge/generator/
Additional Annotations Support (PR #71)¶
@rangeannotation rendering in code generator- Support for
@range(min..max)constraints on attributes - Renders as validation metadata in generated code
Role Player IIDs (PR #70)¶
- Populate IIDs on role player entities when fetching relations
- Role players now have their
_iidfield populated automatically - Enables direct IID-based lookups on role players
Generator CLI Enhancement (PR #70)¶
- New
--schema-pathCLI option for code generator - Specify custom path for schema file in generated output
Batch Delete Error Handling¶
strictparameter fordelete_many- Optional error handling for batch deletes- When
strict=True, raises error if any entity not found - When
strict=False(default), silently skips missing entities
Performance Improvements¶
Batch Query Optimizations (PR #75)¶
- 50-100x improvement for bulk operations
- Batch
update_withoperations to reduce round-trips - Batch
_populate_iidsfor efficient IID resolution - Significant performance gains for large datasets
N+1 Query Fix (PR #73)¶
- Fix N+1 query problem in entity IID/type resolution
- Previously: 1 query per entity for IID resolution
- Now: Single batched query for all entities
- Major performance improvement for
all()andfilter().execute()
Batched CRUD Operations¶
- Batched
update_manyanddelete_manyoperations - Efficient batch processing instead of per-entity queries
- Reduced database round-trips
Bug Fixes¶
- None check in
delete_many- Add None check for entity in batched delete query to prevent errors when entity list contains None values
Key Files Modified¶
type_bridge/generator/parser.py- Struct parsing supporttype_bridge/generator/render/- Struct code generationtype_bridge/generator/__main__.py---schema-pathCLI optiontype_bridge/crud/entity/manager.py- Batch operations, strict parametertype_bridge/crud/entity/query.py- Batch IID populationtype_bridge/crud/relation/manager.py- Role player IID population
[1.1.0] - 2025-12-19¶
New Features¶
Polymorphic Entity Instantiation¶
- Querying a supertype now returns proper subtype instances (Issue #65)
Artifact.manager(db).all()returns a mix ofUserStory,DesignAspect, etc.- Each entity has the correct Python type with all subtype-specific attributes populated
- IIDs and type information correctly extracted for each subtype
Usage Example:
# Define type hierarchy
class Artifact(Entity):
flags = TypeFlags(abstract=True)
name: Name = Flag(Key)
class UserStory(Artifact):
story_points: StoryPoints
class DesignAspect(Artifact):
priority: Priority
# Query supertype - get proper subtypes back
artifacts = Artifact.manager(db).all()
for artifact in artifacts:
print(type(artifact)) # UserStory, DesignAspect, etc.
print(artifact.name) # All have base attributes
if isinstance(artifact, UserStory):
print(artifact.story_points) # Subtype-specific attributes
Refactoring¶
Jinja2 Templates for Code Generation¶
- Code generator now uses Jinja2 templates instead of string concatenation
- 6 new templates: attributes, entities, relations, functions, package_init, registry
- Significant code reduction in render modules:
registry.py: 578 โ 156 lines (-422)package.py: 116 โ 61 lines (-55)entities.py: 234 โ 198 lines (-36)
Typer CLI¶
- Generator and migration CLIs migrated to Typer
- Improved help messages and command structure
- Better argument parsing and validation
Dependencies¶
- Added
jinja2>=3.1.0- Template engine for code generation - Added
typer>=0.15.0- CLI framework for generator and migration tools
Key Files Modified¶
type_bridge/crud/entity/manager.py- Polymorphic instantiation inget()type_bridge/crud/entity/query.py- Polymorphic instantiation inexecute()type_bridge/crud/utils.py-resolve_entity_class()utilitytype_bridge/generator/__main__.py- Typer CLItype_bridge/generator/render/- Jinja2 template integrationtype_bridge/generator/templates/- 6 new Jinja2 templatestype_bridge/migration/__main__.py- Typer CLI with subcommands
[1.0.1] - 2025-12-19¶
New Features¶
TypeDB IID Support¶
- Expose TypeDB Internal ID (IID) on entity and relation instances
_iidfield automatically populated when entities/relations are fetched from database- New
get_by_iid(iid: str)method on EntityManager and RelationManager - IID populated from
get(),filter().execute(), andall()operations
Usage Example:
# Insert entity
person = Person(name=Name("Alice"), age=Age(30))
Person.manager(db).insert(person)
# Fetch - IID is automatically populated
fetched = Person.manager(db).get(name="Alice")
print(fetched[0]._iid) # '0x1e00000000000000000000'
# Direct IID lookup
person = Person.manager(db).get_by_iid("0x1e00000000000000000000")
Bug Fixes¶
- Fixed relation IID assignment order - Set
_iidafter role player assignments to prevent Pydantic revalidation from resetting the value
Key Files Modified¶
type_bridge/session.py- IID extraction functionstype_bridge/crud/entity/manager.py-get_by_iid()methodtype_bridge/crud/entity/query.py- IID extraction from resultstype_bridge/crud/relation/manager.py-get_by_iid()methodtype_bridge/crud/relation/query.py- IID extraction from results
[1.0.0] - 2025-12-15¶
New Features¶
Django-style Migration System¶
- Complete migration framework for TypeDB schema evolution
- Auto-generate migrations from Python model changes
- Apply and rollback migrations with transaction safety
- Track migration state in TypeDB database
- CLI commands:
type-bridge makemigrations,type-bridge migrate -
Location:
type_bridge/migration/(2872 lines) -
Migration Operations
AddAttribute- Add new attribute typesAddEntity- Add new entity typesAddRelation- Add new relation types with rolesAddOwnership- Add attribute ownership to typesAddRolePlayer- Add role players to relationsRemoveAttribute,RemoveEntity,RemoveRelation- Remove typesRunTypeQL- Execute raw TypeQL for custom migrations- All operations support forward and rollback
-
Location:
type_bridge/migration/operations.py -
Migration Generator
- Auto-detect schema changes by comparing Python models to database
- Generate migration files with operations
- Support for incremental migrations (detect only changes)
-
Location:
type_bridge/migration/generator.py -
Migration Executor
- Apply pending migrations in order
- Rollback migrations in reverse order
- Dry-run mode for previewing changes
sqlmigratefor viewing generated TypeQL-
Location:
type_bridge/migration/executor.py -
Migration State Tracking
- Track applied migrations in TypeDB
-
Location:
type_bridge/migration/state.py -
Model Registry
- Register models for migration tracking
- Auto-discover models from modules
- Location:
type_bridge/migration/registry.py
Schema Introspection¶
- Query existing schema from TypeDB database
- Introspect entities, relations, attributes, and ownerships
- TypeDB 3.x compatible queries
- Model-aware introspection for efficient checking
- Location:
type_bridge/schema/introspection.py(527 lines)
Breaking Change Detection¶
- Analyze schema changes for safety
- Detect breaking vs safe changes
- Categories: BREAKING, SAFE, WARNING
- Check role player narrowing, type removal, etc.
- Location:
type_bridge/schema/breaking.py(411 lines)
Enhanced Schema Diff¶
- Improved schema comparison
- Compare by TypeDB type name instead of Python object identity
- Detect modified entities, relations, and role players
- Track attribute and ownership changes
- Location:
type_bridge/schema/info.py,type_bridge/schema/diff.py
Bug Fixes¶
TypeDB 3.x Compatibility¶
- Fixed schema comparison using Python object identity instead of type name
-
SchemaInfo.compare()now correctly matches entities/relations by type name -
Fixed migration executor to execute operations separately
-
TypeDB 3.x doesn't allow multiple
defineblocks in single query -
Fixed schema introspection to query ownership from schema definition
-
Uses
match {type_name} owns $a;for schema queries -
Fixed migration state tracking for TypeDB 3.x @key semantics
- Uses composite key (
migration_id) instead of dual@keyattributes
Testing¶
- All 391 integration tests passing
- Added comprehensive migration test suite
- Added role player diff tests
- Added schema introspection tests
Key Files Added¶
type_bridge/migration/__init__.py- Migration module exportstype_bridge/migration/__main__.py- CLI commandstype_bridge/migration/base.py- Migration base classtype_bridge/migration/operations.py- Migration operationstype_bridge/migration/generator.py- Auto-generationtype_bridge/migration/executor.py- Apply/rollbacktype_bridge/migration/loader.py- Load migration filestype_bridge/migration/state.py- State trackingtype_bridge/migration/registry.py- Model registrytype_bridge/schema/introspection.py- Schema introspectiontype_bridge/schema/breaking.py- Breaking change detectiontests/integration/migration/- Migration integration teststests/integration/schema/test_role_player_diff.py- Role player tests
Usage Example¶
from type_bridge.migration import MigrationGenerator, MigrationExecutor
from type_bridge import Database
db = Database("localhost:1729", "mydb")
# Generate migration from models
generator = MigrationGenerator(db, "./migrations")
generator.generate(models=[Person, Company], name="initial")
# Apply migrations
executor = MigrationExecutor(db, "./migrations")
results = executor.migrate()
# Rollback
executor.rollback()
CLI Usage¶
# Generate migrations
type-bridge makemigrations ./migrations --models myapp.models
# Apply migrations
type-bridge migrate ./migrations
# Show migration status
type-bridge showmigrations ./migrations
# Preview TypeQL
type-bridge sqlmigrate ./migrations 0001_initial
[0.9.4] - 2025-12-12¶
New Features¶
Debug Logging Support (Issue #43)¶
- Added comprehensive logging throughout TypeBridge using Python's standard
loggingmodule - See generated TQL queries during CRUD operations
- Hierarchical logger structure for fine-grained control
- Documentation:
docs/api/logging.md
Bug Fixes¶
Type Safety Improvements¶
- Fixed pyright errors for
TransactionType.nameaccess in session.py - Added
_tx_type_name()helper function for type-safe transaction type logging
Documentation¶
- Added
docs/api/logging.md- Comprehensive logging configuration guide - Updated
docs/DEVELOPMENT.mdwith logging section
Key Files Modified¶
type_bridge/session.py- Fixed type errors, added loggingtype_bridge/query.py- Added loggingtype_bridge/validation.py- Added loggingtype_bridge/schema/manager.py- Added loggingtype_bridge/schema/migration.py- Added loggingtype_bridge/crud/entity/manager.py- Added loggingtype_bridge/crud/entity/query.py- Added loggingtype_bridge/crud/entity/group_by.py- Added loggingtype_bridge/crud/relation/manager.py- Added loggingtype_bridge/crud/relation/query.py- Added loggingtype_bridge/crud/relation/group_by.py- Added loggingtype_bridge/generator/__main__.py- Added loggingtype_bridge/generator/render/attributes.py- Added loggingtype_bridge/generator/render/entities.py- Added loggingtype_bridge/generator/render/relations.py- Added loggingtype_bridge/models/entity.py- Added loggingtype_bridge/models/relation.py- Added loggingdocs/api/logging.md- New documentationdocs/DEVELOPMENT.md- Added logging section
[0.9.3] - 2025-12-12¶
Documentation¶
@key Attribute Requirement for update() (Issue #45)¶
- Added prominent documentation explaining that
update()requires @key attributes - New section "Important: @key Attributes Required for update()" in CRUD docs
- Clear examples showing proper
@keyattribute definition - Error scenarios documented: no
@keydefined,@keyvalue isNone - Guidance for UUID/ID fields as
@keyattributes - Cross-reference to Exception Handling section
- Location:
docs/api/crud.md(lines 369-413)
Key Files Modified¶
docs/api/crud.md- Added @key requirement documentation in Update Operations section
[0.9.2] - 2025-12-12¶
New Features¶
KeyAttributeError Exception (Issue #44)¶
- Added
KeyAttributeErrorexception for @key validation failures - Raised when @key attribute is None during update/delete
- Raised when no @key attributes are defined on entity
- Structured attributes:
entity_type,operation,field_name,all_fields - Helpful error messages with hints for fixing issues
- Inherits from
ValueErrorfor backward compatibility - Location:
type_bridge/crud/exceptions.py
Testing¶
- Added 7 unit tests for
KeyAttributeError - 813 unit tests passing
Key Files Added/Modified¶
type_bridge/crud/exceptions.py- AddedKeyAttributeErrorclasstype_bridge/crud/__init__.py- ExportKeyAttributeErrortype_bridge/__init__.py- ExportKeyAttributeErrorin public APItype_bridge/crud/entity/manager.py- UseKeyAttributeErrortype_bridge/crud/entity/query.py- UseKeyAttributeErrortests/unit/exceptions/test_exceptions.py- Added KeyAttributeError tests
Usage Example¶
from type_bridge import KeyAttributeError
try:
manager.update(entity_with_none_key)
except KeyAttributeError as e:
print(f"Entity: {e.entity_type}")
print(f"Operation: {e.operation}")
print(f"Field: {e.field_name}")
[0.9.1] - 2025-12-11¶
New Features¶
Enhanced Code Generator (PR #53)¶
- Registry Module - Generates
registry.pywith schema metadata as Python dictionaries - Entity/relation attributes, roles, and inheritance info
- JSON Schema fragments for validation
- Convenience lookup functions
- Schema hash for change detection
-
Location:
type_bridge/generator/render/registry.py -
Enhanced Function Generation - Generic
FunctionCallExpr[T]with precise return type hints - Support for all TypeDB function variations: stream, scalar, tuple, optional returns
- Added
boolto type mapping - Improved docstrings with return type documentation
-
Location:
type_bridge/generator/render/functions.py -
TypeQL Parser Enhancements
@independentattribute flag support@range(min..max)constraint parsing (integers, floats, dates, datetimes, open-ended)@cardonplaysdeclarations with inheritance@cardonrelatesdeclarations//C-style comments alongside#comments- Comment annotations parsing (
@prefix,@tags, etc.) - Location:
type_bridge/generator/parser.py,type_bridge/generator/typeql.lark
Testing¶
- Added comprehensive generator unit tests for annotations, functions, and registry
- 1,268 total tests passing
Key Files Added/Modified¶
type_bridge/generator/render/registry.py- Registry module generation (new)type_bridge/generator/annotations.py- Annotation parsing (new)type_bridge/generator/render/functions.py- Enhanced function generationtype_bridge/generator/parser.py- Parser enhancementstype_bridge/generator/typeql.lark- Grammar updatestype_bridge/generator/models.py- New annotation modelstype_bridge/expressions/functions.py- Generic FunctionCallExprdocs/api/generator.md- Updated documentation
Contributors¶
- @CaliLuke - Generator enhancements
[0.9.0] - 2025-12-11¶
New Features¶
Type-Safe Role Player Expressions (PR #42)¶
- Type-safe role player field expressions
- Access role player attributes with type safety:
Employment.employee.age.gte(Age(30)) RoleRefclass for class-level role accessRolePlayerFieldReffor type-safe attribute accessRolePlayerNumericFieldReffor numeric comparison methodsRolePlayerStringFieldReffor string-specific methods (contains, like, regex)-
Location:
type_bridge/fields/role.py -
Django-style role-player lookup filters
- Filter by role player attributes:
filter(employee__age__gt=30) - Support for comparison operators:
__eq,__gt,__lt,__gte,__lte - Support for string operators:
__contains,__like,__regex -
Location:
type_bridge/crud/relation/lookup.py -
Added
order_by()method to EntityQuery and RelationQuery - Sort results by entity/relation attributes or role player attributes
- Supports ascending (default) and descending (
-field) order - Role-player sorting:
order_by('employee__age', '-salary') -
Location:
type_bridge/crud/entity/query.py,type_bridge/crud/relation/query.py -
Added public
Relation.get_roles()method - Clean API for accessing relation roles without internal
_rolesaccess - Returns:
dict[str, Role]mapping role names to Role instances - Location:
type_bridge/models/relation.py
Bug Fixes¶
- Fixed
RelationQuery.filter()to support Django-style kwargs - Chained
.filter()calls now properly support**filtersparameter - Location:
type_bridge/crud/relation/query.py
Testing¶
- Added
TestCombinedWithPaginationintegration tests - Added
TestRoleMultiAttributeAccessunit tests - All type checks pass without suppressions (uses
isinstancefor type narrowing) - 806 unit tests + 377 integration tests = 1,183 total tests
Key Files Added/Modified¶
type_bridge/fields/role.py- RoleRef and RolePlayerFieldRef classestype_bridge/crud/relation/lookup.py- Django-style lookup parsertype_bridge/crud/relation/query.py- RelationQuery with filter and order_bytype_bridge/crud/entity/query.py- EntityQuery with order_bytype_bridge/models/relation.py- Added get_roles() methodtype_bridge/generator/render/relations.py- Updated generated code patternstests/unit/fields/test_role_ref.py- RoleRef unit teststests/integration/queries/test_role_field_expressions.py- Integration tests
Usage Examples¶
from type_bridge import Relation, Role, Entity, TypeFlags, String, Integer
class Age(Integer):
pass
class Name(String):
pass
class Person(Entity):
flags = TypeFlags(name="person")
name: Name = Flag(Key)
age: Age | None = None
class Employment(Relation):
flags = TypeFlags(name="employment")
employee: Role[Person] = Role("employee", Person)
# Type-safe role player expression
results = Employment.manager(db).filter(
Employment.employee.age.gte(Age(30))
).execute()
# Django-style lookup
results = Employment.manager(db).filter(employee__age__gt=30).execute()
# Combined with sorting and pagination
results = (
Employment.manager(db)
.filter(Employment.employee.age.gte(Age(25)), salary__gte=80000)
.order_by("employee__age", "-salary")
.limit(10)
.execute()
)
[0.8.1] - 2025-12-11¶
New Features¶
TypeDB Function Support in Code Generator¶
- Parse TypeQL
fundeclarations with parameters and return types - Generate Python function wrappers that return
FunctionCallExprobjects - Auto-generate
functions.pymodule when functions are defined in schema - Support for all TypeDB data types (string, integer, date, datetime, double, boolean, decimal, duration)
-
Location:
type_bridge/generator/render/functions.py -
Added
FunctionCallExprclass for building function calls in queries - New expression type for calling TypeDB functions
- Location:
type_bridge/expressions/functions.py
Lark-based Parser¶
- Migrated from regex-based parser to robust Lark grammar
- Added formal grammar file (
typeql.lark) for better maintainability - Improved handling of edge cases (whitespace, optional clauses)
- Better support for TypeDB 3.0 features
- Location:
type_bridge/generator/typeql.lark,type_bridge/generator/parser.py
Bug Fixes¶
Parser Grammar Fixes¶
- Fixed parsing of
suband@abstractin entity/relation bodies - Now correctly handles patterns like
entity page @abstract, sub content, - Supports
subappearing anywhere in the type definition, not just at the start - Fixed parsing of
@cardannotations onplaysandrelatesstatements - Now correctly parses
plays posting:post @card(1)andrelates subject @card(1)
Testing¶
- Added 136 new unit tests for function parsing and rendering
- All 808 tests passing (520 unit + 288 integration)
Key Files Added/Modified¶
type_bridge/generator/typeql.lark- Formal TypeQL grammar (75 lines)type_bridge/generator/parser.py- Rewritten with Lark integrationtype_bridge/generator/models.py- AddedFunctionSpec,ParameterSpectype_bridge/generator/render/functions.py- Function code generationtype_bridge/expressions/functions.py-FunctionCallExprclasstype_bridge/expressions/__init__.py- ExportFunctionCallExprtype_bridge/generator/__init__.py- Expose function parsing APItests/unit/generator/test_functions.py- Function unit tests
[0.8.0] - 2025-12-11¶
New Features¶
Code Generator (TypeQL โ Python)¶
- Added
type_bridge.generatormodule for generating Python models from TypeQL schema files - Eliminates manual synchronization between
.tqlschemas and Python code - Write schema once in TypeQL, generate type-safe Python models automatically
-
Location:
type_bridge/generator/ -
CLI interface for code generation
- Usage:
python -m type_bridge.generator schema.tql -o ./models/ - Options:
--version,--no-copy-schema,--implicit-keys -
Location:
type_bridge/generator/__main__.py -
Programmatic API
generate_models(schema, output_dir)- Main generation functionparse_tql_schema(schema_content)- Parse TypeQL to intermediate representation-
Location:
type_bridge/generator/__init__.py -
Full TypeDB 3.x schema support
- All value types: string, integer, double, decimal, boolean, date, datetime, datetime-tz, duration
- Entity and relation inheritance (
subdeclarations) - Abstract types (
@abstract) - Attribute constraints:
@key,@unique,@card,@regex,@values - Role definitions and
playsdeclarations -
Comment annotations for customization (
# @prefix:,# @internal) -
Generated package structure
Bug Fixes¶
Optional Attribute Update Fix¶
- Fixed silent update failures for optional attributes (Resolves #47)
- Previously: Updating an entity with an optional attribute set to
Nonecould silently fail - Now: Properly handles
Nonevalues in update operations - Location:
type_bridge/crud/entity/manager.py
Testing¶
- Added comprehensive generator test suite
- 62 unit tests covering parser, naming utilities, and renderers
- 18 integration tests verifying generated code imports and executes correctly
- Test fixtures with complex TypeQL schemas
-
Location:
tests/unit/generator/,tests/integration/generator/ -
Expanded lookup filter tests
- Additional test coverage for lookup filter parsing and execution
- Location:
tests/unit/crud/test_lookup_parser.py,tests/integration/queries/test_lookup_filters.py
Documentation¶
- Added generator documentation
- Complete API reference and usage guide
- CLI reference and examples
- Supported TypeQL features and cardinality mapping
- Best practices for generated code management
-
Location:
docs/api/generator.md -
Updated project documentation
- Added generator to project structure in CLAUDE.md
- Updated README.md with code generator feature
Key Files Added/Modified¶
type_bridge/generator/__init__.py- Public API:generate_models(),parse_tql_schema()type_bridge/generator/__main__.py- CLI interfacetype_bridge/generator/models.py-ParsedSchema,AttributeSpec,EntitySpec,RelationSpectype_bridge/generator/parser.py- TypeQL parser with inheritance resolutiontype_bridge/generator/naming.py- kebab-case โ PascalCase/snake_case utilitiestype_bridge/generator/render/- Code generation renderers (attributes, entities, relations, package)type_bridge/crud/entity/manager.py- Optional attribute update fixdocs/api/generator.md- Generator documentation
Usage Examples¶
CLI Usage¶
# Generate models from a schema file
python -m type_bridge.generator schema.tql -o ./myapp/models/
# With options
python -m type_bridge.generator schema.tql \
--output ./myapp/models/ \
--version 2.0.0 \
--implicit-keys id
Programmatic Usage¶
from type_bridge.generator import generate_models
# From a file path
generate_models("schema.tql", "./myapp/models/")
# From schema text
schema = """
define
entity person, owns name @key;
attribute name, value string;
"""
generate_models(schema, "./myapp/models/")
Using Generated Models¶
from myapp.models import attributes, entities, relations
from myapp.models import SCHEMA_VERSION, schema_text
# Access generated classes
person = entities.Person(name=attributes.Name("Alice"))
# Get schema version
print(SCHEMA_VERSION) # "1.0.0"
[0.7.2] - 2025-12-10¶
Breaking Changes¶
New Exceptions for Delete Operations¶
- Added
EntityNotFoundError- Raised when deleting an entity that doesn't exist - Now raised for both keyed and keyless entities when no match is found
- Previously: keyed entities silently succeeded, keyless raised
ValueError -
Subclass of
LookupError -
Added
RelationNotFoundError- Raised when deleting a relation that doesn't exist - Raised when relation with given role players is not found
- Previously: silently succeeded
-
Subclass of
LookupError -
Added
NotUniqueError- Raised when keyless entity matches multiple records - Replaces
ValueErrorfor multiple match scenarios - Subclass of
ValueError - Suggestion to use
filter().delete()for bulk deletion
Migration Guide¶
# Handling non-existent entity deletion (NEW in v0.7.2)
from type_bridge import EntityNotFoundError, RelationNotFoundError, NotUniqueError
# Entity with @key that doesn't exist
try:
manager.delete(nonexistent_entity)
except EntityNotFoundError:
print("Entity was already deleted or never existed")
# Relation that doesn't exist
try:
relation_manager.delete(nonexistent_relation)
except RelationNotFoundError:
print("Relation was already deleted or never existed")
# Entity without @key matching multiple records
try:
manager.delete(keyless_entity)
except NotUniqueError:
print("Multiple entities matched - use filter().delete() for bulk deletion")
# Bulk delete with __in (migrating from v0.7.0)
# OLD: manager.delete_many(name__in=["Alice", "Bob"])
# NEW:
count = manager.filter(name__in=["Alice", "Bob"]).delete()
Key Files Modified¶
type_bridge/crud/exceptions.py- NEW - Exception classestype_bridge/crud/__init__.py- Export exceptionstype_bridge/crud/entity/manager.py- Add existence check before deletetype_bridge/crud/relation/manager.py- Add existence check before deletetype_bridge/__init__.py- Export exceptions
[0.7.1] - 2025-12-09¶
Breaking Changes¶
Delete API Refactored to Instance-Based Pattern¶
- Changed
EntityManager.delete()signature - Old:
delete(**filters) -> int(filter-based, returns count) - New:
delete(entity: E) -> E(instance-based, returns deleted entity) - Uses
@keyattributes to identify entity (same pattern asupdate()) -
Related: Issue #37
-
Changed
EntityManager.delete_many()signature - Old:
delete_many(**filters) -> int(filter-based with__insupport) -
New:
delete_many(entities: list[E]) -> list[E](instance list, returns list) -
Changed
RelationManager.delete()anddelete_many()similarly - Uses role players'
@keyattributes to identify the relation - Each role player is matched by their
@keyattribute
New Features¶
Instance Delete Methods¶
- Added
Entity.delete(connection)instance method - Delete entity directly:
alice.delete(db) - Returns self for chaining
-
Location:
type_bridge/models/entity.py -
Added
Relation.delete(connection)instance method - Delete relation directly:
employment.delete(db) - Returns self for chaining
- Location:
type_bridge/models/relation.py
Fallback for Entities Without @key¶
- Entities without
@keycan still be deleted if they match exactly 1 record - Matches by ALL non-None attributes
- Raises
ValueErrorif 0 or >1 matches found - Provides safer delete behavior than filter-based approach
Migration Guide¶
# OLD (v0.7.0): Filter-based deletion
deleted_count = manager.delete(name="Alice") # Returns int
# NEW (v0.7.1): Instance-based deletion
alice = manager.get(name="Alice")[0]
deleted = manager.delete(alice) # Returns Alice instance
# OR use instance method
alice.delete(db) # Returns alice
# For filter-based deletion, use filter().delete()
count = manager.filter(name__in=["Alice", "Bob"]).delete() # Still returns int
count = manager.filter(Age.gt(Age(65))).delete() # Expression filters
Key Files Modified¶
type_bridge/crud/entity/manager.py- Refactoreddelete(),delete_many()type_bridge/crud/relation/manager.py- Refactoreddelete(),delete_many()type_bridge/models/entity.py- Addeddelete()instance methodtype_bridge/models/relation.py- Addeddelete()instance method
[0.7.0] - 2025-12-08¶
๐ New Features¶
TransactionContext for Shared Operations¶
- Added
TransactionContextclass for sharing transactions across operations - Multiple managers can share a single transaction
- Auto-commit on context exit, rollback on exception
- Location:
type_bridge/session.py
with db.transaction(TransactionType.WRITE) as tx:
person_mgr = Person.manager(tx) # reuses tx
artifact_mgr = Artifact.manager(tx) # same tx
# ... operations commit together
Unified Connection Type¶
- Added
Connectiontype alias for flexible connection handling Connection = Database | Transaction | TransactionContext- All managers accept any Connection type
ConnectionExecutorhandles transaction reuse internally- Location:
type_bridge/session.py
Entity Dict Helpers¶
- Added
Entity.to_dict()for serialization - Unwraps Attribute instances to
.value - Supports
include,exclude,by_alias,exclude_unsetoptions - Added
Entity.from_dict()for deserialization - Optional
field_mappingfor external key names strict=Falsemode to ignore unknown fields- Location:
type_bridge/models/entity.py
person.to_dict() # {'name': 'Alice', 'age': 30}
Person.from_dict(payload, field_mapping={"display-id": "display_id"})
Django-style Lookup Filters¶
- Added lookup suffix operators to
filter() __contains,__startswith,__endswith,__regexfor strings__gt,__gte,__lt,__ltefor comparisons__infor disjunction (multiple values)__isnullfor null checks- Location:
type_bridge/crud/entity/manager.py
person_manager.filter(name__startswith="Al", age__gt=30).execute()
person_manager.filter(status__in=["active", "pending"]).execute()
Bulk Operations¶
- Added
EntityManager.update_many()- Update multiple entities in one transaction - Added
EntityManager.delete_many()- Bulk delete with__infilter support
๐ Documentation¶
- Comprehensive documentation update
- Fixed broken example paths in README.md
- Added Connection types documentation to docs/api/crud.md
- Added TransactionContext usage examples
- Added lookup filter documentation with TypeQL mappings
- Added dict helpers documentation to docs/api/entities.md
๐ง Maintenance¶
- Fixed version mismatch between pyproject.toml and init.py
- Added
typings/stubs forisodateandtypedb.driver
๐ฆ Key Files Modified¶
type_bridge/session.py- Added TransactionContext, Connection, ConnectionExecutortype_bridge/models/entity.py- Added to_dict(), from_dict()type_bridge/crud/entity/manager.py- Added lookup filters, update_many, delete_manytype_bridge/crud/relation/manager.py- Unified connection handlingdocs/api/crud.md- New sections for transactions, lookups, bulk opsdocs/api/entities.md- Dict helpers documentation
[0.6.4] - 2025-12-04¶
๐ New Features¶
CRUD PUT Operations (Idempotent Insert)¶
- Added
EntityManager.put()for idempotent entity insertion - Inserts entity only if it doesn't already exist
- Safe to call multiple times without creating duplicates
- Uses TypeQL's PUT clause for atomic match-or-insert semantics
-
Location:
type_bridge/crud/entity/manager.py -
Added
EntityManager.put_many()for bulk idempotent insertion - All-or-nothing semantics: entire pattern must match or all is inserted
-
Efficient batch operations for data synchronization
-
Added
RelationManager.put()for idempotent relation insertion - Same PUT semantics for relations with role players
- Prevents duplicate relationships
-
Location:
type_bridge/crud/relation/manager.py -
Added
RelationManager.put_many()for bulk relation PUT - Batch idempotent insertion for relations
Use Cases¶
- Data import scripts (safe re-runs)
- Ensuring reference data exists
- Synchronization with external systems
- Idempotent API endpoints
๐ Documentation¶
- Updated
docs/api/crud.mdwith PUT operations section - Comparison table: INSERT vs PUT behavior
- All-or-nothing semantics explanation
-
Usage examples for entities and relations
-
Added
examples/basic/crud_08_put.pytutorial - Demonstrates PUT vs INSERT differences
- Shows idempotent behavior patterns
๐งช Testing¶
- Added entity PUT integration tests (
tests/integration/crud/entities/test_put.py) - Single put, bulk put_many
- Idempotency verification
-
All-or-nothing behavior
-
Added relation PUT integration tests (
tests/integration/crud/relations/test_put.py) - Relation put operations
- Role player handling
๐ฆ Key Files Modified¶
type_bridge/crud/entity/manager.py- Addedput(),put_many()type_bridge/crud/relation/manager.py- Addedput(),put_many()docs/api/crud.md- PUT documentationexamples/basic/crud_08_put.py- New tutorialtests/integration/crud/entities/test_put.py- Entity PUT teststests/integration/crud/relations/test_put.py- Relation PUT testsREADME.md- Updated features
๐ก Usage Examples¶
# Single PUT (idempotent insert)
alice = Person(name=Name("Alice"), age=Age(30))
person_manager.put(alice)
person_manager.put(alice) # No duplicate created
# Bulk PUT
persons = [Person(name=Name("Bob")), Person(name=Name("Carol"))]
person_manager.put_many(persons)
person_manager.put_many(persons) # No duplicates
# Relation PUT
employment = Employment(employee=alice, employer=techcorp)
employment_manager.put(employment)
[0.6.3] - 2025-12-04¶
๐ New Features¶
Multi-Player Roles¶
- Added
Role.multi()for roles playable by multiple entity types - Syntax:
origin: Role[Document | Email] = Role.multi("origin", Document, Email) - Eliminates need for artificial supertype hierarchies
- Generates multiple
playsdeclarations in TypeQL schema - Location:
type_bridge/models/role.py - Full CRUD support for multi-role relations
- Filter by specific player type:
manager.get(origin=doc) - Chainable operations work with multi-roles
- Batch insert with mixed player types supported
- Runtime validation: TypeError if wrong player type assigned
- Pydantic integration: Union types provide IDE/type-checker support
TypeDB 3.7 Compatibility¶
- Verified compatibility with TypeDB 3.7.0-rc0
- Updated documentation to reflect tested TypeDB version
๐ Bug Fixes¶
Inherited Attribute Filter Bug¶
- Fixed filters on inherited attributes being silently ignored
- Root cause:
get_owned_attributes()was used instead ofget_all_attributes()in filter operations - Affected methods:
EntityManager.delete(),EntityQuery.delete(),QueryBuilder.match_entity() - Example:
Dog.manager(db).get(name=LivingName("Buddy"))now works whennameis inherited from parentLivingclass - Location:
type_bridge/crud/entity/query.py:215,type_bridge/crud/entity/manager.py:219,type_bridge/query.py:193 - Impact: Dictionary-based filters (
get(),delete()) now correctly handle inherited attributes in subtype queries
๐งช Testing¶
Multi-Role Tests¶
- Multi-role integration tests (
tests/integration/crud/relations/test_multi_role.py) - 37 tests - Insert relations with different role player types
- Filter by multi-role players
- Delete filtered by multi-role
- Chainable
update_withoperations - Multi-role with 3+ entity types
- Multi-role unit tests (
tests/unit/core/test_multi_role_players.py) - Role.multi() API validation
- Type safety and runtime validation
Inherited Attribute Filter Tests¶
- Created unit tests (
tests/unit/core/test_inherited_attribute_filter.py) with 9 tests: get_owned_attributes()vsget_all_attributes()behavior verificationQueryBuilder.match_entity()with inherited/owned/mixed attribute filters- Deep inheritance chain (grandparent โ parent โ child) attribute access
- Created integration tests (
tests/integration/crud/test_inherited_attribute_filter.py) with 5 tests: get()with inherited key attributedelete()with inherited attribute filter- Combined inherited + owned attribute filters
๐ฆ Key Files Modified¶
type_bridge/models/role.py- AddedRole.multi()and multi-player supporttype_bridge/schema/info.py- Generate multipleplaysdeclarationstype_bridge/crud/relation/manager.py- Multi-role query handlingtype_bridge/crud/relation/query.py- Multi-role filtering supportdocs/api/relations.md- Added "Multi-player Roles" documentationtype_bridge/crud/entity/query.py- Fixeddelete()to useget_all_attributes()type_bridge/crud/entity/manager.py- Fixeddelete()to useget_all_attributes()type_bridge/query.py- Fixedmatch_entity()to useget_all_attributes()tests/integration/crud/relations/test_multi_role.py- New multi-role test suite (37 tests)tests/unit/core/test_multi_role_players.py- New multi-role unit tests
[0.6.0] - 2025-11-24¶
๐ New Features¶
Chainable Delete and Update Operations¶
- Added
EntityQuery.delete()for chainable deletion - Delete entities after complex filtering:
manager.filter(Age.gt(Age(65))).delete() - Builds TypeQL delete query from both dict-based and expression-based filters
- Single atomic transaction with automatic rollback on error
- Returns count of deleted entities (0 if no matches)
-
Location:
type_bridge/crud.py:626-676 -
Added
EntityQuery.update_with(func)for functional bulk updates - Update multiple entities using lambda or named functions
- Example:
manager.filter(Age.gt(Age(30))).update_with(lambda p: setattr(p, 'age', Age(p.age.value + 1))) - Fetches matching entities, applies function, updates all in single transaction
- Returns list of updated entities (empty list if no matches)
- Error handling: Stops immediately and raises error if function fails on any entity
- All updates in single atomic transaction (all-or-nothing)
-
Location:
type_bridge/crud.py:678-730 -
Helper methods added
_build_update_query(entity): Builds TypeQL update query for single entity_is_multi_value_attribute(flags): Checks attribute cardinality- Reuses existing EntityManager logic for consistency
Benefits¶
- Chainable API: Natural method chaining for complex operations
- Type-safe: Full integration with expression-based filtering
- Atomic transactions: All operations are all-or-nothing
- Functional updates: Clean lambda/function-based bulk updates
- Consistent API: Works seamlessly with existing filter() method
AttributeFlags Configuration for Attribute Type Names¶
- Added
AttributeFlags.namefield - Explicitly override attribute type name:
flags = AttributeFlags(name="person_name") - Use case: Interop with existing TypeDB schemas, legacy naming conventions
-
Location:
type_bridge/attribute/flags.py:229 -
Added
AttributeFlags.casefield - Apply case formatting to attribute type names:
flags = AttributeFlags(case=TypeNameCase.SNAKE_CASE) - Supports: CLASS_NAME (default), LOWERCASE, SNAKE_CASE, KEBAB_CASE
- Use case: Consistent naming conventions across large schemas
-
Location:
type_bridge/attribute/flags.py:230 -
Updated
Attribute.__init_subclass__to use AttributeFlags - Priority: flags.name > attr_name > flags.case > class.case > default CLASS_NAME
- Respects both explicit name and case formatting
- Location:
type_bridge/attribute/base.py:108-126
Benefits¶
- Flexible naming: Support for legacy schemas and naming conventions
- Consistent API: Mirrors TypeFlags.name pattern for entities/relations
- Migration friendly: Easier interop with existing TypeDB databases
- Developer choice: Explicit name or automatic case formatting
๐๏ธ Refactoring¶
Modularized CRUD Operations¶
- Refactored monolithic
crud.py(3008 lines) into modular structure - Split into 11 focused modules under
crud/directory - Entity operations:
crud/entity/with manager, query, and group_by modules - Relation operations:
crud/relation/with manager, query, and group_by modules - Shared utilities:
crud/utils.pyforformat_valueandis_multi_value_attribute - Base definitions:
crud/base.pyfor type variables - Benefits:
- Eliminated code duplication (shared utilities now have single implementations)
- Improved maintainability (files are now 200-800 lines each)
- Better code organization and discoverability
- Preserved backward compatibility (all imports still work)
- Impact: No breaking changes, all existing code continues to work
Modularized Models¶
- Previously refactored
models.pyinto modular structure - Split into
models/directory with base, entity, relation, role, and utils modules - Improved separation of concerns and maintainability
๐ Bug Fixes¶
String Attribute Escaping in Multi-Value Attributes¶
- Fixed proper escaping of special characters in multi-value string attributes
- Backslashes are now properly escaped:
\โ\\ - Double quotes are properly escaped:
"โ\" - Escape order matters: backslashes first, then quotes
- Location:
type_bridge/query.py,type_bridge/crud.py,type_bridge/models/base.py - Impact: Multi-value string attributes with quotes or backslashes now work correctly in insert/update operations
- Examples:
- Quotes:
Tag('skill "Python"')โ TypeQL:has Tag "skill \"Python\"" - Backslashes:
Path("C:\\Users\\Alice")โ TypeQL:has Path "C:\\Users\\Alice" - Mixed:
Description(r'Path: "C:\Program Files"')โ TypeQL:has Description "Path: \"C:\\Program Files\""
๐ Documentation¶
API Documentation Updated¶
- Updated
docs/api/crud.mdwith comprehensive new sections: - Chainable Delete section with examples and behavior explanation
- Bulk Update with Function section demonstrating lambda and named function usage
- Updated EntityQuery method signatures
- Added "New in v0.6.0" markers for discoverability
-
Error handling and empty results behavior documented
-
Updated
docs/api/attributes.mdwith new section: - "Configuring Attribute Type Names" section with comprehensive examples
- Documents AttributeFlags.name for explicit type name overrides
- Documents AttributeFlags.case for automatic case formatting
- Shows priority order and all configuration options
-
Use cases and best practices
-
Updated
docs/INTERNALS.md: - Updated AttributeFlags dataclass documentation
- Added name and case fields with usage examples
- Updated cardinality field names (card_min, card_max)
README Updated¶
- Added "Chainable Operations" to features list
- Highlights filter, delete, and bulk update capabilities
- Location:
README.md
New Example Created¶
- Created
examples/advanced/crud_07_chainable_operations.py - Comprehensive demonstration of chainable delete and update
- Shows lambda functions, named functions, and complex multi-attribute updates
- Demonstrates atomic transaction behavior with rollback examples
- Interactive tutorial format with step-by-step explanations
๐งช Testing¶
Integration Tests Added¶
- Created
tests/integration/crud/entities/test_chainable.pywith 9 comprehensive tests: test_chainable_delete_with_expression_filter- Basic delete with expressionstest_chainable_delete_with_multiple_filters- Multiple filter combinationstest_chainable_delete_returns_zero_for_no_matches- Empty results handlingtest_chainable_delete_with_range_filter- Range queries (gte/lt)test_update_with_lambda_increments_age- Lambda function updatestest_update_with_function_modifies_status- Named function updatestest_update_with_returns_empty_list_for_no_matches- Empty results handlingtest_update_with_complex_function_multiple_attributes- Multi-attribute updatestest_update_with_atomic_transaction- Transaction rollback verification
Test Results¶
- All 9 tests passing โ
- Tests verify:
- Correct entity deletion with expression filters
- Accurate counts returned
- Proper transaction boundaries (atomic behavior)
- Error propagation and rollback
- Empty result handling
- Multi-attribute updates
- Lambda and function-based updates
Escaping Test Coverage Added¶
- Created comprehensive string escaping test suite
- 7 unit tests for multi-value string escaping patterns
- 9 integration tests verifying end-to-end escaping behavior
- Location:
tests/unit/attributes/test_multivalue_escaping.py,tests/integration/crud/attributes/test_multivalue_escaping.py - Test coverage includes:
- Quotes in strings:
'skill "Python"' - Backslashes in paths:
C:\Users\Alice - Mixed escaping:
"C:\Program Files\App" - Empty strings and special characters
- Unicode characters (cafรฉ, ๆฅๆฌ่ช, emoji๐)
- Single quotes (not escaped in TypeQL)
- Relations with multi-value escaping
- Batch operations:
insert_many(),update_with()
๐ฆ Key Files Modified¶
type_bridge/crud.py- Added delete() and update_with() to EntityQuery classdocs/api/crud.md- Updated API documentation with new methodsREADME.md- Added chainable operations to features listexamples/advanced/crud_07_chainable_operations.py- New comprehensive exampletests/integration/crud/entities/test_chainable.py- New integration test suitetests/unit/attributes/test_multivalue_escaping.py- New unit test suite (7 tests)tests/integration/crud/attributes/test_multivalue_escaping.py- New integration test suite (9 tests)
๐ก Usage Examples¶
Chainable Delete¶
# Delete all persons over 65
count = Person.manager(db).filter(Age.gt(Age(65))).delete()
# Delete with multiple filters
count = manager.filter(
Age.lt(Age(18)),
Status.eq(Status("inactive"))
).delete()
Chainable Update with Lambda¶
# Increment age for all persons over 30
updated = manager.filter(Age.gt(Age(30))).update_with(
lambda person: setattr(person, 'age', Age(person.age.value + 1))
)
Chainable Update with Function¶
def promote(person):
person.status = Status("senior")
person.salary = Salary(int(person.salary.value * 1.1))
promoted = manager.filter(Age.gte(Age(35))).update_with(promote)
[0.5.1] - 2025-11-20¶
๐ Bug Fixes¶
Integer Key Query Bug¶
- Fixed entities with Integer-type keys failing to query by key value
- Root cause: Attribute instances not being unwrapped before TypeQL value formatting
EntityId(123)was formatted as"123"(string) instead of123(integer)- Generated incorrect TypeQL:
has EntityId "123"causing type mismatch - Fix: Added
.valueextraction in_format_value()before type checking - Location:
type_bridge/query.py:252-256,type_bridge/crud.py:419-423,type_bridge/crud.py:1145-1149 - Impact: All non-string attribute types (Integer, Double, Decimal, Boolean, Date, DateTime, DateTimeTZ, Duration) now work correctly as entity keys and in query filters
- Silent failure fixed: Entities would insert successfully but couldn't be queried, now both work correctly
๐งช Testing¶
Regression Tests Added¶
- Created comprehensive Integer key test suite
- 5 new integration tests specifically for Integer key bug regression
- Tests cover: basic insert/query, comparison with String keys, various integer values, chainable queries, all()/count() methods
- Location:
tests/integration/crud/entities/test_integer_key_bug.py - Test Results: 422/422 tests passing (284 unit + 138 integration) โ
- All existing tests still passing
- All new regression tests passing
- Zero test failures or regressions
Why String Keys Worked¶
- String attributes need quotes in TypeQL anyway
- Bug accidentally produced correct output:
"KEY-123" - Integer, Boolean, Double, etc. require unquoted values in TypeQL
- These would fail with incorrect quoting:
"123","true","3.14"
๐ฆ Key Files Modified¶
type_bridge/query.py- Fixed_format_value()functiontype_bridge/crud.py- FixedEntityManager._format_value()andRelationManager._format_value()tests/integration/crud/entities/test_integer_key_bug.py- New regression test suite (5 tests)
[0.5.0] - 2025-11-20¶
๐ New Features¶
Concise Attribute Type-Based Expression API¶
- New streamlined query API using attribute class methods
- Old:
Person.age.gt(Age(30))โ New:Age.gt(Age(30))โจ - Shorter, more readable syntax with better type checking support
- Type checkers now correctly validate all expression methods
- Location:
type_bridge/attribute/base.py,type_bridge/attribute/string.py
Class Methods Added to Attribute Base Class¶
- Comparison methods:
gt(),lt(),gte(),lte(),eq(),neq() - Example:
Age.gt(Age(30)),Salary.gte(Salary(80000)) - Aggregation methods:
sum(),avg(),max(),min(),median(),std() - Example:
Salary.avg(),Age.sum() - String-specific methods (on
Stringclass):contains(),like(),regex() - Example:
Email.contains(Email("@company.com")),Name.like(Name("^A.*"))
Runtime Validation¶
- Automatic attribute ownership validation in filter() methods
- Validates that entity owns the attribute type being queried
- Raises
ValueErrorwith helpful message if validation fails - Example:
person_manager.filter(Salary.gt(Salary(50000)))validates Person owns Salary - Location:
type_bridge/crud.py,type_bridge/expressions/base.py
๐ API Changes¶
Expression Classes Refactored¶
- Changed from field-based to attribute type-based
ComparisonExpr,StringExpr,AggregateExprnow useattr_typeinstead offield- Simpler internal structure with 1-to-1 mapping (attribute type uniquely identifies field)
- Location:
type_bridge/expressions/comparison.py,type_bridge/expressions/string.py,type_bridge/expressions/aggregate.py
Backwards Compatibility¶
- Old field-based API still works
Person.age.gt(Age(30))continues to work alongside new API- FieldRef classes now delegate to attribute class methods internally
- Gradual migration path for existing code
- Location:
type_bridge/fields.py
๐ง Type Safety Improvements¶
Keyword-Only Arguments Enforced¶
- Changed
@dataclass_transform(kw_only_default=False)โTrue - All Entity/Relation constructors now require keyword arguments for clarity and safety
- Improves code readability and prevents positional argument order errors
- Example:
Person(name=Name("Alice"), age=Age(30))โ - Positional args now rejected by type checkers:
Person(Name("Alice"), Age(30))โ - Location:
type_bridge/models/base.py:20,type_bridge/models/entity.py:81,type_bridge/models/relation.py:30
Optional Field Defaults Required¶
- Added explicit
= Nonedefaults for all optional fields - Pattern:
age: Age | None = None(previouslyage: Age | None) - Makes field optionality explicit in code for better clarity
- Improves IDE autocomplete and type checking accuracy
- Required by
kw_only_default=Trueto distinguish optional from required fields - Applied throughout codebase: examples, tests, integration tests
Pyright Type Checking Configuration¶
- Added
pyrightconfig.jsonfor project-wide type checking - Excludes validation tests from type checking (
tests/unit/type-check-except/) - Tests intentionally checking Pydantic validation failures now properly excluded
- Core library achieves 0 errors, 0 warnings, 0 informations โจ
- Proper separation of type-safe code vs runtime validation tests
- Location:
pyrightconfig.json(new file)
Validation Tests Reorganized¶
- Moved intentional validation tests to
tests/unit/type-check-except/ - Tests using raw values to verify Pydantic validation now excluded from type checking
- Original tests fixed to use properly wrapped attribute types
- Clean separation: type-safe tests vs validation behavior tests
- Moved files:
test_pydantic.py,test_basic.py,test_update_api.py,test_cardinality.py,test_list_default.py
Benefits¶
- Clearer code: Keyword arguments make field names explicit at call sites
- Better IDE support: Explicit
= Noneimproves autocomplete for optional fields - 100% type safety: Pyright validates correctly with zero false positives
- Maintainability: Adding new fields doesn't break existing constructor calls
- Error prevention: Type checker catches argument order mistakes at development time
๐ Documentation¶
Automatic Conversions Documented¶
avg()โmeanin TypeQL- TypeDB 3.x uses
meaninstead ofavg - User calls
Age.avg(), generatesmean($age)in TypeQL - Result key converted back to
avg_agefor consistency - Clearly documented in docstrings and implementation comments
regex()โlikein TypeQL- TypeQL uses
likefor regex pattern matching regex()provided as user-friendly alias- Both methods generate identical TypeQL output
- Documented in method docstrings and code comments
TypeQL Compliance Verification¶
- All expressions verified against TypeDB 3.x specification
- Comparison operators:
>,<,>=,<=,==,!=โ - String operations:
contains,likeโ - Aggregations:
sum,mean,max,min,median,std,countโ - Boolean logic:
;(AND),or,notโ - Created
tmp/typeql_verification.mdandtmp/automatic_conversions.md
Examples Updated¶
- Updated query_expressions.py to use new API
- All field-based expressions converted to attribute type-based
- Added notes about API improvements and type safety
- Location:
examples/advanced/query_expressions.py
๐งช Testing¶
Test Results¶
- 417/417 tests passing (100% pass rate) โ
- Unit tests: 284/284 passing (0.3s)
- Integration tests: 133/133 passing
- Type checking: 0 errors, 0 warnings, 0 informations โ
- All type errors eliminated (250 errors โ 0 errors)
Tests Updated¶
- Updated field reference tests for new API
- Tests now check
attr_typeinstead offieldattributes - All expression creation and TypeQL generation tests passing
- Location:
tests/unit/expressions/test_field_refs.py
Test Organization¶
- Integration tests reorganized into subdirectories
tests/integration/queries/test_expressions.py- Query expression integration teststests/integration/crud/relations/test_abstract_roles.py- Abstract role type tests- Better organization: crud/, queries/, schema/ subdirectories
- Improved test discoverability and maintenance
๐ง Type Safety¶
Type Checking Improvements¶
- Eliminated all expression-related type errors
- Before: 26 errors (
.gt(),.avg()"not a known attribute" errors) - After: 0 errors โ
- Type checkers now fully understand class method API
- Pyright passes with 0 errors, 0 warnings, 0 informations
Benefits¶
- Type-safe: Full type checker support with zero errors
- Concise: Shorter syntax (
Age.gt()vsPerson.age.gt()) - Validated: Runtime checks prevent invalid queries
- Compatible: Old API still works for gradual migration
- Documented: All automatic conversions clearly explained
๐ฆ Key Files Modified¶
type_bridge/attribute/base.py- Added class methods for comparisons and aggregationstype_bridge/attribute/string.py- Added string-specific class methodstype_bridge/expressions/comparison.py- Changed toattr_type-basedtype_bridge/expressions/string.py- Changed toattr_type-basedtype_bridge/expressions/aggregate.py- Changed toattr_type-basedtype_bridge/expressions/base.py- Addedget_attribute_types()methodtype_bridge/expressions/boolean.py- Added recursive attribute type collectiontype_bridge/fields.py- Updated to delegate to attribute class methodstype_bridge/crud.py- Added validation in filter() methodsexamples/advanced/query_expressions.py- Updated to use new API
[0.4.4] - 2025-11-19¶
๐ Bug Fixes¶
- Fixed inherited attributes not included in insert/get operations
- Entity and Relation insert queries now include all inherited attributes
- Fetch operations properly extract inherited attribute values
- Added
get_all_attributes()method to collect attributes from entire class hierarchy - Location:
type_bridge/models/base.py,type_bridge/models/entity.py,type_bridge/crud.py
๐ API Changes¶
- Removed deprecated
EntityFlagsandRelationFlagsaliases - Use
TypeFlagsfor both entities and relations - All example files updated to use
TypeFlags - Documentation updated to reflect unified API
๐ Documentation¶
- Updated CLAUDE.md: Replaced all EntityFlags/RelationFlags references with TypeFlags
- Updated examples: All 17 example files now use the unified TypeFlags API
[0.4.0] - 2025-11-15¶
๐ New Features¶
Docker Integration for Testing¶
- Automated Docker management for integration tests
- Added
docker-compose.ymlwith TypeDB 3.5.5 server configuration - Created
test-integration.shscript for automated Docker lifecycle management - Docker containers start/stop automatically with test fixtures
- Location:
docker-compose.yml,test-integration.sh,tests/integration/conftest.py - Optional Docker usage: Set
USE_DOCKER=falseto use existing TypeDB server - Port configuration: TypeDB server on port 1729
Schema Validation¶
- Duplicate attribute type detection
- Prevents using the same attribute type for multiple fields in an entity/relation
- Validates during schema generation to catch design errors early
- Raises
SchemaValidationErrorwith detailed field information - Location:
type_bridge/schema/info.py,type_bridge/schema/exceptions.py - Why it matters: TypeDB stores ownership by attribute type, not by field name
- Using
created: TimeStampandmodified: TimeStampcreates a single ownership - This causes cardinality constraint violations at runtime
- Solution: Use distinct types like
CreatedStampandModifiedStamp
๐งช Testing¶
Test Infrastructure¶
- Improved test organization: 347 total tests (249 unit + 98 integration)
- Docker-based integration tests: Automatic container lifecycle management
- Added duplicate attribute validation tests: 6 new tests for schema validation
- Location:
tests/unit/validation/test_duplicate_attributes.py
๐ Documentation¶
- Updated CLAUDE.md:
- Added Docker setup instructions for integration tests
- Documented duplicate attribute type validation rules
- Added schema validation best practices
- Included examples of correct vs incorrect attribute usage
- Updated test execution patterns: Docker vs manual TypeDB server options
๐ง CI/CD¶
- Updated GitHub Actions workflow:
- Integrated Docker Compose for automated integration testing
- Added TypeDB 3.5.5 service container configuration
- Location:
.github/workflows/(multiple CI updates)
๐ฆ Dependencies¶
- Added
docker-composesupport for development workflow - No changes to runtime dependencies
๐ Bug Fixes¶
- Fixed test fixture ordering: Improved integration test reliability with Docker
- Enhanced error messages: Schema validation errors now include field names
[0.3.X] - 2025-01-14¶
โ Full TypeDB 3.x Compatibility¶
Major Achievement: 100% Test Pass Rate (341/341 tests)
Fixed¶
Query Pagination¶
- Fixed TypeQL clause ordering: offset must come BEFORE limit in TypeDB 3.x
- Changed
limit X; offset Y;โoffset Y; limit X; - Location:
type_bridge/query.py:151-154 - Added automatic sorting for pagination: TypeDB 3.x requires sorting for reliable offset results
- Automatically finds and sorts by key attributes when using limit/offset
- Falls back to required attributes if no key exists
- Location:
type_bridge/crud.py:447-468
Schema Conflict Detection¶
- Updated to TypeDB 3.x syntax: Changed from
subtoisafor type queries - TypeDB 3.x uses
$e isa personinstead of$e sub entity - Fixed
has_existing_schema()to properly detect existing types - Fixed
_type_exists()to use correct TypeQL syntax - Location:
type_bridge/schema/manager.py:65-284 - Improved conflict detection: Now properly raises SchemaConflictError when types exist
Type Safety¶
- Fixed AttributeFlags attribute access: Changed
cardinality_mintocard_min - Resolved pyright type checking error
- Location:
type_bridge/crud.py:460
Testing¶
Test Results¶
- Unit tests: 243/243 passing (100%) - ~0.3s runtime
- Integration tests: 98/98 passing (100%) - ~18s runtime
- Total: 341/341 passing (100%)
Test Coverage¶
- All 9 TypeDB attribute types fully tested (Boolean, Date, DateTime, DateTimeTZ, Decimal, Double, Duration, Integer, String)
- Full CRUD operations for each type (insert, fetch, update, delete)
- Multi-value attribute operations
- Query pagination with limit/offset/sort
- Schema conflict detection and inheritance
- Reserved word validation
Code Quality¶
- โ Ruff linting: 0 errors, 0 warnings
- โ Ruff formatting: All 112 files properly formatted
- โ Pyright type checking: 0 errors, 0 warnings, 0 informations
Documentation¶
- Updated README.md with current test counts and features
- Updated CLAUDE.md testing strategy section
- Added TypeDB 3.x compatibility notes
- Documented pagination requirements and automatic sorting
Key Files Modified¶
type_bridge/query.py- Fixed clause ordering in build()type_bridge/crud.py- Added automatic sorting for pagination, fixed attribute accesstype_bridge/schema/manager.py- Updated to TypeDB 3.xisasyntax
[0.2.0] - Previous Release¶
See git history for earlier changes.