Overview
What are TypeDB drivers?
TypeDB drivers are client libraries that enable applications to communicate with TypeDB servers. They provide a programming language-specific interface for all server operations, from connection management to query execution.
Key responsibilities of a TypeDB driver include:
-
Connection management: Establishing and maintaining network connections to TypeDB servers
-
Authentication: Handling user credentials and security protocols
-
Transaction control: Managing database transactions and their lifecycle
-
Query execution: Sending TypeQL queries and processing results
-
Error handling: Converting server errors into language-specific exceptions
-
Resource management: Properly managing network resources and memory
-
Database management: Create and delete databases
-
User management: Create, delete, and manage users.
Check out the available gRPC drivers and HTTP helper libraries to find a driver that works for you.
Communication endpoints
TypeDB servers expose two different endpoints for client communication:
TypeDB RPC (gRPC)
The primary communication protocol used by all officially supported language drivers. Based on the TypeDB protocol, it provides:
-
High performance: Efficient binary protocol over HTTP2 bidirectional streams
-
Error handling: Simple API with comprehensive error handling
-
Full feature support: Access to all TypeDB capabilities and operations
-
Connection pooling: Optimized connection management for production use
TypeDB HTTP
A more accessible RESTful API designed for:
-
Web applications: Direct browser-based access, where gRPC is not available
-
Rapid prototyping: Simple curl-based testing and exploration
-
Language flexibility: Use from any language with HTTP client capabilities
-
Integration scenarios: Easier integration with existing HTTP-based workflows
The server’s HTTP endpoint may also be abstracted away behind HTTP driver libraries in your language. These libraries offer a similar interface to the gRPC driver libraries.
While the HTTP endpoint offers greater accessibility, the gRPC drivers provide better performance, simpler APIs, and more sophisticated connection management for production applications. |
Driver usage
All TypeDB-based applications share a common conceptual architecture, regardless of the programming language:
Application
↓
Driver (Language-specific API)
↓
Network Layer (gRPC/HTTP)
↓
TypeDB Server
Internal architecture
TypeDB’s gRPC drivers are implemented as FFI (Foreign Function Interface) wrappers around a shared Rust driver core, enabling the core logic, validation, and error handling to be implemented once and exposed into each language with a thin wrapper.
This means that your driver may be platform (eg. OS and CPU architecture) specific, and make your application non-portable. However, this is typically not a problem:
-
Rust compiles per-platform or is distributed as source.
-
Python applications are usually distributed as source.
-
The Java driver is specifically built to support major platforms to allow shipping built Java applications.
Basic driver workflow
Applications using TypeDB drivers tend to follow a similar pattern:
#!test[reset, reset-after]
from typedb.driver import *
DB_NAME = "my_database"
address = "localhost:1729"
credentials = Credentials("admin", "password")
options = DriverOptions(is_tls_enabled=True, tls_root_ca_path=None)
# 1. Connect to TypeDB
with TypeDB.driver(address, credentials, options) as driver:
# 2. Initialize database with a schema during application startup
try:
driver.databases.create(DB_NAME) # raises already exists exception
finally:
with driver.transaction(DB_NAME, TransactionType.SCHEMA) as tx:
tx.query("define entity person;").resolve()
tx.commit()
# 3. Open a transaction
with driver.transaction(DB_NAME, TransactionType.READ) as tx:
# 4. Execute queries
result = tx.query("match $x label person; fetch { 'entity': $x };").resolve()
# 5. Process results
for answer in result.as_concept_documents():
print(answer)
# 6. Transaction automatically closed, call .commit() to commit and close, or .close() explicitly if not using 'with'
# 7. Driver connection automatically closed, or call .close() explicitly if not using 'with'
Next steps
Now that you understand the overall driver model, explore the detailed concepts:
-
Start with Connections to learn about establishing server connections
-
Learn about Authentication for secure access
-
Understand Transactions for data consistency
-
Use Queries for reading and writing schema and data
-
Best Practices for ideal approaches and some tips and tricks