0
# Client & Database Management
1

2
Core client operations for connecting to ArangoDB and database management functionality. The ArangoClient serves as the entry point for all database interactions, while StandardDatabase provides database-level operations.
3

4
## Capabilities
5

6
### Client Operations
7

8
Initialize and configure the main ArangoDB client with connection settings and database access.
9

10
```python { .api }
11
class ArangoClient:
12
    def __init__(self, hosts='http://127.0.0.1:8529', host_resolver='fallback',
13
                 resolver_max_tries=None, http_client=None, serializer=None, 
14
                 deserializer=None, verify_override=None, request_timeout=60,
15
                 request_compression=None, response_compression=None):
16
        """
17
        Initialize ArangoDB client.
18
        
19
        Parameters:
20
        - hosts: str or list, ArangoDB server URLs (default: 'http://127.0.0.1:8529')
21
        - host_resolver: str, host resolution strategy ('fallback', 'roundrobin', 'random', 'periodic')
22
        - resolver_max_tries: int, maximum host resolution attempts
23
        - http_client: HTTPClient, custom HTTP client implementation
24
        - serializer: callable, JSON serializer function
25
        - deserializer: callable, JSON deserializer function
26
        - verify_override: Union[bool, str, None], SSL certificate verification override
27
        - request_timeout: Union[int, float, None], request timeout in seconds (default: 60)
28
        - request_compression: RequestCompression, request compression handler
29
        - response_compression: str, response compression type
30
        """
31

32
    def db(self, name='_system', username='root', password='', verify=False,
33
           auth_method='basic', user_token=None, superuser_token=None) -> StandardDatabase:
34
        """
35
        Connect to database and return StandardDatabase API wrapper.
36
        
37
        Parameters:
38
        - name: str, database name (default '_system')
39
        - username: str, username for basic authentication
40
        - password: str, password for basic authentication  
41
        - verify: bool, verify connection by sending test request
42
        - auth_method: str, authentication method ('basic', 'jwt')
43
        - user_token: str, user generated token for user access
44
        - superuser_token: str, user generated token for superuser access
45
        
46
        Returns:
47
        StandardDatabase: Database interface object
48
        """
49

50
    def close(self) -> None:
51
        """Close HTTP sessions."""
52
        
53
    @property
54
    def hosts(self) -> Sequence[str]:
55
        """Return the list of ArangoDB host URLs."""
56

57
    @property  
58
    def version(self) -> str:
59
        """Return the client version."""
60

61
    @property
62
    def request_timeout(self) -> Any:
63
        """Return the request timeout of the http client."""
64
```
65

66
### Database Management
67

68
Database lifecycle operations including creation, deletion, and listing. These operations are performed through a StandardDatabase instance connected to the _system database.
69

70
```python { .api }
71
class StandardDatabase:
72
    def create_database(self, name: str, users=None, replication_factor=None,
73
                        write_concern=None, sharding=None) -> Result[bool]:
74
        """
75
        Create a new database.
76
        
77
        Parameters:
78
        - name: str, database name
79
        - users: Sequence[Json], list of users with access to the new database
80
        - replication_factor: Union[int, str, None], default replication factor for collections
81
        - write_concern: int, default write concern for collections
82
        - sharding: str, sharding method for new collections ('flexible', 'single')
83
        
84
        Returns:
85
        Result[bool]: True if database was created successfully
86
        """
87

88
    def delete_database(self, name: str, ignore_missing: bool = False) -> Result[bool]:
89
        """
90
        Delete a database.
91
        
92
        Parameters:
93
        - name: str, database name to delete
94
        - ignore_missing: bool, do not raise exception if database does not exist
95
        
96
        Returns:
97
        Result[bool]: True if database was deleted successfully
98
        """
99

100
    def databases(self) -> Result[List[str]]:
101
        """
102
        Return the names of all databases.
103
        
104
        Returns:
105
        Result[List[str]]: List of database names
106
        """
107

108
    def databases_accessible_to_user(self) -> Result[List[str]]:
109
        """
110
        Return names of databases accessible by the current user.
111
        
112
        Returns:
113
        Result[List[str]]: List of accessible database names
114
        """
115

116
    def has_database(self, name: str) -> Result[bool]:
117
        """
118
        Check if a database exists.
119
        
120
        Parameters:
121
        - name: str, database name
122
        
123
        Returns:
124
        Result[bool]: True if database exists
125
        """
126
```
127

128
### Server Information
129

130
Access server status, version information, statistics, and engine details for monitoring and debugging.
131

