0
# Core Database Operations
1

2
Fundamental database operations including connecting to clusters, creating transactions, and performing basic setup and teardown operations with ACID guarantees.
3

4
## Capabilities
5

6
### API Version Selection
7

8
Sets the API version that the client will use. This must be called before any other FoundationDB operations.
9

10
```c { .api }
11
/**
12
 * Select the API version for the client library
13
 * @param runtime_version - Version requested by client
14
 * @param header_version - Version compiled into headers  
15
 * @return Error code (0 for success)
16
 */
17
fdb_error_t fdb_select_api_version_impl(int runtime_version, int header_version);
18

19
// Macro that automatically passes header version
20
#define fdb_select_api_version(v) fdb_select_api_version_impl(v, FDB_API_VERSION)
21
```
22

23
```python { .api }
24
def api_version(version: int) -> None:
25
    """
26
    Set the API version for the FoundationDB client
27
    
28
    Args:
29
        version: API version to use (current is 630)
30
        
31
    Raises:
32
        RuntimeError: If version is unsupported or already set differently
33
    """
34
```
35

36
```java { .api }
37
// Java API
38
public static FDB selectAPIVersion(int version):
39
    /**
40
     * Select the API version and get FDB instance
41
     * @param version API version to use
42
     * @return FDB instance for database operations
43
     */
44
```
45

46
```go { .api }  
47
// Go API
48
func MustAPIVersion(version int) error:
49
    /**
50
     * Set the API version, panicking on error
51
     * @param version API version to use  
52
     */
53
```
54

55
### Network Management
56

57
Initialize and manage the network subsystem that handles communication with the FoundationDB cluster.
58

59
```c { .api }
60
/**
61
 * Initialize the network subsystem (must be called before fdb_run_network)
62
 * @return Error code (0 for success)
63
 */
64
fdb_error_t fdb_setup_network();
65

66
/**
67
 * Start the network thread (blocking call)
68
 * @return Error code (0 for success)
69
 */  
70
fdb_error_t fdb_run_network();
71

72
/**
73
 * Stop the network thread
74
 * @return Error code (0 for success)
75
 */
76
fdb_error_t fdb_stop_network();
77

78
/**
79
 * Add cleanup hook called when network thread completes
80
 * @param hook Function to call on completion
81
 * @param hook_parameter Parameter passed to hook function
82
 * @return Error code (0 for success)
83
 */
84
fdb_error_t fdb_add_network_thread_completion_hook(void (*hook)(void*), void* hook_parameter);
85

86
/**
87
 * Get the maximum supported API version by the client library
88
 * @return Maximum API version supported
89
 */
90
int fdb_get_max_api_version();
91

92
/**
93
 * Get the client library version string
94
 * @return Version string
95
 */  
96
const char* fdb_get_client_version();
97
```
98

99
```python { .api }
100
# Network is managed automatically in Python  
101
# No explicit network management required
102

103
def get_api_version() -> int:
104
    """
105
    Get the currently selected API version
106
    
107
    Returns:
108
        Currently selected API version
109
        
110
    Raises:
111
        RuntimeError: If API version is not set
112
    """
113

114
def is_api_version_selected() -> bool:
115
    """
116
    Check if an API version has been selected
117
    
118
    Returns:
119
        True if API version is set, False otherwise
120
    """
121
```
122

123
```java { .api }
124
// Java API  
125
public void startNetwork():
126
    /**
127
     * Start the network thread (called automatically by open())
128
     */
129

130
public void stopNetwork():
131
    /**
132
     * Stop the network thread
133
     */
134
```
135

136
```go { .api }
137
// Go API
138
func StartNetwork() error:
139
    /**
140
     * Start the network thread
141
     * @return Error if network fails to start
142
     */
143

144
func StopNetwork() error:
145
    /**
146
     * Stop the network thread  
147
     * @return Error if network fails to stop
148
     */
149
```
150

151
### Database Connection
152

153
Create and manage database connections to FoundationDB clusters.
154

155
```c { .api }
156
/**
157
 * Create a database connection
158
 * @param cluster_file_path Path to cluster file (NULL for default)
159
 * @param out_database Pointer to store created database handle
160
 * @return Error code (0 for success)
161
 */
162
fdb_error_t fdb_create_database(const char* cluster_file_path, FDBDatabase** out_database);
163

164
/**
165
 * Destroy database connection and free resources
166
 * @param d Database handle to destroy
167
 */
168
void fdb_database_destroy(FDBDatabase* d);
169
```
170

171
```python { .api }
172
def open(cluster_file: str = None, event_model: str = None) -> Database:
173
    """
174
    Open a connection to FoundationDB
175
    
176
    Args:
177
        cluster_file: Path to cluster file (None for default)
178
        event_model: Event model to use (None for default)
179
        
180
    Returns:
181
        Database connection object
182
    """
183

184
class Database:
185
    def __enter__(self) -> 'Database': ...
186
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
187
```
188

