0
# EdgeDB Python Driver
1

2
The official Python driver for EdgeDB, a next-generation graph-relational database. Provides both blocking IO and asyncio implementations for connecting to and interacting with EdgeDB databases, enabling developers to execute EdgeQL queries, manage database connections, handle transactions, and work with EdgeDB's advanced type system.
3

4
## Package Information
5

6
- **Package Name**: edgedb
7
- **Language**: Python
8
- **Installation**: `pip install edgedb`
9
- **Python Version**: >= 3.8
10

11
## Core Imports
12

13
```python
14
import edgedb
15
```
16

17
Common client imports:
18

19
```python
20
from edgedb import create_client, create_async_client
21
from edgedb import Client, AsyncIOClient
22
```
23

24
## Basic Usage
25

26
### Synchronous Client
27

28
```python
29
import edgedb
30

31
# Create a client
32
client = edgedb.create_client()
33

34
# Query for multiple results
35
users = client.query(
36
    "SELECT User { name, email } FILTER .name ILIKE $pattern",
37
    pattern="John%"
38
)
39

40
# Query for a single result
41
user = client.query_single(
42
    "SELECT User { name, email } FILTER .id = <uuid>$id",
43
    id="123e4567-e89b-12d3-a456-426614174000"
44
)
45

46
# Execute a command
47
client.execute(
48
    "INSERT User { name := $name, email := $email }",
49
    name="John Doe",
50
    email="john@example.com"
51
)
52

53
# Use transactions
54
with client.transaction() as tx:
55
    tx.execute("INSERT User { name := 'Alice' }")
56
    tx.execute("INSERT User { name := 'Bob' }")
57
    # Automatically commits or rolls back
58

59
client.close()
60
```
61

62
### Asynchronous Client
63

64
```python
65
import asyncio
66
import edgedb
67

68
async def main():
69
    # Create an async client
70
    client = edgedb.create_async_client()
71
    
72
    # Query for multiple results
73
    users = await client.query(
74
        "SELECT User { name, email } FILTER .name ILIKE $pattern",
75
        pattern="John%"
76
    )
77
    
78
    # Query for a single result
79
    user = await client.query_single(
80
        "SELECT User { name, email } FILTER .id = <uuid>$id",
81
        id="123e4567-e89b-12d3-a456-426614174000"
82
    )
83
    
84
    # Execute a command
85
    await client.execute(
86
        "INSERT User { name := $name, email := $email }",
87
        name="John Doe",
88
        email="john@example.com"
89
    )
90
    
91
    # Use transactions
92
    async with client.transaction() as tx:
93
        await tx.execute("INSERT User { name := 'Alice' }")
94
        await tx.execute("INSERT User { name := 'Bob' }")
95
        # Automatically commits or rolls back
96
    
97
    await client.aclose()
98

99
asyncio.run(main())
100
```
101

102
## Architecture
103

104
The EdgeDB Python driver uses a layered architecture:
105

106
- **Client Layer**: High-level `Client` and `AsyncIOClient` classes providing lazy connection pooling
107
- **Executor Layer**: Abstract interfaces (`Executor`, `AsyncIOExecutor`) defining query execution contracts
108
- **Connection Layer**: Low-level connection management with automatic retry and connection pooling
109
- **Protocol Layer**: Binary protocol implementation for efficient communication with EdgeDB
110
- **Type System**: Complete EdgeDB type mapping with Python-native representations
111
- **Error Handling**: Comprehensive exception hierarchy mapping EdgeDB server errors
112

113
## Capabilities
114

115
### Client Creation and Management
116

117
Client factory functions and connection management for both synchronous and asynchronous programming models.
118

119
```python { .api }
120
def create_client(
121
    dsn: Optional[str] = None,
122
    *,
123
    max_concurrency: Optional[int] = None,
124
    host: Optional[str] = None,
125
    port: Optional[int] = None,
126
    credentials: Optional[Credentials] = None,
127
    # ... additional connection parameters
128
) -> Client: ...
129

130
def create_async_client(
131
    dsn: Optional[str] = None,
132
    *,
133
    max_concurrency: Optional[int] = None,
134
    host: Optional[str] = None,
135
    port: Optional[int] = None,
136
    credentials: Optional[Credentials] = None,
137
    # ... additional connection parameters
138
) -> AsyncIOClient: ...
139
```
140

141
[Client Management](./client-management.md)
142

143
### Query Execution
144

145
Core query execution methods for EdgeQL queries with support for different result cardinalities and JSON output formats.
146

147
```python { .api }
148
def query(query: str, *args, **kwargs) -> List[Any]: ...
149
def query_single(query: str, *args, **kwargs) -> Optional[Any]: ...
150
def query_required_single(query: str, *args, **kwargs) -> Any: ...
151
def query_json(query: str, *args, **kwargs) -> str: ...
152
def execute(query: str, *args, **kwargs) -> None: ...
153
```
154

155
[Query Execution](./query-execution.md)
156

157
### Data Types
158

159
EdgeDB data type representations in Python, including scalar types, collections, and custom types.
160

161
```python { .api }
162
class Object: ...
163
class Set(list): ...
164
class Array(list): ...
165
class NamedTuple(tuple): ...
166
class EnumValue: ...
167
class RelativeDuration: ...
168
class Range: ...
169
class MultiRange: ...
170
```
171

