Ruby API

as_foundationdb_key and as_foundationdb_value

In some cases, you may have objects that are used to represent specific keys or values (for example, see Subspace). As a convenience, the language binding API can work seamlessly with such objects if they implement the as_foundationdb_key or as_foundationdb_value methods, respectively. API methods that accept a key will alternately accept an object that implements the as_foundationdb_key method. Likewise, API methods accepting a value will also accept an object that implements the as_foundationdb_value method.

Database options

Database options alter the behavior of FoundationDB databases.

Database.options.set_location_cache_size(size) → nil

Set the size of the client location cache. Raising this value can boost performance in very large databases where clients access data in a near-random pattern. This value must be an integer in the range [0, 2³¹-1]. Defaults to 100000.

Database.options.set_max_watches(max_watches) → nil

Set the maximum number of watches allowed to be outstanding on a database connection. Increasing this number could result in increased resource usage. Reducing this number will not cancel any outstanding watches. Defaults to 10000 and cannot be larger than 1000000.

Database.options.set_machine_id(id) → nil

Specify the machine ID of a server to be preferentially used for database operations. ID must be a string of up to 16 hexadecimal digits that was used to configure fdbserver processes. Load balancing uses this option for location-awareness, attempting to send database operations first to servers on a specified machine, then a specified datacenter, then returning to its default algorithm.

Database.options.set_datacenter_id(id) → nil

Specify the datacenter ID to be preferentially used for database operations. ID must be a string of up to 16 hexadecimal digits that was used to configure fdbserver processes. Load balancing uses this option for location-awareness, attempting to send database operations first to servers on a specified machine, then a specified datacenter, then returning to its default algorithm.

Database.options.set_transaction_timeout(timeout) → nil

Set the default timeout duration in milliseconds after which all transactions created by this database will automatically be cancelled. This is equivalent to calling Transaction.options.set_timeout on each transaction created by this database. This option can only be called if the API version is at least 610.

Database.options.set_transaction_retry_limit(retry_limit) → nil

Set the default maximum number of retries for each transaction after which additional calls to Transaction.on_error will throw the most recently seen error code. This is equivalent to calling Transaction.options.set_retry_limit on each transaction created by this database.

Database.options.set_transaction_max_retry_delay(delay_limit) → nil

Set the default maximum backoff delay incurred by each transaction in the call to Transaction.on_error if the error is retryable. This is equivalent to calling Transaction.options.set_max_retry_delay on each transaction created by this database.

Database.options.set_transaction_size_limit(size_limit) → nil

Set the default maximum transaction size in bytes. This is equivalent to calling Database.options.set_transaction_size_limit on each transaction created by this database.

Database.options.set_transaction_causal_read_risky() → nil

Transactions do not require the strict causal consistency guarantee that FoundationDB provides by default. The read version will be committed, and usually will be the latest committed, but might not be the latest committed in the event of a simultaneous fault and misbehaving clock. Enabling this option is equivalent to calling Transaction.options.set_causal_read_risky on each transaction created by this database.

Database.options.set_transaction_logging_max_field_length(size_limit) → nil

Sets the maximum escaped length of key and value fields to be logged to the trace file via the LOG_TRANSACTION option. This is equivalent to calling Transaction.options.set_transaction_logging_max_field_length on each transaction created by this database.

Database.options.set_snapshot_ryw_enable() → nil

If this option has been set an equal or more times with this database than the disable option, snapshot reads will see the effects of prior writes in the same transaction. Enabling this option is equivalent to calling Transaction.options.set_snapshot_ryw_enable on each transaction created by this database.

Database.options.set_snapshot_ryw_disable() → nil

If this option has been set more times with this database than the disable option, snapshot reads will not see the effects of prior writes in the same transaction. Disabling this option is equivalent to calling Transaction.options.set_snapshot_ryw_disable on each transaction created by this database.

Attributes

Transaction.db

The Database that this transaction is interacting with.

Reading data

Transaction.get(key) → Value

Returns the value associated with the specified key in the database (which may be nil if the key does not exist).

Transaction.[](key)

