0
# Arctic Connection Management
1

2
Core functionality for connecting to MongoDB, managing libraries, and handling authentication. Provides the main entry point for all Arctic operations including library lifecycle management and quota control.
3

4
## Capabilities
5

6
### Arctic Class
7

8
Main Arctic database connection and library manager providing centralized access to MongoDB-backed time series storage.
9

10
```python { .api }
11
class Arctic:
12
    """
13
    Top-level Arctic connection managing MongoDB databases and libraries.
14
    
15
    Each Arctic instance owns arctic_<user> databases in MongoDB, containing
16
    one or more ArcticLibrary instances with implementation-specific functionality.
17
    """
18
    
19
    def __init__(self, mongo_host, app_name='arctic', allow_secondary=False,
20
                 socketTimeoutMS=600000, connectTimeoutMS=2000,
21
                 serverSelectionTimeoutMS=30000, **kwargs):
22
        """
23
        Construct Arctic datastore connection.
24
        
25
        Parameters:
26
        - mongo_host: MongoDB hostname, alias, or pymongo connection
27
        - app_name: Application name for authentication (default: 'arctic')
28
        - allow_secondary: Allow reads from secondary cluster members
29
        - socketTimeoutMS: Socket timeout in milliseconds (default: 10 minutes)
30
        - connectTimeoutMS: Connection timeout in milliseconds (default: 2 seconds)
31
        - serverSelectionTimeoutMS: Server selection timeout (default: 30 seconds)
32
        - **kwargs: Additional PyMongo MongoClient arguments (SSL, etc.)
33
        """
34
```
35

36
### Library Management
37

38
Operations for creating, listing, and managing Arctic libraries within the MongoDB cluster.
39

40
```python { .api }
41
def list_libraries(self, newer_than_secs=None):
42
    """
43
    List all available libraries.
44
    
45
    Parameters:
46
    - newer_than_secs: Only return libraries modified within this time period
47
    
48
    Returns:
49
    List of library names
50
    """
51

52
def library_exists(self, library):
53
    """
54
    Check if library exists.
55
    
56
    Parameters:
57
    - library: Library name to check
58
    
59
    Returns:
60
    bool: True if library exists
61
    """
62

63
def initialize_library(self, library, lib_type=VERSION_STORE, **kwargs):
64
    """
65
    Create new Arctic library with specified type.
66
    
67
    Parameters:
68
    - library: Library name to create
69
    - lib_type: Storage engine type (VERSION_STORE, TICK_STORE, CHUNK_STORE, etc.)
70
    - **kwargs: Library-specific initialization parameters
71
    
72
    Raises:
73
    - ArcticException: If library already exists or initialization fails
74
    """
75

76
def get_library(self, library):
77
    """
78
    Get ArcticLibraryBinding instance for library operations.
79
    
80
    Parameters:
81
    - library: Library name
82
    
83
    Returns:
84
    ArcticLibraryBinding: Library interface
85
    
86
    Raises:
87
    - LibraryNotFoundException: If library doesn't exist
88
    """
89

90
def delete_library(self, library):
91
    """
92
    Delete library and all its data permanently.
93
    
94
    Parameters:
95
    - library: Library name to delete
96
    
97
    Raises:
98
    - LibraryNotFoundException: If library doesn't exist
99
    """
100

101
def rename_library(self, from_lib, to_lib):
102
    """
103
    Rename existing library.
104
    
105
    Parameters:
106
    - from_lib: Current library name
107
    - to_lib: New library name
108
    
109
    Raises:
110
    - LibraryNotFoundException: If source library doesn't exist
111
    - ArcticException: If target library already exists
112
    """
113

114
def get_library_type(self, lib):
115
    """
116
    Get the storage engine type of specified library.
117
    
118
    Parameters:
119
    - lib: Library name
120
    
121
    Returns:
122
    str: Library type (VERSION_STORE, TICK_STORE, etc.)
123
    """
124
```
125

126
### Quota Management
127

128
Storage quota management for controlling disk usage and preventing runaway storage growth.
129

130
```python { .api }
131
def set_quota(self, library, quota):
132
    """
133
    Set storage quota in bytes for library.
134
    
135
    Parameters:
136
    - library: Library name
137
    - quota: Quota in bytes (0 = unlimited)
138
    """
139

140
def get_quota(self, library):
141
    """
142
    Get current quota for library.
143
    
144
    Parameters:
145
    - library: Library name
146
    
147
    Returns:
148
    int: Current quota in bytes (0 = unlimited)
149
    """
150

151
def check_quota(self, library):
152
    """
153
    Check quota status and usage for library.
154
    
155
    Parameters:
156
    - library: Library name
157
    
158
    Returns:
159
    dict: Quota information including usage and limits
160
    """
161
```
162

163
### Connection Management
164

165
Methods for managing MongoDB connections and caching behavior.
166

167
```python { .api }
168
def reset(self):
169
    """
170
    Reset MongoDB connections.
171
    
172
    Useful after process forking to ensure clean connection state.
173
    """
174

175
def is_caching_enabled(self):
176
    """
177
    Check if library metadata caching is enabled.
178
    
179
    Returns:
180
    bool: True if caching is active
181
    """
182

183
def reload_cache(self):
184
    """
185
    Reload the library metadata cache.
186
    
187
    Forces refresh of cached library information.
188
    """
189
```
190