172
[Data Types](./data-types.md)
173

174
### Transaction Management
175

176
Transaction handling with context managers, retry logic, and isolation level control.
177

178
```python { .api }
179
class TransactionOptions:
180
    def __init__(
181
        self,
182
        isolation: IsolationLevel = IsolationLevel.Serializable,
183
        readonly: bool = False,
184
        deferrable: bool = False
185
    ): ...
186

187
def transaction(
188
    *,
189
    options: Optional[TransactionOptions] = None,
190
    retry_options: Optional[RetryOptions] = None
191
) -> ContextManager: ...
192
```
193

194
[Transaction Management](./transaction-management.md)
195

196
### Configuration and Options
197

198
Client configuration options, retry policies, session state management, and connection parameters.
199

200
```python { .api }
201
class RetryOptions:
202
    def __init__(self, attempts: int, backoff: Callable[[int], float]): ...
203

204
class State:
205
    def with_default_module(self, module: str) -> State: ...
206
    def with_module_aliases(self, **aliases: str) -> State: ...
207
    def with_config(self, **config: Any) -> State: ...
208
    def with_globals(self, **globals: Any) -> State: ...
209
```
210

211
[Configuration and Options](./configuration-options.md)
212

213
### Error Handling
214

215
Comprehensive exception hierarchy representing all EdgeDB server errors and client-side issues.
216

217
```python { .api }
218
class EdgeDBError(Exception):
219
    def has_tag(self, tag: ErrorTag) -> bool: ...
220
    def get_code(self) -> int: ...
221

222
class QueryError(EdgeDBError): ...
223
class TransactionError(EdgeDBError): ...
224
class ClientError(EdgeDBError): ...
225
```
226

227
[Error Handling](./error-handling.md)
228

229
### Schema Introspection
230

231
Schema introspection capabilities for examining database structure and type information.
232

233
```python { .api }
234
class DescribeContext:
235
    query: str
236
    state: Optional[State]
237
    inject_type_names: bool
238
    output_format: OutputFormat
239
    expect_one: bool
240

241
class DescribeResult:
242
    input_type: Optional[AnyType]
243
    output_type: Optional[AnyType]
244
    output_cardinality: Cardinality
245
    capabilities: int
246
```
247

248
[Schema Introspection](./schema-introspection.md)
249

250
### AI Integration
251

252
EdgeDB AI capabilities for RAG (retrieval-augmented generation) queries and embeddings generation.
253

254
```python { .api }
255
def create_ai(client: Client, **kwargs) -> EdgeDBAI: ...
256
def create_async_ai(client: AsyncIOClient, **kwargs) -> AsyncEdgeDBAI: ...
257

258
class EdgeDBAI:
259
    def query_rag(self, message: str, context: Optional[QueryContext] = None) -> str: ...
260
    def stream_rag(self, message: str, context: Optional[QueryContext] = None) -> Iterator[str]: ...
261
    def generate_embeddings(self, *inputs: str, model: str) -> List[float]: ...
262
```
263

264
[AI Integration](./ai-integration.md)
265

266
## Types
267

268
```python { .api }
269
# Core data types
270
Tuple = tuple
271
NamedTuple = collections.namedtuple
272
Set = list
273
Array = list
274
EnumValue = object
275
RelativeDuration = object
276
DateDuration = object
277
ConfigMemory = object
278
Object = object
279
Link = object
280
LinkSet = object
281
Range = object
282
MultiRange = object
283

284
# Client types
285
class Client:
286
    def query(self, query: str, *args, **kwargs) -> List[Any]: ...
287
    def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
288
    def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
289
    def query_json(self, query: str, *args, **kwargs) -> str: ...
290
    def query_single_json(self, query: str, *args, **kwargs) -> str: ...
291
    def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
292
    def execute(self, query: str, *args, **kwargs) -> None: ...
293
    def transaction(self, **kwargs) -> ContextManager: ...
294
    def ensure_connected(self) -> None: ...
295
    def close(self) -> None: ...
296

297
class AsyncIOClient:
298
    async def query(self, query: str, *args, **kwargs) -> List[Any]: ...
299
    async def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
300
    async def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
301
    async def query_json(self, query: str, *args, **kwargs) -> str: ...
302
    async def query_single_json(self, query: str, *args, **kwargs) -> str: ...
303
    async def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
304
    async def execute(self, query: str, *args, **kwargs) -> None: ...
305
    def transaction(self, **kwargs) -> AsyncContextManager: ...
306
    async def ensure_connected(self) -> None: ...
307
    async def aclose(self) -> None: ...
308

309
# Enums
310
class Cardinality(Enum):
311
    NO_RESULT = "n"
312
    AT_MOST_ONE = "?"
313
    ONE = "1"
314
    MANY = "*"
315
    AT_LEAST_ONE = "+"
316
    
317
    def is_single(self) -> bool: ...
318
    def is_multi(self) -> bool: ...
319

320
class IsolationLevel:
321
    Serializable = "SERIALIZABLE"
322

323
class ElementKind(Enum):
324
    LINK = "link"
325
    PROPERTY = "property"
326
    LINK_PROPERTY = "linkprop"
327
```