Alias of Transaction.get.

Transaction.get_key(key_selector) → Key

Returns the key referenced by the specified KeySelector.

By default, the key is cached for the duration of the transaction, providing a potential performance benefit. However, the value of the key is also retrieved, using network bandwidth. Invoking Transaction.options.set_read_your_writes_disable will avoid both the caching and the increased network bandwidth.

Transaction.get_range(begin, end, options={}) → an_enumerable

Returns all keys k such that begin <= k < end and their associated values as an enumerable of KeyValue objects. Note the exclusion of end from the range.

Like a Future object, the returned enumerable issues asynchronous read operations to fetch data in the range, and may block while enumerating its values if the read has not completed. Data will be fetched in one more more efficient batches (depending on the value of the :streaming_mode parameter).

Each of begin and end may be a key (String or Key) or a KeySelector. Note that in the case of a KeySelector, the exclusion of end from the range still applies.

The options hash accepts the following optional parameters:

:limit

Only the first limit keys (and their values) in the range will be returned.

:reverse

If true, then the keys in the range will be returned in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.

If :limit is also specified, the last limit keys in the range will be returned in reverse order.

:streaming_mode

A valid streaming mode, which provides a hint to FoundationDB about how the returned enumerable is likely to be used. The default is :iterator.

Transaction.get_range(begin, end, options={}) {|kv| block } -> nil

If given a block, Transaction.get_range yields each KeyValue in the range that would otherwise have been returned to block.

Transaction.get_range_start_with(prefix, options={}) → an_enumerable

Returns all keys k such that k.start_with? prefix, and their associated values, as an enumerable of KeyValue objects (see Transaction.get_range for a description of the returned enumerable).

The options hash accepts the same values as Transaction.get_range.

Transaction.get_range_start_with(prefix, options={}) {|kv| block } -> nil

If given a block, Transaction.get_range_start_with yields each KeyValue in the range that would otherwise have been returned to block.

Snapshot reads

Transaction.snapshot

Snapshot reads selectively relax FoundationDB’s isolation property, reducing conflicts but making it harder to reason about concurrency.

By default, FoundationDB transactions guarantee strictly serializable isolation, resulting in a state that is as if transactions were executed one at a time, even if they were executed concurrently. Serializability has little performance cost when there are few conflicts but can be expensive when there are many. FoundationDB therefore also permits individual reads within a transaction to be done as snapshot reads.

Snapshot reads differ from ordinary (strictly serializable) reads by permitting the values they read to be modified by concurrent transactions, whereas strictly serializable reads cause conflicts in that case. Like strictly serializable reads, snapshot reads see the effects of prior writes in the same transaction. For more information on the use of snapshot reads, see Snapshot reads.

Snapshot reads also interact with transaction commit a little differently than normal reads. If a snapshot read is outstanding when transaction commit is called that read will immediately return an error. (Normally, transaction commit will wait until outstanding reads return before committing.)

Transaction.snapshot.db

The Database that this transaction is interacting with.

Transaction.snapshot.get(key) → Value

Like Transaction.get, but as a snapshot read.

Transaction.snapshot.[](key) -> Value

Alias of Transaction.snapshot.get.

Transaction.snapshot.get_key(key_selector) → Key

Like Transaction.get_key, but as a snapshot read.

Transaction.snapshot.get_range(begin, end, options={}) → an_enumerable

Like Transaction.get_range, but as a snapshot read.

Transaction.snapshot.get_range_start_with(prefix, options={}) → an_enumerable

Like Transaction.get_range_start_with, but as a snapshot read.

Transaction.snapshot.get_read_version() → Int64Future

Identical to Transaction.get_read_version (since snapshot and strictly serializable reads use the same read version).

Writing data

Transaction.set(key, value) → nil

Associates the given key and value. Overwrites any prior value associated with key. Returns immediately, having modified the snapshot represented by this Transaction.

Transaction.[]=(key, value) -> nil

Alias of Transaction.set.

Note

Although the above method returns nil, assignments in Ruby evaluate to the value assigned, so the expression tr[key] = value will return value.

