0
# Client Management
1

2
Client creation and connection management for EdgeDB, supporting both synchronous and asynchronous programming models with lazy connection pooling and automatic connection management.
3

4
## Capabilities
5

6
### Client Factory Functions
7

8
Creates EdgeDB clients with flexible connection options including DSN strings, individual connection parameters, and connection pooling configuration.
9

10
```python { .api }
11
def create_client(
12
    dsn: Optional[str] = None,
13
    *,
14
    max_concurrency: Optional[int] = None,
15
    host: Optional[str] = None,
16
    port: Optional[int] = None,
17
    credentials: Optional[Credentials] = None,
18
    credentials_file: Optional[str] = None,
19
    user: Optional[str] = None,
20
    password: Optional[str] = None,
21
    secret_key: Optional[str] = None,
22
    database: Optional[str] = None,
23
    branch: Optional[str] = None,
24
    tls_ca: Optional[str] = None,
25
    tls_ca_file: Optional[str] = None,
26
    tls_security: Optional[str] = None,
27
    wait_until_available: int = 30,
28
    timeout: int = 10
29
) -> Client:
30
    """
31
    Create a synchronous EdgeDB client.
32
    
33
    Parameters:
34
    - dsn: Connection string in EdgeDB DSN format
35
    - max_concurrency: Maximum number of concurrent connections
36
    - host: Database host (default: localhost)
37
    - port: Database port (default: 5656)
38
    - credentials: Credentials object for authentication
39
    - credentials_file: Path to credentials file
40
    - user: Database user name
41
    - password: Database password
42
    - secret_key: Secret key for authentication
43
    - database: Database name
44
    - branch: Database branch name
45
    - tls_ca: TLS certificate authority
46
    - tls_ca_file: Path to TLS CA file
47
    - tls_security: TLS security mode ('strict', 'no_host_verification', 'insecure')
48
    - wait_until_available: Seconds to wait for server availability
49
    - timeout: Connection timeout in seconds
50
    
51
    Returns:
52
    Client instance for synchronous operations
53
    """
54

55
def create_async_client(
56
    dsn: Optional[str] = None,
57
    *,
58
    max_concurrency: Optional[int] = None,
59
    host: Optional[str] = None,
60
    port: Optional[int] = None,
61
    credentials: Optional[Credentials] = None,
62
    credentials_file: Optional[str] = None,
63
    user: Optional[str] = None,
64
    password: Optional[str] = None,
65
    secret_key: Optional[str] = None,
66
    database: Optional[str] = None,
67
    branch: Optional[str] = None,
68
    tls_ca: Optional[str] = None,
69
    tls_ca_file: Optional[str] = None,
70
    tls_security: Optional[str] = None,
71
    wait_until_available: int = 30,
72
    timeout: int = 10
73
) -> AsyncIOClient:
74
    """
75
    Create an asynchronous EdgeDB client.
76
    
77
    Parameters: Same as create_client()
78
    
79
    Returns:
80
    AsyncIOClient instance for asynchronous operations
81
    """
82
```
83

84
### Client Classes
85

86
The main client classes providing lazy connection pooling and query execution capabilities.
87

88
```python { .api }
89
class Client:
90
    """
91
    Synchronous lazy connection pool client for EdgeDB.
92
    
93
    Provides blocking I/O operations and automatic connection management
94
    with connection pooling and retry logic.
95
    """
96
    
97
    def query(self, query: str, *args, **kwargs) -> List[Any]:
98
        """Execute query and return all results as a list."""
99
    
100
    def query_single(self, query: str, *args, **kwargs) -> Optional[Any]:
101
        """Execute query expecting at most one result."""
102
    
103
    def query_required_single(self, query: str, *args, **kwargs) -> Any:
104
        """Execute query expecting exactly one result."""
105
    
106
    def query_json(self, query: str, *args, **kwargs) -> str:
107
        """Execute query and return results as JSON string."""
108
    
109
    def query_single_json(self, query: str, *args, **kwargs) -> str:
110
        """Execute query expecting at most one result as JSON."""
111
    
112
    def query_required_single_json(self, query: str, *args, **kwargs) -> str:
113
        """Execute query expecting exactly one result as JSON."""
114
    
115
    def execute(self, query: str, *args, **kwargs) -> None:
116
        """Execute command that doesn't return data."""
117
    
118
    def transaction(
119
        self,
120
        *,
121
        options: Optional[TransactionOptions] = None,
122
        retry_options: Optional[RetryOptions] = None
123
    ) -> ContextManager:
124
        """Create a transaction context manager."""
125
    
126
    def ensure_connected(self) -> None:
127
        """Ensure the client is connected to the database."""
128
    
129
    def close(self) -> None:
130
        """Close the client and all connections."""
131

132
class AsyncIOClient:
133
    """
134
    Asynchronous lazy connection pool client for EdgeDB.
135
    
136
    Provides async/await operations and automatic connection management
137
    with connection pooling and retry logic.
138
    """
139
    
140
    async def query(self, query: str, *args, **kwargs) -> List[Any]:
141
        """Execute query and return all results as a list."""
142
    
143
    async def query_single(self, query: str, *args, **kwargs) -> Optional[Any]:
144
        """Execute query expecting at most one result."""
145
    
146
    async def query_required_single(self, query: str, *args, **kwargs) -> Any:
147
        """Execute query expecting exactly one result."""
148
    
149
    async def query_json(self, query: str, *args, **kwargs) -> str:
150
        """Execute query and return results as JSON string."""
151
    
152
    async def query_single_json(self, query: str, *args, **kwargs) -> str:
153
        """Execute query expecting at most one result as JSON."""
154
    
155
    async def query_required_single_json(self, query: str, *args, **kwargs) -> str:
156
        """Execute query expecting exactly one result as JSON."""
157
    
158
    async def execute(self, query: str, *args, **kwargs) -> None:
159
        """Execute command that doesn't return data."""
160
    
161
    def transaction(
162
        self,
163
        *,
164
        options: Optional[TransactionOptions] = None,
165
        retry_options: Optional[RetryOptions] = None
166
    ) -> AsyncContextManager:
167
        """Create an async transaction context manager."""
168
    
169
    async def ensure_connected(self) -> None:
170
        """Ensure the client is connected to the database."""
171
    
172
    async def aclose(self) -> None:
173
        """Close the client and all connections."""
174
```
175

