0
# Connection Management
1

2
Database connection establishment, configuration, and lifecycle management with support for various authentication mechanisms and connection parameters.
3

4
## Capabilities
5

6
### Connection Creation
7

8
Establishes connections to Phoenix query server with comprehensive authentication and configuration support.
9

10
```python { .api }
11
def connect(url, max_retries=None, auth=None, authentication=None,
12
           avatica_user=None, avatica_password=None, truststore=None,
13
           verify=None, do_as=None, user=None, password=None,
14
           extra_headers=None, **kwargs):
15
    """
16
    Connects to a Phoenix query server.
17

18
    Parameters:
19
    - url (str): URL to Phoenix query server (e.g., 'http://localhost:8765/')
20
    - autocommit (bool): Switch connection to autocommit mode (default: False)
21
    - readonly (bool): Switch connection to readonly mode (default: False)
22
    - max_retries (int): Maximum number of retries for connection errors
23
    - cursor_factory: Default cursor factory class (default: Cursor)
24
    - auth: Authentication configuration object (requests.auth compatible)
25
    - authentication (str): Authentication mechanism ('BASIC', 'DIGEST', 'SPNEGO', 'NONE')
26
    - avatica_user (str): Username for BASIC/DIGEST authentication
27
    - avatica_password (str): Password for BASIC/DIGEST authentication
28
    - truststore (str): Path to PEM file for server certificate verification
29
    - verify: Certificate verification configuration (passed to requests)
30
    - do_as (str): Username to impersonate (sets Hadoop doAs URL parameter)
31
    - user (str): Alias for avatica_user (BASIC/DIGEST) or do_as (SPNEGO/NONE)
32
    - password (str): Alias for avatica_password
33
    - extra_headers (dict): Additional HTTP headers as dictionary
34

35
    Returns:
36
    Connection: Database connection object
37

38
    Raises:
39
    InterfaceError: Connection interface problems
40
    OperationalError: Connection establishment failures
41
    """
42
```
43

44
Usage examples:
45

46
```python
47
# Basic connection
48
conn = phoenixdb.connect('http://localhost:8765/')
49

50
# With autocommit
51
conn = phoenixdb.connect('http://localhost:8765/', autocommit=True)
52

53
# With authentication
54
conn = phoenixdb.connect('http://localhost:8765/',
55
                        authentication='BASIC',
56
                        avatica_user='username',
57
                        avatica_password='password')
58

59
# With SPNEGO/Kerberos
60
conn = phoenixdb.connect('https://localhost:8765/',
61
                        authentication='SPNEGO',
62
                        truststore='/path/to/truststore.pem')
63

64
# With custom headers and retry configuration
65
conn = phoenixdb.connect('http://localhost:8765/',
66
                        max_retries=3,
67
                        extra_headers={'User-Agent': 'MyApp/1.0'})
68
```
69

70
### Connection Class
71

72
Manages database connection state and provides access to cursors and metadata.
73

74
```python { .api }
75
class Connection:
76
    """Database connection object."""
77

78
    def __init__(self, client, cursor_factory=None, **kwargs): ...
79

80
    def open(self):
81
        """Opens the connection."""
82

83
    def close(self):
84
        """
85
        Closes the connection and all associated cursors.
86
        No further operations allowed after closing.
87
        """
88

89
    def commit(self):
90
        """Commits the current transaction."""
91

92
    def rollback(self):
93
        """Rolls back the current transaction."""
94

95
    def cursor(self, cursor_factory=None):
96
        """
97
        Creates a new cursor.
98

99
        Parameters:
100
        - cursor_factory: Cursor class to use (default: self.cursor_factory)
101

102
        Returns:
103
        Cursor: New cursor object
104
        """
105

106
    def set_session(self, **props):
107
        """
108
        Sets connection properties.
109

110
        Parameters:
111
        - autocommit (bool): Switch to autocommit mode
112
        - readonly (bool): Switch to readonly mode
113
        """
114

115
    def meta(self):
116
        """
117
        Creates a metadata interface.
118

119
        Returns:
120
        Meta: Database metadata object
121
        """
122
```
123