Transaction.clear(key) → nil

Removes the specified key (and any associated value), if it exists. Returns immediately, having modified the snapshot represented by this Transaction.

Transaction.clear_range(begin, end) → nil

Removes all keys k such that begin <= k < end, and their associated values. Returns immediately, having modified the snapshot represented by this Transaction.

Range clears are efficient with FoundationDB – clearing large amounts of data will be fast. However, this will not immediately free up disk - data for the deleted range is cleaned up in the background. For purposes of computing the transaction size, only the begin and end keys of a clear range are counted. The size of the data stored in the range does not count against the transaction size limit.

Note

Unlike in the case of Transaction.get_range, begin and end must be keys (String or Key), not KeySelectors. (Resolving arbitrary key selectors would prevent this method from returning immediately, introducing concurrency issues.)

Transaction.clear_range_start_with(prefix) → nil

Removes all the keys k such that k.start_with? prefix, and their associated values. Returns immediately, having modified the snapshot represented by this Transaction.

Range clears are efficient with FoundationDB – clearing large amounts of data will be fast. However, this will not immediately free up disk - data for the deleted range is cleaned up in the background. For purposes of computing the transaction size, only the begin and end keys of a clear range are counted. The size of the data stored in the range does not count against the transaction size limit.

Atomic operations

An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result. Different atomic operations perform different transformations. Like other database operations, an atomic operation is used within a transaction; however, its use within a transaction will not cause the transaction to conflict.

Atomic operations do not expose the current value of the key to the client but simply send the database the transformation to apply. In regard to conflict checking, an atomic operation is equivalent to a write without a read. It can only cause other transactions performing reads of the key to conflict.

By combining these logical steps into a single, read-free operation, FoundationDB can guarantee that the transaction will not conflict due to the operation. This makes atomic operations ideal for operating on keys that are frequently modified. A common example is the use of a key-value pair as a counter.

In each of the methods below, param should be a string appropriately packed to represent the desired value. For example:

# wrong
tr.add('key', 1)

# right
tr.add('key', [1].pack('q<'))

Transaction.add(key, param) → nil

Performs an addition of little-endian integers. If the existing value in the database is not present or shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param. In case of overflow, the result is truncated to the width of param.

The integers to be added must be stored in a little-endian representation. They can be signed in two’s complement representation or unsigned. You can add to an integer at a known offset in the value by prepending the appropriate number of zero bytes to param and padding with zero bytes to match the length of the value. However, this offset technique requires that you know the addition will not cause the integer field within the value to overflow.

Transaction.bit_and(key, param) → nil

Performs a bitwise “and” operation. If the existing value in the database is not present, then param is stored in the database. If the existing value in the database is shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param.

Transaction.bit_or(key, param) → nil

Performs a bitwise “or” operation. If the existing value in the database is not present or shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param.

Transaction.bit_xor(key, param) → nil

Performs a bitwise “xor” operation. If the existing value in the database is not present or shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param.

Transaction.compare_and_clear(key, param) → nil

Performs an atomic compare and clear operation. If the existing value in the database is equal to the given value, then given key is cleared.

Transaction.max(key, param) → nil

Sets the value in the database to the larger of the existing value and param. If the existing value in the database is not present or shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param.

Both the existing value and param are treated as unsigned integers. (This differs from the behavior of atomic addition.)

Transaction.byte_max(key, param) → nil

Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then param is stored. Otherwise the larger of the two values is then stored in the database.

Transaction.min(key, param) → nil

Sets the value in the database to the smaller of the existing value and param. If the existing value in the database is not present, then param is stored in the database. If the existing value in the database is shorter than param, it is first extended to the length of param with zero bytes. If param is shorter than the existing value in the database, the existing value is truncated to match the length of param.

Both the existing value and param are treated as unsigned integers. (This differs from the behavior of atomic addition.)

Transaction.byte_min(key, param) → nil

Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then param is stored. Otherwise the smaller of the two values is then stored in the database.

Transaction.set_versionstamped_key(key, param) → nil