176
### Abstract Executor Interfaces
177

178
Abstract base classes defining the contract for EdgeDB query executors, enabling flexible client implementations.
179

180
```python { .api }
181
class Executor(ABC):
182
    """
183
    Abstract interface for clients that can execute both read-only
184
    and modification queries.
185
    """
186
    
187
    @abstractmethod
188
    def query(self, query: str, *args, **kwargs) -> List[Any]: ...
189
    
190
    @abstractmethod
191
    def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
192
    
193
    @abstractmethod
194
    def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
195
    
196
    @abstractmethod
197
    def query_json(self, query: str, *args, **kwargs) -> str: ...
198
    
199
    @abstractmethod
200
    def query_single_json(self, query: str, *args, **kwargs) -> str: ...
201
    
202
    @abstractmethod
203
    def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
204
    
205
    @abstractmethod
206
    def execute(self, query: str, *args, **kwargs) -> None: ...
207

208
class AsyncIOExecutor(ABC):
209
    """
210
    Abstract interface for asynchronous clients that can execute both
211
    read-only and modification queries.
212
    """
213
    
214
    @abstractmethod
215
    async def query(self, query: str, *args, **kwargs) -> List[Any]: ...
216
    
217
    @abstractmethod
218
    async def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
219
    
220
    @abstractmethod
221
    async def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
222
    
223
    @abstractmethod
224
    async def query_json(self, query: str, *args, **kwargs) -> str: ...
225
    
226
    @abstractmethod
227
    async def query_single_json(self, query: str, *args, **kwargs) -> str: ...
228
    
229
    @abstractmethod
230
    async def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
231
    
232
    @abstractmethod
233
    async def execute(self, query: str, *args, **kwargs) -> None: ...
234

235
class ReadOnlyExecutor(ABC):
236
    """
237
    Abstract interface for clients that can execute read-only queries only.
238
    """
239
    
240
    @abstractmethod
241
    def query(self, query: str, *args, **kwargs) -> List[Any]: ...
242
    
243
    @abstractmethod
244
    def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
245
    
246
    @abstractmethod
247
    def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
248
    
249
    @abstractmethod
250
    def query_json(self, query: str, *args, **kwargs) -> str: ...
251
    
252
    @abstractmethod
253
    def query_single_json(self, query: str, *args, **kwargs) -> str: ...
254
    
255
    @abstractmethod
256
    def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
257

258
class AsyncIOReadOnlyExecutor(ABC):
259
    """
260
    Abstract interface for asynchronous clients that can execute
261
    read-only queries only.
262
    """
263
    
264
    @abstractmethod
265
    async def query(self, query: str, *args, **kwargs) -> List[Any]: ...
266
    
267
    @abstractmethod
268
    async def query_single(self, query: str, *args, **kwargs) -> Optional[Any]: ...
269
    
270
    @abstractmethod
271
    async def query_required_single(self, query: str, *args, **kwargs) -> Any: ...
272
    
273
    @abstractmethod
274
    async def query_json(self, query: str, *args, **kwargs) -> str: ...
275
    
276
    @abstractmethod
277
    async def query_single_json(self, query: str, *args, **kwargs) -> str: ...
278
    
279
    @abstractmethod
280
    async def query_required_single_json(self, query: str, *args, **kwargs) -> str: ...
281
```
282

283
## Usage Examples
284

285
### DSN Connection
286

287
```python
288
import edgedb
289

290
# Connect using DSN
291
client = edgedb.create_client("edgedb://user:pass@localhost:5656/mydb")
292

293
# Async version
294
async_client = edgedb.create_async_client("edgedb://user:pass@localhost:5656/mydb")
295
```
296

297
### Individual Parameters
298

299
```python
300
import edgedb
301

302
# Connect using individual parameters
303
client = edgedb.create_client(
304
    host="localhost",
305
    port=5656,
306
    user="edgedb",
307
    password="secret",
308
    database="mydb",
309
    tls_security="strict"
310
)
311
```
312

313
### Connection Pooling
314

315
```python
316
import edgedb
317

318
# Configure connection pool
319
client = edgedb.create_client(
320
    dsn="edgedb://localhost:5656/mydb",
321
    max_concurrency=20,  # Maximum 20 concurrent connections
322
    timeout=30           # 30 second connection timeout
323
)
324
```
325

326
### Environment Variables
327

328
The client automatically reads from environment variables:
329

330
- `EDGEDB_HOST`
331
- `EDGEDB_PORT`
332
- `EDGEDB_USER`
333
- `EDGEDB_PASSWORD`
334
- `EDGEDB_DATABASE`
335
- `EDGEDB_BRANCH`
336
- `EDGEDB_DSN`
337
- `EDGEDB_CREDENTIALS_FILE`
338

339
```python
340
import edgedb
341

342
# Uses environment variables automatically
343
client = edgedb.create_client()
344
```