132
```python { .api }
133
def version(self, details: bool = False) -> Result[Json]:
134
    """
135
    Return ArangoDB server version information.
136
    
137
    Parameters:
138
    - details: bool, return detailed version information
139
    
140
    Returns:
141
    Result[Json]: Version information dictionary
142
    """
143

144
def status(self) -> Result[Json]:
145
    """
146
    Return ArangoDB server status information.
147
    
148
    Returns:
149
    Result[Json]: Server status dictionary
150
    """
151

152
def statistics(self, description: bool = False) -> Result[Json]:
153
    """
154
    Return server statistics.
155
    
156
    Parameters:
157
    - description: bool, return description of each figure
158
    
159
    Returns:
160
    Result[Json]: Server statistics dictionary
161
    """
162

163
def role(self) -> Result[str]:
164
    """
165
    Return server role.
166
    
167
    Returns:
168
    Result[str]: Server role ('SINGLE', 'COORDINATOR', 'PRIMARY', 'SECONDARY', 'AGENT', 'UNDEFINED')
169
    """
170

171
def engine(self) -> Result[Json]:
172
    """
173
    Return storage engine information.
174
    
175
    Returns:
176
    Result[Json]: Storage engine details dictionary
177
    """
178
```
179

180
### Cluster Operations
181

182
Manage and monitor ArangoDB clusters through the cluster property. These operations are available when connected to a cluster.
183

184
```python { .api }
185
@property
186
def cluster(self) -> Cluster:
187
    """Return cluster API wrapper."""
188

189
class Cluster:
190
    def server_id(self) -> Result[str]:
191
        """Return the server ID."""
192

193
    def server_role(self) -> Result[str]:
194
        """Return the server role."""
195

196
    def server_version(self, server_id: str) -> Result[str]:
197
        """Return version of given server."""
198

199
    def server_engine(self, server_id: str) -> Result[Json]:
200
        """Return engine details of given server."""
201

202
    def health(self) -> Result[Json]:
203
        """Return cluster health information."""
204

205
    def endpoints(self) -> Result[Json]:
206
        """Return cluster endpoints information."""
207
```
208

209
### Database Properties
210

211
Core database properties and connection information.
212

213
```python { .api }
214
@property
215
def name(self) -> str:
216
    """Return database name."""
217
    
218
@property
219
def username(self) -> str:
220
    """Return username."""
221
    
222
@property 
223
def context(self) -> str:
224
    """Return database context string."""
225
```
226

227
## Usage Examples
228

229
### Basic Client Setup
230

231
```python
232
from arango import ArangoClient
233

234
# Single server
235
client = ArangoClient(hosts='http://localhost:8529')
236

237
# Multiple servers with load balancing
238
client = ArangoClient(
239
    hosts=['http://server1:8529', 'http://server2:8529'],
240
    host_resolver='roundrobin'
241
)
242

243
# Custom timeout and compression
244
client = ArangoClient(
245
    hosts='http://localhost:8529',
246
    request_timeout=120,
247
    verify_override=False
248
)
249
```
250

251
### Database Management
252

253
```python
254
# Connect to system database (required for database management)
255
sys_db = client.db('_system', username='root', password='password')
256

257
# Create new database with users
258
users = [
259
    {'username': 'admin', 'password': 'secret', 'active': True},
260
    {'username': 'guest', 'password': 'guest', 'active': True}
261
]
262
sys_db.create_database('myapp', users=users)
263

264
# Connect to application database
265
app_db = client.db('myapp', username='admin', password='secret')
266

267
# List all databases (requires _system database connection)
268
db_list = sys_db.databases()
269
print(db_list)  # ['_system', 'myapp']
270

271
# Check if database exists
272
if sys_db.has_database('myapp'):
273
    print("Database exists")
274

275
# Clean up
276
sys_db.delete_database('myapp')
277
```
278

279
### Server Monitoring
280

281
```python
282
# Connect to database
283
db = client.db('_system', username='root', password='password')
284

285
# Get server information
286
version_info = db.version(details=True)
287
print(f"ArangoDB Version: {version_info['version']}")
288

289
server_stats = db.statistics()
290
print(f"Server uptime: {server_stats.get('uptime', 'N/A')}")
291

292
# Check server role
293
server_role = db.role()
294
print(f"Server role: {server_role}")
295

296
# Engine information
297
engine_info = db.engine()
298
print(f"Storage engine: {engine_info['name']}")
299
```
300

301
### Cluster Operations
302

303
```python
304
# Connect to cluster coordinator
305
db = client.db('_system', username='root', password='password')
306

307
# Check if running in cluster mode
308
if db.role() == 'COORDINATOR':
309
    cluster = db.cluster()
310
    
311
    # Get cluster health
312
    health = cluster.health()
313
    print(f"Cluster health: {health}")
314
    
315
    # Get cluster endpoints
316
    endpoints = cluster.endpoints()
317
    print(f"Cluster endpoints: {endpoints}")
318
    
319
    # Get server information
320
    server_id = cluster.server_id()
321
    server_role = cluster.server_role()
322
    print(f"Server ID: {server_id}, Role: {server_role}")
323
```
324

325
### Authentication Methods
326

327
```python
328
# Basic authentication (default)
329
db = client.db('mydb', username='user', password='pass', auth_method='basic')
330

331
# JWT authentication
332
db = client.db('mydb', username='user', password='pass', auth_method='jwt')
333

334
# User token authentication
335
db = client.db('mydb', user_token='your_jwt_token_here')
336

337
# Superuser token authentication
338
db = client.db('mydb', superuser_token='your_superuser_token_here')
339

340
# Verify connection
341
db = client.db('mydb', username='user', password='pass', verify=True)
342
```