Transforms key using a versionstamp for the transaction. This key must be at least 14 bytes long. The final 4 bytes will be interpreted as a 32-bit little-endian integer denoting an index into the key at which to perform the transformation, and then trimmed off the key. The 10 bytes in the key beginning at the index will be overwritten with the versionstamp. If the index plus 10 bytes points past the end of the key, the result will be an error. Sets the transformed key in the database to param.

A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database (serialized in big-endian order). The last 2 bytes are monotonic in the serialization order for transactions (serialized in big-endian order).

A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an accessed_unreadable error. The range of keys marked unreadable when setting a versionstamped key begins at the transactions’s read version if it is known, otherwise a versionstamp of all 0x00 bytes is conservatively assumed. The upper bound of the unreadable range is a versionstamp of all 0xFF bytes.

Warning

At this time, versionstamped keys are not compatible with the Tuple layer except in Java, Python, and Go. Note that this implies versionstamped keys may not be used with the Subspace and Directory layers except in those languages.

Transaction.set_versionstamped_value(key, param) → nil

Transforms param using a versionstamp for the transaction. This parameter must be at least 14 bytes long. The final 4 bytes will be interpreted as a 32-bit little-endian integer denoting an index into the parameter at which to perform the transformation, and then trimmed off the key. The 10 bytes in the parameter beginning at the index will be overwritten with the versionstamp. If the index plus 10 bytes points past the end of the parameter, the result will be an error. Sets key in the database to the transformed parameter.

A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database (serialized in big-endian order). The last 2 bytes are monotonic in the serialization order for transactions (serialized in big-endian order).

A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an accessed_unreadable error. The range of keys marked unreadable when setting a versionstamped key begins at the transactions’s read version if it is known, otherwise a versionstamp of all 0x00 bytes is conservatively assumed. The upper bound of the unreadable range is a versionstamp of all 0xFF bytes.

Warning

At this time, versionstamped values are not compatible with the Tuple layer except in Java, Python, and Go. Note that this implies versionstamped values may not be used with the Subspace and Directory layers except in those languages.

Committing

Transaction.transact() {|tr| block }

Yields self to the given block.

This method, along with Database.transact, makes it easy to write transactional functions which accept either a Database or a Transaction as a parameter. See The transact method for explanation and examples.

Transaction.commit() → FutureNil

Attempt to commit the changes made in the transaction to the database. Returns a FutureNil, representing the asynchronous result of the commit. You must call the wait() method on the returned FutureNil, which will raise an exception if the commit failed.

As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, Transaction.commit will raise a commit_unknown_result exception. The Transaction.on_error function treats this exception as retryable, so retry loops that don’t check for commit_unknown_result could execute the transaction twice. In these cases, you must consider the idempotence of the transaction. For more information, see Transactions with unknown results.

Normally, commit will wait for outstanding reads to return. However, if those reads were snapshot reads or the transaction option for disabling “read-your-writes” has been invoked, any outstanding reads will immediately return errors.

Note

Consider using Database.transact, which not only calls Database.create_transaction and Transaction.commit for you, but also implements the required error handling and retry logic for transactions.

Warning

If any operation is performed on a transaction after a commit has been issued but before it has returned, both the commit and the operation will raise a used_during_commit exception. In this case, all subsequent operations on this transaction will raise this error until reset is called.

Transaction.on_error(exception) → FutureNil

Determine whether an exception raised by a Transaction method is retryable. Returns a FutureNil. You must call the wait() method on the FutureNil, which will return after a delay if the exception was retryable, or re-raise the exception if it was not.

Note

Consider using Database.transact, which calls this method for you.

Transaction.reset() → nil

Rollback a transaction, completely resetting it to its initial state. This is logically equivalent to destroying the transaction and creating a new one.

Transaction.cancel() → nil

Cancels the transaction. All pending or future uses of the transaction will raise a transaction_cancelled exception. The transaction can be used again after it is reset.

Warning

Be careful if you are using Transaction.reset and Transaction.cancel concurrently with the same transaction. Since they negate each other’s effects, a race condition between these calls will leave the transaction in an unknown state.

Warning