189
```java { .api }
190
// Java API
191
public Database open() throws FDBException:
192
    /**
193
     * Open database with default cluster file
194
     * @return Database connection
195
     */
196

197
public Database open(String clusterFilePath) throws FDBException:
198
    /**
199
     * Open database with specified cluster file
200
     * @param clusterFilePath Path to cluster file
201
     * @return Database connection  
202
     */
203

204
public interface Database extends AutoCloseable:
205
    /**
206
     * Database connection that must be closed when done
207
     */
208
```
209

210
```go { .api }
211
// Go API  
212
func OpenDefault() (Database, error):
213
    /**
214
     * Open database with default cluster file
215
     * @return Database connection and error
216
     */
217

218
func OpenDatabase(clusterFile string) (Database, error):
219
    /**
220
     * Open database with specified cluster file
221
     * @param clusterFile Path to cluster file
222
     * @return Database connection and error
223
     */
224

225
func MustOpenDefault() Database:
226
    /**
227
     * Open database with default cluster file, panicking on error
228
     * @return Database connection
229
     */
230
```
231

232
### Transaction Creation
233

234
Create transactions for executing database operations with ACID properties.
235

236
```c { .api }
237
/**
238
 * Create a new transaction on the database
239
 * @param d Database handle
240
 * @param out_transaction Pointer to store created transaction handle
241
 * @return Error code (0 for success)
242
 */
243
fdb_error_t fdb_database_create_transaction(FDBDatabase* d, FDBTransaction** out_transaction);
244

245
/**
246
 * Destroy transaction and free resources
247
 * @param tr Transaction handle to destroy
248
 */
249
void fdb_transaction_destroy(FDBTransaction* tr);
250
```
251

252
```python { .api }
253
class Database:
254
    def create_transaction(self) -> Transaction:
255
        """
256
        Create a new transaction
257
        
258
        Returns:
259
            New transaction object
260
        """
261

262
class Transaction:
263
    def __enter__(self) -> 'Transaction': ...
264
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
265
```
266

267
```java { .api }
268
// Java API
269
public interface Database:
270
    public Transaction createTransaction():
271
        /**
272
         * Create a new transaction
273
         * @return New transaction object
274
         */
275

276
public interface Transaction extends AutoCloseable:
277
    /**
278
     * Transaction that must be closed when done
279
     */
280
```
281

282
```go { .api }
283
// Go API
284
type Database interface:
285
    CreateTransaction() (Transaction, error):
286
        /**
287
         * Create a new transaction
288
         * @return Transaction and error
289
         */
290
```
291

292
### Future Operations
293

294
Functions for working with Future objects returned by asynchronous operations.
295

296
```c { .api }
297
/**
298
 * Block until future is ready (synchronous wait)
299
 * @param f Future to wait for
300
 * @return Error code (0 for success)
301
 */
302
fdb_error_t fdb_future_block_until_ready(FDBFuture* f);
303

304
/**
305
 * Check if future is ready without blocking
306
 * @param f Future to check
307
 * @return True if ready, false otherwise
308
 */
309
fdb_bool_t fdb_future_is_ready(FDBFuture* f);
310

311
/**
312
 * Cancel the operation associated with this future
313
 * @param f Future to cancel
314
 */
315
void fdb_future_cancel(FDBFuture* f);
316

317
/**
318
 * Destroy future and free resources
319
 * @param f Future to destroy
320
 */
321
void fdb_future_destroy(FDBFuture* f);
322

323
/**
324
 * Get error from completed future
325
 * @param f Completed future
326
 * @return Error code (0 if no error)
327
 */
328
fdb_error_t fdb_future_get_error(FDBFuture* f);
329

330
/**
331
 * Extract int64 value from completed future
332
 * @param f Completed future
333
 * @param out Pointer to store extracted value
334
 * @return Error code (0 for success)
335
 */
336
fdb_error_t fdb_future_get_int64(FDBFuture* f, int64_t* out);
337

338
/**
339
 * Extract key from completed future
340
 * @param f Completed future
341
 * @param out_key Pointer to store key pointer
342
 * @param out_key_length Pointer to store key length
343
 * @return Error code (0 for success)
344
 */
345
fdb_error_t fdb_future_get_key(FDBFuture* f, uint8_t const** out_key, int* out_key_length);
346

347
/**
348
 * Extract value from completed future
349
 * @param f Completed future
350
 * @param out_present Pointer to store whether value exists
351
 * @param out_value Pointer to store value pointer
352
 * @param out_value_length Pointer to store value length
353
 * @return Error code (0 for success)
354
 */
355
fdb_error_t fdb_future_get_value(FDBFuture* f, fdb_bool_t* out_present, 
356
                                uint8_t const** out_value, int* out_value_length);
357

358
/**
359
 * Extract key-value array from completed range query future
360
 * @param f Completed future
361
 * @param out_kv Pointer to store key-value array
362
 * @param out_count Pointer to store number of items
363
 * @param out_more Pointer to store whether more results exist
364
 * @return Error code (0 for success)
365
 */
366
fdb_error_t fdb_future_get_keyvalue_array(FDBFuture* f, FDBKeyValue const** out_kv,
367
                                         int* out_count, fdb_bool_t* out_more);
368

369
/**
370
 * Extract string array from completed future
371
 * @param f Completed future
372
 * @param out_strings Pointer to store string array
373
 * @param out_count Pointer to store number of strings
374
 * @return Error code (0 for success)
375
 */
376
fdb_error_t fdb_future_get_string_array(FDBFuture* f, const char*** out_strings, int* out_count);
377
```
378