191
### Special Methods
192

193
Convenience methods for library access and Python integration.
194

195
```python { .api }
196
def __getitem__(self, key):
197
    """
198
    Access library using bracket notation: arctic[library_name].
199
    
200
    Parameters:
201
    - key: Library name
202
    
203
    Returns:
204
    ArcticLibraryBinding: Library interface
205
    """
206
```
207

208
### Library Type Registration
209

210
Register custom storage engine types with Arctic.
211

212
```python { .api }
213
def register_library_type(name, type_):
214
    """
215
    Register a custom Arctic library type handler.
216
    
217
    Parameters:
218
    - name: Unique name for the library type
219
    - type_: Library class implementing the storage engine interface
220
    
221
    Raises:
222
    - ArcticException: If library type name already registered
223
    
224
    Example:
225
    register_library_type('CUSTOM_STORE', MyCustomStore)
226
    """
227
```
228

229
## ArcticLibraryBinding Class
230

231
Library-specific interface providing quota management, metadata operations, and store access.
232

233
```python { .api }
234
class ArcticLibraryBinding:
235
    """
236
    Library-specific interface for Arctic operations.
237
    
238
    Provides access to library metadata, quota management, and the underlying
239
    storage implementation.
240
    """
241
    
242
    def get_name(self):
243
        """
244
        Get full qualified library name.
245
        
246
        Returns:
247
        str: Complete library name including database prefix
248
        """
249

250
    def get_top_level_collection(self):
251
        """
252
        Get MongoDB collection reference for this library.
253
        
254
        Returns:
255
        pymongo.Collection: MongoDB collection object
256
        """
257

258
    def get_library_type(self):
259
        """
260
        Get library storage engine type.
261
        
262
        Returns:
263
        str: Library type string
264
        """
265

266
    def set_library_type(self, lib_type):
267
        """
268
        Set library storage engine type.
269
        
270
        Parameters:
271
        - lib_type: New library type
272
        """
273

274
    def set_quota(self, quota_bytes):
275
        """
276
        Set storage quota for this library.
277
        
278
        Parameters:
279
        - quota_bytes: Quota in bytes (0 = unlimited)
280
        """
281

282
    def get_quota(self):
283
        """
284
        Get current quota setting.
285
        
286
        Returns:
287
        int: Current quota in bytes
288
        """
289

290
    def check_quota(self):
291
        """
292
        Check quota usage status.
293
        
294
        Returns:
295
        dict: Quota status information
296
        """
297

298
    def get_library_metadata(self, field):
299
        """
300
        Get library metadata field value.
301
        
302
        Parameters:
303
        - field: Metadata field name
304
        
305
        Returns:
306
        Value of metadata field
307
        """
308

309
    def set_library_metadata(self, field, value):
310
        """
311
        Set library metadata field.
312
        
313
        Parameters:
314
        - field: Metadata field name
315
        - value: Value to set
316
        """
317

318
    def reset_auth(self):
319
        """
320
        Reset authentication for this library.
321
        
322
        Forces re-authentication on next operation.
323
        """
324
```
325

326
## Usage Examples
327

328
### Basic Connection and Library Setup
329

330
```python
331
from arctic import Arctic, VERSION_STORE, TICK_STORE
332

333
# Connect to Arctic with custom timeouts
334
arctic_conn = Arctic(
335
    'mongodb://user:pass@host:27017',
336
    app_name='my_trading_app',
337
    socketTimeoutMS=30000,
338
    connectTimeoutMS=5000
339
)
340

341
# List existing libraries
342
libraries = arctic_conn.list_libraries()
343
print(f"Available libraries: {libraries}")
344

345
# Create new libraries for different data types
346
arctic_conn.initialize_library('daily_prices', VERSION_STORE)
347
arctic_conn.initialize_library('tick_data', TICK_STORE)
348

349
# Access libraries
350
price_lib = arctic_conn['daily_prices']
351
tick_lib = arctic_conn.get_library('tick_data')
352
```
353

354
### Quota Management
355

356
```python
357
# Set 10GB quota on library
358
arctic_conn.set_quota('daily_prices', 10 * 1024**3)
359

360
# Check quota status
361
quota_info = arctic_conn.check_quota('daily_prices')
362
print(f"Quota usage: {quota_info}")
363

364
# Get current quota setting
365
current_quota = arctic_conn.get_quota('daily_prices')
366
print(f"Current quota: {current_quota} bytes")
367
```
368

369
### Library Metadata Management
370

371
```python
372
# Access library binding
373
lib = arctic_conn['daily_prices']
374

375
# Set custom metadata
376
lib.set_library_metadata('data_source', 'Bloomberg')
377
lib.set_library_metadata('update_frequency', 'daily')
378

379
# Retrieve metadata
380
source = lib.get_library_metadata('data_source')
381
frequency = lib.get_library_metadata('update_frequency')
382

383
print(f"Data source: {source}, Update frequency: {frequency}")
384
```