If your program attempts to cancel a transaction after Transaction.commit has been called but before it returns, unpredictable behavior will result. While it is guaranteed that the transaction will eventually end up in a cancelled state, the commit may or may not occur. Moreover, even if the call to Transaction.commit appears to raise a transaction_cancelled exception, the commit may have occurred or may occur in the future. This can make it more difficult to reason about the order in which transactions occur.

Watches

Transaction.watch(key) → FutureNil

Creates a watch and returns a FutureNil that will become ready when the watch reports a change to the value of the specified key.

A watch’s behavior is relative to the transaction that created it. A watch will report a change in relation to the key’s value as readable by that transaction. The initial value used for comparison is either that of the transaction’s read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change.

Until the transaction that created it has been committed, a watch will not report changes made by other transactions. In contrast, a watch will immediately report changes made by the transaction itself. Watches cannot be created if the transaction has set Transaction.options.set_read_your_writes_disable, and an attempt to do so will raise an watches_disabled exception.

If the transaction used to create a watch encounters an exception during commit, then the watch will be set with that exception. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result exception. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled exception.

By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will raise a too_many_watches exception. This limit can be changed using Database.options.set_max_watches. Because a watch outlives the transaction that creates it, any watch that is no longer needed should be cancelled by calling Future.cancel on its returned future.

Conflict ranges

The following make it possible to add conflict ranges to a transaction.

Transaction.add_read_conflict_range(begin, end) → nil

Adds a range of keys to the transaction’s read conflict ranges as if you had read the range. As a result, other transactions that write a key in this range could cause the transaction to fail with a conflict.

Transaction.add_read_conflict_key(key) → nil

Adds a key to the transaction’s read conflict ranges as if you had read the key. As a result, other transactions that concurrently write this key could cause the transaction to fail with a conflict.

Transaction.add_write_conflict_range(begin, end) → nil

Adds a range of keys to the transaction’s write conflict ranges as if you had cleared the range. As a result, other transactions that concurrently read a key in this range could fail with a conflict.

Transaction.add_write_conflict_key(key) → nil

Adds a key to the transaction’s write conflict ranges as if you had written the key. As a result, other transactions that concurrently read this key could fail with a conflict.

Versions

Most applications should use the read version that FoundationDB determines automatically during the transaction’s first read, and ignore all of these methods.

Transaction.set_read_version(version) → nil

Infrequently used. Sets the database version that the transaction will read from the database. The database cannot guarantee causal consistency if this method is used (the transaction’s reads will be causally consistent only if the provided read version has that property).

Transaction.get_read_version() → Int64Future

Infrequently used. Returns the transaction’s read version.

Transaction.get_committed_version() → Integer

Infrequently used. Gets the version number at which a successful commit modified the database. This must be called only after the successful (non-error) completion of a call to Transaction.commit on this Transaction, or the behavior is undefined. Read-only transactions do not modify the database when committed and will have a committed version of -1. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

Transaction.get_versionstamp() → String

Infrequently used. Returns a future which will contain the versionstamp which was used by any versionstamp operations in this transaction. This function must be called before a call to Transaction.commit on this Transaction. The future will be ready only after the successful completion of a call to Transaction.commit on this Transaction. Read-only transactions do not modify the database when committed and will result in the future completing with an error. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

Transaction misc functions

Transaction.get_estimated_range_size_bytes(begin_key, end_key) → Int64Future

Gets the estimated byte size of the given key range. Returns a Int64Future.

Note

The estimated size is calculated based on the sampling done by FDB server. The sampling algorithm works roughly in this way: the larger the key-value pair is, the more likely it would be sampled and the more accurate its sampled size would be. And due to that reason it is recommended to use this API to query against large ranges for accuracy considerations. For a rough reference, if the returned size is larger than 3MB, one can consider the size to be accurate.

Transaction.get_range_split_points(begin_key, end_key, chunk_size) → FutureKeyArray

Gets a list of keys that can split the given range into (roughly) equally sized chunks based on chunk_size. Returns a FutureKeyArray. .. note:: The returned split points contain the start key and end key of the given range