379
```python { .api }
380
class Future:
381
    def wait(self) -> None:
382
        """Block until future is ready"""
383
    
384
    def is_ready(self) -> bool:
385
        """Check if future is ready without blocking"""
386
    
387
    def cancel(self) -> None:
388
        """Cancel the operation"""
389
    
390
    def block_until_ready(self) -> None:
391
        """Block until future is ready (alias for wait)"""
392
```
393

394
### Version Information
395

396
Retrieve version information about the FoundationDB client library.
397

398
```c { .api }
399
/**
400
 * Get maximum API version supported by client library
401
 * @return Maximum supported API version
402
 */
403
int fdb_get_max_api_version();
404

405
/**
406
 * Get client library version string
407
 * @return Version string
408
 */
409
const char* fdb_get_client_version();
410
```
411

412
```python { .api }
413
def get_api_version() -> int:
414
    """Get currently selected API version"""
415

416
def is_api_version_selected() -> bool:
417
    """Check if API version has been set"""
418
```
419

420
```java { .api }
421
// Java API - version info available through FDB class
422
```
423

424
```go { .api }
425
// Go API - version info available through package constants
426
```
427

428
**Usage Examples:**
429

430
**C API Complete Setup:**
431
```c
432
#define FDB_API_VERSION 630
433
#include <foundationdb/fdb_c.h>
434

435
int main() {
436
    // Select API version
437
    fdb_error_t err = fdb_select_api_version(630);
438
    if (err) return err;
439
    
440
    // Setup and start network
441
    err = fdb_setup_network();
442
    if (err) return err;
443
    
444
    // Start network in background thread here
445
    
446
    // Create database
447
    FDBDatabase* db;
448
    err = fdb_create_database(NULL, &db);
449
    if (err) return err;
450
    
451
    // Create transaction  
452
    FDBTransaction* tr;
453
    err = fdb_database_create_transaction(db, &tr);
454
    if (err) return err;
455
    
456
    // Use transaction here...
457
    
458
    // Cleanup
459
    fdb_transaction_destroy(tr);
460
    fdb_database_destroy(db);
461
    fdb_stop_network();
462
    
463
    return 0;
464
}
465
```
466

467
**Python API Complete Setup:**
468
```python
469
import fdb
470

471
# Set API version (required first)
472
fdb.api_version(630)
473

474
# Open database (network started automatically)
475
db = fdb.open()
476

477
# Create transaction
478
with db.create_transaction() as tr:
479
    # Use transaction here...
480
    pass
481

482
# Database cleanup handled automatically
483
```
484

485
**Java API Complete Setup:**
486
```java
487
import com.apple.foundationdb.*;
488

489
public class Example {
490
    public static void main(String[] args) {
491
        // Select API version and get FDB instance
492
        FDB fdb = FDB.selectAPIVersion(630);
493
        
494
        // Open database (network started automatically)
495
        try (Database db = fdb.open()) {
496
            // Create and use transaction
497
            try (Transaction tr = db.createTransaction()) {
498
                // Use transaction here...
499
                tr.commit().join();
500
            }
501
        } // Database closed automatically
502
    }
503
}
504
```
505

506
**Go API Complete Setup:**
507
```go
508
package main
509

510
import "github.com/apple/foundationdb/bindings/go/src/fdb"
511

512
func main() {
513
    // Set API version
514
    fdb.MustAPIVersion(630)
515
    
516
    // Open database
517
    db := fdb.MustOpenDefault()
518
    
519
    // Create and use transaction
520
    tr, err := db.CreateTransaction()
521
    if err != nil {
522
        panic(err)
523
    }
524
    defer tr.Destroy()
525
    
526
    // Use transaction here...
527
    
528
    // Network cleanup handled automatically on program exit
529
}
530
```