C SDK¶
Security update: Upgrade to TypeBridge 2.2.5. Its prebuilt distributions use rustls 0.23.46, which fixes RUSTSEC-2026-0346 through RUSTSEC-2026-0349 and the earlier RUSTSEC-2026-0285. The 2.2.1 post-release notice records the affected earlier release.
TypeBridge 2.2.5 provides a generated C SDK with native ABI 1.6.0 for Ubuntu 24.04, x86_64 GNU/Linux, shared runtime. C17 and C++17 applications consume generated schema packages through CMake or pkg-config. The public release was independently verified on 2026-10-15.
The SDK uses the same Rust-owned schema, CRUD, query, migration, serialization,
cancellation, diagnostics, and resource-limit contracts as the other SDKs.
Connected acceptance uses exactly TypeDB 3.12.3; the canonical semantic profile
is typedb-3.12.1/v1. The selected C distribution does not cover static linking,
macOS, Windows, or other architectures.
Install the runtime¶
Download the runtime archive and its Sigstore bundle from the 2.2.5 release:
type-bridge-c-runtime-2.2.5-abi-1.6-x86_64-unknown-linux-gnu.tar.gztype-bridge-cli-2.2.5-x86_64-unknown-linux-gnu.tar.gzfor standalone generation and migration commandstype-bridge-c-sdk-example-2.2.5.tar.gzfor the verifiedtb_sdkv3example
Verify the signed release files using the
documented signing identity and provenance.
Extract the runtime into a private installation prefix. It contains the public
header, libtype_bridge_c.so, CMake configuration, and pkg-config metadata.
The standalone CLI archive has its own bin/type-bridge executable.
Application execution needs the shared runtime and its system-library dependencies. Building an application additionally needs a C17 or C++17 compiler and CMake 3.20+ or pkg-config. Python and Cargo are not application runtime dependencies.
Generate an application schema package¶
Add a C output to your Split-YAML workspace:
Then run:
type-bridge --manifest typebridge.yaml schema check
type-bridge --manifest typebridge.yaml schema generate
Distribute the complete generated package with your application. It contains typed declarations, generated C source, embedded schema authority, package identity, and build metadata. Keep the physical schema in Split-YAML and regenerate rather than editing emitted declarations or runtime resources.
Link an application¶
For the released example, CMake discovers both the runtime and generated schema package:
cmake_minimum_required(VERSION 3.20)
project(example LANGUAGES C CXX)
find_package(TypeBridge 1.6.0 EXACT CONFIG REQUIRED)
find_package(tb_sdkv3 1.0.0 EXACT CONFIG REQUIRED)
add_executable(example main.c)
set_target_properties(example PROPERTIES C_STANDARD 17 C_STANDARD_REQUIRED YES)
target_link_libraries(example PRIVATE tb_sdkv3::schema)
Set TypeBridge_DIR to the runtime's lib/cmake/TypeBridge directory and
tb_sdkv3_DIR to the example package's lib/cmake/tb_sdkv3 directory. Include
<tb_sdkv3/tb_sdkv3.h> from the application. Use the package name emitted for
your own schema when replacing the example.
For pkg-config, add both packages' lib/pkgconfig directories to
PKG_CONFIG_PATH. Compile the source returned by
pkg-config --variable=generated_source tb_sdkv3 together with your application,
using pkg-config --cflags --libs tb_sdkv3. Configure the dynamic loader to find
the installed runtime's lib directory.
Run a query on a database or a TypeBridge server¶
A query session authors terminals; it holds no connection. Each connection type has one execute call, and all of them return the same result family and diagnostics:
| Connection | Execute call |
|---|---|
type_bridge_database_t |
type_bridge_database_query_execute_v1 |
type_bridge_read_transaction_t |
type_bridge_read_transaction_query_execute_v1 |
type_bridge_proxy_connection_t |
type_bridge_proxy_query_execute_v1 |
So one program runs unchanged against TypeDB directly or through a
TypeBridge server; only the connection it opens differs. The proxy
connection, type_bridge_query_session_open_with_limits_v1, and their types
are ABI 1.7; the ABI 1.6 header of 2.2.6 does not declare them. The proxy connection
is synchronous and blocks the calling thread:
type_bridge_proxy_header_v1_t auth = {
{(const uint8_t *)"Authorization", 13},
{(const uint8_t *)token, token_length},
};
type_bridge_proxy_connection_options_v1_t options = {0};
options.struct_size = sizeof options;
options.version = TYPE_BRIDGE_PROXY_CONNECTION_OPTIONS_VERSION;
options.endpoint = (type_bridge_byte_view_t){(const uint8_t *)url, strlen(url)};
options.tls_mode = TYPE_BRIDGE_TLS_NATIVE_ROOTS; /* or _DISABLED, _CUSTOM_ROOT_CA */
options.headers = &auth;
options.header_count = 1;
options.answer_limits = &ceiling; /* NULL selects the proxy defaults */
type_bridge_proxy_connection_t *proxy = NULL;
type_bridge_execution_diagnostics_t *diagnostics = NULL;
status = type_bridge_proxy_connection_open_v1(
package, &options, NULL, &proxy, &diagnostics);
/* ... */
status = type_bridge_proxy_query_execute_v1(
proxy, terminal, kind, NULL, NULL, &result, &diagnostics);
/* ... */
type_bridge_proxy_connection_close(&proxy);
With TLS mode TYPE_BRIDGE_TLS_CUSTOM_ROOT_CA, custom_root_ca_path names a
PEM bundle. An empty pinned_advertisement fetches the server's capability
advertisement during open, bounded by connection_limits; a nonempty one is
used as is. answer_limits is a ceiling: every terminal on the connection
runs under its own limits constrained by it, and limit values are kept or
refused, never clamped. Manager terminals run only on a database or a read
transaction.
ABI 1.6 rollback consumes the write transaction and clears its owner slot, just like commit and close. Keep-open rollback requires the later ABI 1.7 API.
Caller-owned exchange¶
A host that owns the route to the server (its own HTTP stack, a message bus,
or an in-process server) uses the remote context instead of the built-in
proxy connection. It is the exchange extension point, not a second session:
type_bridge_query_remote_context_open_v1 validates the advertisement,
type_bridge_query_remote_prepare_v1 returns a pending request whose bytes
(type_bridge_query_remote_pending_request_bytes) the host sends, and the
reply goes through the one-shot type_bridge_query_remote_pending_claim and
type_bridge_query_remote_claim_decode_v1. Both paths prepare and validate
requests through the same Rust proxy connection.
The release evidence covers relocated installation, strict C17/C++17 headers, direct and caller-transport queries, custom-root TLS, migrations, model serialization, cancellation, resource limits, and cleanup. See the release procedure for the public verification record and exact support boundary.
Provider commit status is selected from the typed commit outcome. ABI 1.6
continues to return TYPE_BRIDGE_STATUS_EXECUTION_FAILED for proven rejections
and TYPE_BRIDGE_STATUS_COMMIT_OUTCOME_UNKNOWN when a commit may have applied.
Rejection diagnostics keep the released commit_definitely_aborted and
provider_operation_failed codes, paths and details. The typed failure
details other SDKs expose (retry_safe, code, rejection, lock_kind,
annotation) belong to ABI 1.7, rather than changing what ABI 1.6 consumers
count and read; see Typed failures.
Stage plans in one transaction (ABI 1.7)¶
ABI 1.7 adds deferred transactions over query-plan/v3 plans. A plan comes
from the plan builder or from canonical plan bytes
(type_bridge_plan_v3_decode); C never serializes plans itself. Staging sends
nothing: type_bridge_staged_transaction_commit runs every staged plan in one
provider transaction, and each pending answer is read after the commit.
Build a plan¶
The builder forwards to the one core builder every SDK uses, so the same
program gives the same plan bytes in C, Rust, Python and TypeScript.
Identities, values and expressions are registered once and named by uint32_t
ids, and operands are (kind, id) pairs. The one-query purchase (check stock
and balance, take one item and the price, record the purchase):
type_bridge_plan_builder_t *b = NULL;
uint32_t item_t, account_t, purchase_t, item_key, account_key, stock_f, price_f,
balance_f, order_f, buyer_r, item_r, item, account, order_in, item_in,
account_in, key, akey, stock, price, balance, zero, one, e, next_stock,
next_balance, purchase, row[3];
type_bridge_plan_builder_new(&b);
type_bridge_plan_builder_type(b, TYPE_BRIDGE_PLAN_THING_ENTITY, text("item"), &item_t);
type_bridge_plan_builder_type(b, TYPE_BRIDGE_PLAN_THING_ENTITY, text("account"), &account_t);
type_bridge_plan_builder_type(b, TYPE_BRIDGE_PLAN_THING_RELATION, text("purchase"), &purchase_t);
type_bridge_plan_builder_owns(b, item_t, text("item-id"), &item_key);
type_bridge_plan_builder_owns(b, account_t, text("account-id"), &account_key);
type_bridge_plan_builder_owns(b, item_t, text("stock"), &stock_f);
type_bridge_plan_builder_owns(b, item_t, text("price"), &price_f);
type_bridge_plan_builder_owns(b, account_t, text("balance"), &balance_f);
type_bridge_plan_builder_owns(b, purchase_t, text("order-id"), &order_f);
type_bridge_plan_builder_role(b, purchase_t, text("buyer"), &buyer_r);
type_bridge_plan_builder_role(b, purchase_t, text("item"), &item_r);
/* Match, in call order. */
type_bridge_plan_builder_exact(b, item_t, &item);
type_bridge_plan_builder_exact(b, account_t, &account);
type_bridge_plan_builder_input(b, text("order_id"), TYPE_BRIDGE_PROJECTED_VALUE_STRING, 0, &order_in);
type_bridge_plan_builder_input(b, text("item_id"), TYPE_BRIDGE_PROJECTED_VALUE_STRING, 0, &item_in);
type_bridge_plan_builder_input(b, text("account_id"), TYPE_BRIDGE_PROJECTED_VALUE_STRING, 0, &account_in);
type_bridge_plan_builder_field(b, item, item_key, &key);
type_bridge_plan_builder_field(b, account, account_key, &akey);
type_bridge_plan_builder_field(b, item, stock_f, &stock);
type_bridge_plan_builder_field(b, item, price_f, &price);
type_bridge_plan_builder_field(b, account, balance_f, &balance);
type_bridge_plan_builder_value_long(b, 0, &zero);
type_bridge_plan_builder_value_long(b, 1, &one);
type_bridge_plan_builder_compare(b, TYPE_BRIDGE_PLAN_OPERAND_BINDING, key,
TYPE_BRIDGE_PLAN_COMPARE_EQUAL, TYPE_BRIDGE_PLAN_OPERAND_INPUT, item_in);
type_bridge_plan_builder_compare(b, TYPE_BRIDGE_PLAN_OPERAND_BINDING, akey,
TYPE_BRIDGE_PLAN_COMPARE_EQUAL, TYPE_BRIDGE_PLAN_OPERAND_INPUT, account_in);
type_bridge_plan_builder_compare(b, TYPE_BRIDGE_PLAN_OPERAND_BINDING, stock,
TYPE_BRIDGE_PLAN_COMPARE_GREATER, TYPE_BRIDGE_PLAN_OPERAND_VALUE, zero);
type_bridge_plan_builder_compare(b, TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance,
TYPE_BRIDGE_PLAN_COMPARE_GREATER_OR_EQUAL, TYPE_BRIDGE_PLAN_OPERAND_BINDING, price);
type_bridge_plan_builder_expr_arith(b, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, stock, TYPE_BRIDGE_PLAN_OPERAND_VALUE, one, &e);
type_bridge_plan_builder_let(b, text("next_stock"), TYPE_BRIDGE_PLAN_OPERAND_EXPR, e, &next_stock);
type_bridge_plan_builder_expr_arith(b, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance, TYPE_BRIDGE_PLAN_OPERAND_BINDING, price, &e);
type_bridge_plan_builder_let(b, text("next_balance"), TYPE_BRIDGE_PLAN_OPERAND_EXPR, e, &next_balance);
/* Writes: both updates share one stage, then the insert. */
type_bridge_plan_builder_update(b, item, stock_f, TYPE_BRIDGE_PLAN_OPERAND_BINDING, next_stock);
type_bridge_plan_builder_update(b, account, balance_f, TYPE_BRIDGE_PLAN_OPERAND_BINDING, next_balance);
type_bridge_plan_builder_insert(b, purchase_t, &purchase);
type_bridge_plan_builder_thing_field(b, purchase, order_f, TYPE_BRIDGE_PLAN_OPERAND_INPUT, order_in);
type_bridge_plan_builder_thing_player(b, purchase, buyer_r, account);
type_bridge_plan_builder_thing_player(b, purchase, item_r, item);
/* One input row, one value id per input column. */
type_bridge_plan_builder_value_string(b, text("O1"), &row[0]);
type_bridge_plan_builder_value_string(b, text("I1"), &row[1]);
type_bridge_plan_builder_value_string(b, text("A1"), &row[2]);
type_bridge_plan_builder_row(b, row, 3);
status = type_bridge_plan_builder_build(b, package, &plan, &diagnostics);
type_bridge_plan_builder_free(&b);
text stands for a helper returning a type_bridge_byte_view_t over a
string. The rules every SDK builder shares:
- Binding ids are dense in creation order.
exact,subtypes,field,links,compareandletadd to one leading match in call order. - Writes append stages in call order; consecutive
update,insert,putordelete*calls share a stage. - Variable names come from labels (
item,item_stock, then_2,_3, ...);inputandletnames are explicit and must be fresh. - A plan with writes answers
TYPE_BRIDGE_PLAN_ANSWER_MATCHED, orROWSafterreturning; a read answersROWS,COUNT(count) orEXISTS(exists).
Values use the C value conventions: UTF-8 strings, int64_t, exact IEEE-754
double bits, Booleans as exactly 0 or 1, and canonical text for date,
datetime, datetime-tz, decimal and duration. Builder calls never fail on
content. type_bridge_plan_builder_build reports the first invalid label,
constant, value or id, else the first invalid builder call, through its
diagnostics; only a broken pointer contract returns
TYPE_BRIDGE_STATUS_INVALID_ARGUMENT from the call itself. build validates
against the schema package's compiled authority and leaves the builder usable.
Stage and commit¶
type_bridge_staged_transaction_t *tx = NULL;
type_bridge_pending_t *pending = NULL;
type_bridge_plan_answer_kind_t kind;
uint64_t matched = 0;
type_bridge_database_transaction(database, TYPE_BRIDGE_TRANSACTION_WRITE, &tx, &diagnostics);
type_bridge_staged_transaction_stage(tx, plan, &pending, &diagnostics);
status = type_bridge_staged_transaction_commit(tx, &diagnostics);
if (status == TYPE_BRIDGE_STATUS_OK)
type_bridge_pending_answer(pending, &kind, &matched); /* MATCHED, 1 or 0 */
type_bridge_staged_transaction_close(&tx); /* the only release */
type_bridge_pending_free(&pending);
type_bridge_plan_free(&plan);
The handle is a reusable logical transaction, as in the other SDKs: commit and
type_bridge_staged_transaction_rollback(tx) keep it usable, and
type_bridge_staged_transaction_close(&tx) is the only release. After a
commit, successful or a typed failure, the handle stages new work; rollback
discards the staged plans. After
TYPE_BRIDGE_STATUS_COMMIT_OUTCOME_UNKNOWN, direct or over the proxy, the
writes may have applied: the caller reads the database to find out, and the
handle stages new work. The open handle keeps its database busy until close. Reading an answer
before commit returns TYPE_BRIDGE_STATUS_IN_USE; after a failed commit,
rollback or close it returns TYPE_BRIDGE_STATUS_EXECUTION_FAILED.
type_bridge_proxy_connection_transaction(proxy, kind, &tx, &diagnostics)
opens the same transaction on a proxy connection. It fetches the server's
staged advertisement at open; commit is one signed exchange that carries every
staged plan. The transaction may outlive the connection.
Typed failures¶
type_bridge_execution_diagnostics_failure_get_v1 reads the typed provider
failure of one diagnostic into type_bridge_execution_failure_v1_t: outcome
(rejected or indeterminate), phase, reason (conflict, cardinality, unique,
constraint, other), lock kind for a conflict, annotation for a constraint,
retry_safe, the staged op_index and the provider code. A diagnostic
without a typed failure reports TYPE_BRIDGE_FAILURE_OUTCOME_NONE. Two
purchases racing for the last item end with one commit and one rejected
commit whose failure is a retry-safe STC2 conflict with
TYPE_BRIDGE_FAILURE_LOCK_EXCLUSIVE; see Concurrency.
Require ABI 1.7¶
The 1.7 runtime serves 1.6 consumers unchanged: CMake accepts
find_package(TypeBridge 1.6.0 EXACT) and pkg-config keeps
type-bridge = 1.6.0 resolving. Applications that use the 1.7 surface
require it explicitly:
The runtime's pkg-config file keeps Version: 1.6.0 and provides
type-bridge-abi at the native ABI version (pkgconf, the Ubuntu 24.04
pkg-config, resolves provided modules). At run time,
type_bridge_c_abi_minor() reports the loaded runtime's minor.