Transaction.get_approximate_size() → Int64Future

Gets the the approximate transaction size so far, which is the summation of the estimated size of mutations, read conflict ranges, and write conflict ranges. Returns a Int64Future.

Transaction options

Transaction options alter the behavior of FoundationDB transactions. FoundationDB defaults to extremely safe transaction behavior, and we have worked hard to make the performance excellent with the default setting, so you should not often need to use transaction options.

Transaction.options.set_snapshot_ryw_disable() → nil

If this option is set more times in this transaction than the enable option, snapshot reads will not see the effects of prior writes in the same transaction. Note that prior to API version 300, this was the default behavior. This option can be disabled one or more times at the database level by calling Database.options.set_snapshot_ryw_disable.

Transaction.options.set_snapshot_ryw_enable() → nil

If this option is set an equal or more times in this transaction than the disable option, snapshot reads will see the effects of prior writes in the same transaction. This option can be enabled one or more times at the database-level by calling Database.options.set_snapshot_ryw_enable.

Transaction.options.set_priority_batch() → nil

This transaction should be treated as low priority (other transactions will be processed first). Batch priority transactions will also be throttled at load levels smaller than for other types of transactions and may be fully cut off in the event of machine failures. Useful for doing potentially saturating batch work without interfering with the latency of other operations.

Transaction.options.set_priority_system_immediate() → nil

This transaction should be treated as extremely high priority, taking priority over other transactions and bypassing controls on transaction queuing.

Warning

This is intended for the use of internal database functions and low-level tools; use by applications may result in severe database performance or availability problems.

Transaction.options.set_causal_read_risky() → nil

This transaction does not require the strict causal consistency guarantee that FoundationDB provides by default. The read version will be committed, and usually will be the latest committed, but might not be the latest committed in the event of a simultaneous fault and misbehaving clock. One can set this for all transactions by calling Database.options.set_transaction_causal_read_risky.

Transaction.options.set_causal_write_risky() → nil

The application either knows that this transaction will be self-conflicting (at least one read overlaps at least one set or clear), or is willing to accept a small risk that the transaction could be committed a second time after its commit apparently succeeds. This option provides a small performance benefit.

Transaction.options.set_next_write_no_write_conflict_range() → nil

The next write performed on this transaction will not generate a write conflict range. As a result, other transactions which read the key(s) being modified by the next write will not necessarily conflict with this transaction.

Note

Care needs to be taken when using this option on a transaction that is shared between multiple threads. When setting this option, write conflict ranges will be disabled on the next write operation, regardless of what thread it is on.

Transaction.options.set_read_your_writes_disable() → nil

When this option is invoked, a read performed by a transaction will not see any prior mutations that occured in that transaction, instead seeing the value which was in the database at the transaction’s read version. This option may provide a small performance benefit for the client, but also disables a number of client-side optimizations which are beneficial for transactions which tend to read and write the same keys within a single transaction.

Note

It is an error to set this option after performing any reads or writes on the transaction.

Transaction.options.set_read_ahead_disable() → nil

Disables read-ahead caching for range reads. Under normal operation, a transaction will read extra rows from the database into cache if range reads are used to page through a series of data one row at a time (i.e. if a range read with a one row limit is followed by another one row range read starting immediately after the result of the first).

Transaction.options.set_access_system_keys() → nil

Allows this transaction to read and modify system keys (those that start with the byte 0xFF).

Warning

Writing into system keys will likely break your database. Further, even for readers, the format of data in the system keys may change from version to version in FoundationDB.

Transaction.options.set_read_system_keys() → nil

Allows this transaction to read system keys (those that start with the byte 0xFF).

Warning

The format of data in the system keys may change from version to version in FoundationDB.

Transaction.options.set_retry_limit() → nil

Set a maximum number of retries after which additional calls to Transaction.on_error will throw the most recently seen error code. (By default, a transaction permits an unlimited number of retries.) Valid parameter values are [-1, INT_MAX]. If set to -1, the transaction returns to the default of unlimited retries.

