Upgrading to 2.3¶
TypeBridge 2.3 runs every query, direct or through a TypeBridge server, on
one Rust pipeline, and adds staged transactions over typed query-plan/v3
programs in Python, TypeScript/Node, Rust and C. Most 2.2 application code
runs unchanged. This page lists what breaks, what is deprecated and what
replaces it, and the behaviour changes you may notice. The
changelog has the complete list.
Supported TypeDB versions¶
| Use | TypeDB |
|---|---|
| Queries and CRUD | Admits >=3.11.0; measured, supported lines remain 3.11–3.14; newer lines warn |
Recommended server, default in docker-compose.yml and test.sh |
3.14.0 (3.13.6 in 2.3.0) |
Staged plans with input rows (the given stage) |
3.12 or newer |
Migrations on profile typedb-3.12.1/v1 |
3.12.3+ |
Migrations on profile typedb-3.13.6/v1 |
3.13.6+, 3.14.0+, and newer lines |
+ admits later patches on the same minor line. The measured release pins
remain unchanged. Earlier 2.3 releases required exact patches.
Newer lines reuse the newest measured profile and protocol assumptions and
warn once per connection that they are
"not tested or supported by this TypeBridge release". Admission does not
guarantee compatibility. Versions below 3.11.0 remain refused; older workspace
profiles still reject mismatched server lines.
TypeDB 3.11 support is deprecated in 2.3 and removed in 2.4.0; move 3.11 servers to 3.12, 3.13 or 3.14 before upgrading to 2.4.
The Python typedb-driver extra accepts >=3.11,<3.15 (>=3.12.3,<3.15 on
CPython 3.14) from 2.3.1; 2.3.0 capped it at <3.14. Existing workspaces keep the semantic profile they declare.
To move a migration history from 3.12.3 to 3.13.6, move the databases, set
compatibility.semantic-profile to typedb-3.13.6/v1, and run once per
environment:
type-bridge --manifest typebridge.yaml migration upgrade-profile \
--environment production --to typedb-3.13.6/v1
See Move a history to a new TypeDB line.
Before you upgrade¶
- Upgrade clients and servers together. A 2.3 server refuses a V1-format query envelope on its V2 query route, a 2.3 client sends authored plans only to a server that advertises the V2 envelope, and a 2.2 client cannot decode the advertisement of a server configured with non-default limits.
- Regenerate generated packages. A package without embedded schema
authority is refused with
schema_authority_required(every generator since 2.1.0 embeds it). Older Python stubs still run, but a type checker reports their descriptor import until they are regenerated. - Surface deprecations in tests, for example with
python -W error::DeprecationWarning -m pytest, Rust#![deny(deprecated)], or the@deprecatedhints in a TypeScript editor.
What breaks¶
Generated query terminals are asynchronous¶
Every terminal (one, first, rows, page_by, count_by, exists_by,
aggregate) is a coroutine in Python and returns a Promise in TypeScript,
direct connections included. Building the query stays synchronous.
# 2.2
rows = session.query(person).rows(limit=50)
# 2.3
rows = await session.query(person).rows(limit=50)
# 2.3, a script without an event loop
from type_bridge_core import blocking
session = blocking(Person.query(db))
rows = session.query(session.exact(Person)).rows(limit=50)
One session type for direct and proxy¶
QuerySession takes the connection first and runs on a database, a
transaction, or a proxy connection. The handwritten type_bridge.typed
facade is gone; import the session from your generated package.
# 2.2
from type_bridge.typed import QuerySession
remote = RemoteQuerySession(advertisement, exchange, RemoteQueryLimits(max_items=100))
# 2.3
from app_models import (
ExchangeConnection,
QueryExecutionResourceLimits,
QuerySession,
connect_proxy,
)
remote = QuerySession(
ExchangeConnection(advertisement, exchange),
resources=QueryExecutionResourceLimits(items=100),
)
built_in = QuerySession(connect_proxy("https://typebridge.example"))
TypeScript is the same: new QuerySession(new ExchangeConnection(advertisement,
exchange), { resources }) or new QuerySession(await connectProxy(url)).
Rust connect returns a Connection¶
SchemaPackage::connect takes a direct or proxy policy and returns
Connection<S>. Match Connection::Direct to reach CRUD managers:
// 2.2: let db: Database<AppSchema> = SCHEMA.connect(direct_policy).await?;
let db = match SCHEMA.connect(direct_policy).await? {
Connection::Direct(db) => db,
Connection::Proxy(_) => unreachable!("a direct policy opens a direct connection"),
};
Limits and refusals come from the core¶
- A predicate nested deeper than the session's
QueryLimitsallow is refused withcanonical_json_too_deep, direct and remote alike. Raise the session'squery_limits(queryLimits,with_query_limits) to run it. QueryExecutionResourceLimitskeeps the values you pass instead of clamping them, and refuses a timeout over one day or more than 3 statements.- Window, selection, aggregate, group-by and reachability refusals, member
cardinality checks, and unknown enum spellings now come from the Rust core
with one structured code in every language. Python raises
InvalidQueryRequestError,ProjectedCardinalityErrorandUnknownEnumValueError, all stillValueErrors. TypeScript raises the structured error withcategoryandcodeinstead ofRangeErrororTypeError; switch oncode.
Rust remote hosts use the V2 envelope¶
Only typebridge.query-remote-request/v2 is accepted. Code that hosted the
proxy route itself with the V1 or version-dispatching items moves to the
*_v2 items:
// 2.2: AdmittedRemoteRequestEnvelope / RemoteRejectionEnvelope
let admitted = preflight_remote_request_versioned(bytes, &context, &advertisement, ceilings)?;
let reply = execute_admitted_remote_request_versioned(admitted, &mut tx, &signer).await;
// 2.3: AdmittedRemoteRequestV2 / RemoteRejectionV2, same arguments
let admitted = preflight_remote_request_v2(bytes, &context, &advertisement, ceilings)?;
let reply = execute_admitted_remote_request_v2(admitted, &mut tx, &signer).await;
The changelog's "Breaking changes" section lists every renamed constant, removed item, and changed refusal code.
Deprecated and their replacements¶
Each deprecated name keeps working and warns (Python DeprecationWarning,
TypeScript @deprecated, Rust #[deprecated]). All are removed in 3.0.
| Deprecated | Use instead |
|---|---|
Python update_with(func) |
An update plan that computes the value with let_(), staged in a transaction |
Python type_bridge.session.Transaction |
Database.transaction() |
Python and TypeScript RemoteQuerySession, RemoteQueryLimits, RemoteQuery, RemoteGroupedQuery |
QuerySession(ExchangeConnection(...)), QueryExecutionResourceLimits, Query, GroupedQuery |
Rust RemoteDatabase, RemoteQueryTransport, RemoteConnectionOptions, RemoteQueryLimits, DirectTls |
ProxyDatabase, ProxyExchange, ProxyConnectionPolicy, QueryExecutionResourceLimits, TlsPolicy |
Rust MAX_QUERY_* constants |
DEFAULT_PROXY_QUERY_* (same values) |
Rust type_bridge_orm::Transaction |
OwnedTransaction |
Rust require_supported_migration_server |
require_supported_migration_server_for_profile |
Legacy query nodes (Clause, Pattern, Statement, ...) and String compilers (QueryCompiler::compile, Python QueryCompiler.compile, compile_batch, parse_typeql_query) |
Generated typed query plans; try_compile / try_compile_node when bridging old nodes |
| Rust String schema-generation helpers | SchemaInfo::to_typeql |
The schema archive reader (_ArchivedTypeSchema.from_typeql) |
Split-YAML schema authority |
The update_with replacement reads and writes in one query, so no other
transaction can change the row between the read and the write:
# 2.2
accounts.filter(tier=Tier("gold")).update_with(add_bonus)
# 2.3
from type_bridge.plan import Plan
from app_models import Account, schema_authority
plan = Plan.builder()
account = plan.exact(Account)
tier = plan.input("tier", "string")
balance = plan.field(account, Account.balance)
plan.where_(plan.field(account, Account.tier).eq(tier))
plan.update(account, Account.balance, plan.let_("next_balance", balance + 10))
plan.row([tier.value("gold")])
with db.staged_transaction() as tx:
tx.stage(plan.build(schema_authority()))
Not deprecated in 2.3: Database.transaction(), TypeScript
RustDatabase.transaction(), Rust ReadTransaction and WriteTransaction,
the generated managers, and the C ABI 1.6 functions. The staged transaction
does not carry managers or typed queries yet, so these remain the way to use
them.
Behaviour changes you may notice¶
- Rollback keeps the transaction. After a successful
rollback(), the same transaction accepts more work and a later commit;close()ends it. A Pythonwithblock commits work done after an explicit rollback when it exits normally. RustWriteTransaction::rollback(self)and the C ABI 1.6 rollback still consume the transaction; userollback_keep. - TypeDB error text is redacted. Errors that come from TypeDB show a
bracketed code and a fixed description instead of the server's message,
so they never contain query values or credentials. Do not parse messages;
read the code or the typed
failure. - Commit failures are typed. Python commit errors are
CommitRejected,CommitConflictorCommitOutcomeUnknown, allRuntimeErrorsubclasses, soexcept RuntimeErrorstill catches them. Every SDK exposesfailurewithretry_safe. Whenretry_safeis true, rerun the whole transaction from the start; reconcile an unknown outcome before retrying. See Concurrency and conditional writes. - A close failure after a successful commit is logged, not raised.
- Generated TypeQL text is formatted differently. Schema, migration and query text is rendered by the official TypeQL AST, so whitespace, stage separators and number spelling change. Plan bytes, recorded migrations and their checksums keep their bytes. Do not compare rendered TypeQL byte for byte.
- Generated writes run as plans where the package allows it. Rust single
writes and every C write run as
query-plan/v3write plans. Python and TypeScript writes (except a TypeScript singledelete), and Rust batches, do so only in packages generated with ordered collections (projection handler version 2); a package without them keeps its released write path in 2.3, because the handler version pins its behaviour. Relation puts, and single inserts, updates and puts on models with ordered fields or roles, keep the released path everywhere. The next two changes apply only to writes that run as plans. - Relation references resolve inside the write. A polymorphic reference that matches several things, or two references of one role that resolve to one player, are now refused after the write instead of before it; a borrowed transaction becomes rollback-only.
- Large batches split into chunks of up to 4,096 rows on the same transaction instead of failing; the batch is still all-or-nothing.
- C direct answer defaults are looser. A C database, transaction, call or batch without a limits descriptor now gets the direct defaults the other SDKs use (100,000 items, 64 MiB) instead of 65,536 items. A proxy connection gets the wire limits (65,536 items, 32 MiB).
New in 2.3¶
- Staged transactions:
Database.staged_transaction()(Python),RustDatabase.stagedTransaction()(TypeScript),Database::transaction(Rust) andtype_bridge_database_transaction(C ABI 1.7). Nothing reaches TypeDB beforecommit, and each staged answer resolves after it. - A plan builder in all four languages that gives the same canonical bytes in each; see the Query-plan V3 reference.
- Staged transactions over a TypeBridge server (
POST /v3/staged), one signed request per commit. - C ABI 1.7. Existing 1.6 consumers keep working against the 1.7 runtime; see Require ABI 1.7.
Language guides: Python typed queries, TypeScript, Rust, C.