0
# Driver and Connection Management
1
2
Core connection functionality for establishing and managing connections to YDB clusters, including driver configuration, endpoint discovery, credential management, and connection lifecycle.
3
4
## Capabilities
5
6
### Driver Creation and Configuration
7
8
The Driver is the main entry point for connecting to YDB. It manages connection pooling, endpoint discovery, and provides the foundation for all database operations.
9
10
```python { .api }
11
class Driver:
12
def __init__(
13
self,
14
endpoint: str,
15
database: str,
16
credentials: Credentials = None,
17
compression: int = None,
18
root_certificates: bytes = None,
19
**kwargs
20
):
21
"""
22
Create a YDB driver instance.
23
24
Args:
25
endpoint (str): YDB endpoint URL (e.g., "grpc://localhost:2136")
26
database (str): Database path (e.g., "/local")
27
credentials (Credentials, optional): Authentication credentials
28
compression (int, optional): gRPC compression method
29
root_certificates (bytes, optional): TLS root certificates
30
"""
31
32
def wait(self, fail_fast: bool = True, timeout: float = None) -> bool:
33
"""
34
Wait for driver to become ready.
35
36
Args:
37
fail_fast (bool): Raise exception on first error
38
timeout (float, optional): Timeout in seconds
39
40
Returns:
41
bool: True if driver is ready, False on timeout
42
"""
43
44
def stop(self, timeout: float = None):
45
"""
46
Stop the driver and close connections.
47
48
Args:
49
timeout (float, optional): Shutdown timeout in seconds
50
"""
51
52
@property
53
def discovery_debug_details(self) -> str:
54
"""Get endpoint discovery debug information."""
55
```
56
57
### Driver Configuration Object
58
59
Provides structured configuration for driver creation with validation and default values.
60
61
```python { .api }
62
class DriverConfig:
63
def __init__(
64
self,
65
endpoint: str,
66
database: str,
67
credentials: Credentials = None,
68
compression: int = None,
69
root_certificates: bytes = None,
70
**kwargs
71
):
72
"""
73
Driver configuration container.
74
75
Args:
76
endpoint (str): YDB endpoint URL
77
database (str): Database path
78
credentials (Credentials, optional): Authentication credentials
79
compression (int, optional): gRPC compression method
80
root_certificates (bytes, optional): TLS root certificates
81
"""
82
```
83
84
### Driver Factory Functions
85
86
Convenience functions for creating drivers from various sources.
87
88
```python { .api }
89
def construct_driver(config: DriverConfig) -> Driver:
90
"""
91
Create driver from configuration object.
92
93
Args:
94
config (DriverConfig): Driver configuration
95
96
Returns:
97
Driver: Configured YDB driver
98
"""
99
100
def construct_driver_from_string(connection_string: str, **kwargs) -> Driver:
101
"""
102
Create driver from connection string.
103
104
Args:
105
connection_string (str): YDB connection string
106
**kwargs: Additional driver parameters
107
108
Returns:
109
Driver: Configured YDB driver
110
"""
111
```
112
113
### RPC Compression Options
114
115
Configure gRPC compression for network efficiency.
116
117
```python { .api }
118
class RPCCompression:
119
"""gRPC compression methods."""
120
NoCompression: int # No compression
121
Deflate: int # Deflate compression
122
Gzip: int # Gzip compression
123
```
124
125
## Usage Examples
126
127
### Basic Driver Setup
128
129
```python
130
import ydb
131
132
# Create driver with minimal configuration
133
driver = ydb.Driver(
134
endpoint="grpc://localhost:2136",
135
database="/local",
136
credentials=ydb.AnonymousCredentials()
137
)
138
139
# Wait for driver to be ready
140
if not driver.wait(timeout=10):
141
raise RuntimeError("Driver failed to initialize")
142
143
# Use driver for operations...
144
145
# Clean shutdown
146
driver.stop()
147
```
148
149
### Advanced Driver Configuration
150
151
```python
152
import ydb
153
154
# Configure driver with custom settings
155
config = ydb.DriverConfig(
156
endpoint="grpcs://ydb.example.com:2135",
157
database="/production/mydb",
158
credentials=ydb.StaticCredentials("your-token"),
159
compression=ydb.RPCCompression.Gzip,
160
root_certificates=open("ca.pem", "rb").read()
161
)
162
163
driver = ydb.construct_driver(config)
164
driver.wait(fail_fast=True, timeout=30)
165
166
# Driver is ready for use
167
print(f"Connected to: {driver.discovery_debug_details}")
168
```
169
170
### Connection String Usage
171
172
```python
173
import ydb
174
175
# Create driver from connection string
176
connection_string = "grpc://user:pass@localhost:2136/local?compression=gzip"
177
driver = ydb.construct_driver_from_string(connection_string)
178
179
driver.wait(fail_fast=True)
180
# Driver ready for operations
181
```
182
183
### Context Manager Pattern
184
185
```python
186
import ydb
187
from contextlib import closing
188
189
# Ensure proper cleanup
190
with closing(ydb.Driver(
191
endpoint="grpc://localhost:2136",
192
database="/local",
193
credentials=ydb.AnonymousCredentials()
194
)) as driver:
195
driver.wait(fail_fast=True, timeout=10)
196
197
# Use driver for operations
198
session_pool = ydb.SessionPool(driver)
199
# ... perform operations ...
200
session_pool.stop()
201
202
# Driver automatically stopped
203
```
204
205
## Types
206
207
```python { .api }
208
from typing import Optional, Union
209
210
# Type aliases used in driver operations
211
ConnectionString = str
212
Endpoint = str
213
DatabasePath = str
214
Timeout = Optional[float]
215
```