Prior to API version 610, Like all other transaction options, the retry limit must be reset after a call to Transaction.on_error. If the API version is 610 or newer, then the retry limit is not reset. Note that at all API versions, it is safe and legal to call this option after each call to Transaction.on_error, so most code written assuming the older behavior can be upgraded without requiring any modification. This also means there is no need to introduce logic to conditionally set this option within retry loops. One can also set the default retry limit for all transactions by calling Database.options.set_transaction_retry_limit.

Transaction.options.set_max_retry_delay() → nil

Set the maximum backoff delay incurred in the call to Transaction.on_error if the error is retryable. Prior to API version 610, like all other transaction options, the maximum retry delay must be reset after a call to Transaction.on_error. If the API version is 610 or newer, then the maximum retry delay is not reset. Note that at all API versions, it is safe and legal to call this option after each call to Transaction.on_error, so most cade written assuming the older behavior can be upgraded without requiring any modification. This also means there is no need to introduce logic to conditionally set this option within retry loops. One can set the default retry limit for all transactions by calling Database.options.set_transaction_max_retry_delay.

Transaction.options.set_size_limit() → nil

Set the transaction size limit in bytes. The size is calculated by combining the sizes of all keys and values written or mutated, all key ranges cleared, and all read and write conflict ranges. (In other words, it includes the total size of all data included in the request to the cluster to commit the transaction.) Large transactions can cause performance problems on FoundationDB clusters, so setting this limit to a smaller value than the default can help prevent the client from accidentally degrading the cluster’s performance. This value must be at least 32 and cannot be set to higher than 10,000,000, the default transaction size limit.

Transaction.options.set_timeout() → nil

Set a timeout duration in milliseconds after which the transaction automatically to be cancelled. The time is measured from transaction creation (or the most call to reset, if any). Valid parameter values are [0, INT_MAX]. If set to 0, all timeouts will be disabled. Once a transaction has timed out, all pending or future uses of the transaction will raise a transaction_timed_out exception. The transaction can be used again after it is reset.

Timeouts employ transaction cancellation, so you should note the issues raised by Transaction.cancel when using timeouts.

Prior to API version 610, like all other transaction options, a timeout must be reset after a call to Transaction.on_error. Note that resetting this option resets only the timeout duration, not the starting point from which the time is measured. If the API version is 610 or newer, then the timeout is not reset. This allows the user to specify a timeout for specific transactions that is longer than the timeout specified by Database.options.set_transaction_timeout. Note that at all API versions, it is safe and legal to call this option after each call to Transaction.on_error, so most code written assuming the older behavior can be upgraded without requiring any modification. This also means that there is no need to introduce logic to conditionally set this option within retry loops. One can set the default timeout for all transactions by calling Database.options.set_transaction_timeout.

Transaction.options.set_transaction_logging_max_field_length(size_limit) → nil

Sets the maximum escaped length of key and value fields to be logged to the trace file via the LOG_TRANSACTION option, after which the field will be truncated. A negative value disables truncation. One can set the default max field length for all transactions by calling Database.options.set_transaction_logging_max_field_length.

Transaction.options.set_debug_transaction_identifier(id_string) → nil

Sets a client provided string identifier for the transaction that will be used in scenarios like tracing or profiling. Client trace logging or transaction profiling must be separately enabled.

Transaction.options.set_log_transaction() → nil

Enables tracing for this transaction and logs results to the client trace logs. The DEBUG_TRANSACTION_IDENTIFIER option must be set before using this option, and client trace logging must be enabled to get log output.

DirectorySubspace

class FDB::DirectorySubspace

A directory subspace represents a specific directory and its contents. It stores the path with which it was opened and supports all DirectoryLayer methods for operating on itself and its subdirectories. It also implements all Subspace methods for working with the contents of that directory.

DirectorySubspace.move_to(db_or_tr, new_absolute_path) → DirectorySubspace

Moves this directory to new_path, interpreting new_path absolutely. There is no effect on the physical prefix of the given directory or on clients that already have the directory open. The method will raise an exception if a directory already exists at new_path or the parent directory of new_path does not exist.

Returns the directory at its new location as a DirectorySubspace.