124
### Connection Properties
125

126
```python { .api }
127
class Connection:
128
    @property
129
    def closed(self):
130
        """Read-only boolean indicating if connection is closed."""
131

132
    @property
133
    def cursor_factory(self):
134
        """Default cursor factory used by cursor() method."""
135

136
    @cursor_factory.setter
137
    def cursor_factory(self, value): ...
138

139
    @property
140
    def autocommit(self):
141
        """Read/write boolean for autocommit mode."""
142

143
    @autocommit.setter
144
    def autocommit(self, value): ...
145

146
    @property
147
    def readonly(self):
148
        """Read/write boolean for readonly mode."""
149

150
    @readonly.setter
151
    def readonly(self, value): ...
152

153
    @property
154
    def transactionisolation(self):
155
        """Read/write transaction isolation level."""
156

157
    @transactionisolation.setter
158
    def transactionisolation(self, value): ...
159
```
160

161
### Context Manager Support
162

163
Connections support Python context manager protocol for automatic resource cleanup.
164

165
```python { .api }
166
class Connection:
167
    def __enter__(self):
168
        """Context manager entry."""
169
        return self
170

171
    def __exit__(self, exc_type, exc_value, traceback):
172
        """Context manager exit with automatic connection closing."""
173
```
174

175
Usage:
176

177
```python
178
with phoenixdb.connect('http://localhost:8765/') as conn:
179
    # Connection automatically closed when exiting block
180
    cursor = conn.cursor()
181
    cursor.execute("SELECT * FROM table")
182
    results = cursor.fetchall()
183
```
184

185
## Authentication Mechanisms
186

187
### BASIC Authentication
188

189
```python
190
conn = phoenixdb.connect('http://localhost:8765/',
191
                        authentication='BASIC',
192
                        avatica_user='username',
193
                        avatica_password='password')
194
```
195

196
### DIGEST Authentication
197

198
```python
199
conn = phoenixdb.connect('http://localhost:8765/',
200
                        authentication='DIGEST',
201
                        avatica_user='username',
202
                        avatica_password='password')
203
```
204

205
### SPNEGO/Kerberos Authentication
206

207
```python
208
# Requires prior kinit or system Kerberos configuration
209
conn = phoenixdb.connect('https://localhost:8765/',
210
                        authentication='SPNEGO')
211
```
212

213
### Custom Authentication
214

215
```python
216
from requests.auth import HTTPBasicAuth
217

218
# Using requests.auth objects directly
219
auth = HTTPBasicAuth('username', 'password')
220
conn = phoenixdb.connect('http://localhost:8765/', auth=auth)
221
```
222

223
## Connection Configuration
224

225
### SSL/TLS Configuration
226

227
```python
228
# Disable certificate verification
229
conn = phoenixdb.connect('https://localhost:8765/', verify=False)
230

231
# Use custom truststore
232
conn = phoenixdb.connect('https://localhost:8765/',
233
                        truststore='/path/to/truststore.pem')
234
```
235

236
### URL Parameters
237

238
Connection parameters can be embedded in the URL:
239

240
```python
241
url = 'http://localhost:8765/?authentication=BASIC&avatica_user=user&truststore=/path/to/cert.pem'
242
conn = phoenixdb.connect(url)
243
```
244

245
### Impersonation
246

247
```python
248
# Impersonate another user (Hadoop doAs)
249
conn = phoenixdb.connect('http://localhost:8765/', do_as='other_user')
250

251
# Using user parameter (maps to do_as for SPNEGO/NONE auth)
252
conn = phoenixdb.connect('http://localhost:8765/',
253
                        authentication='SPNEGO',
254
                        user='other_user')
255
```