fdb v5.1.7-7 FDB.Transaction View Source
Link to this section Summary
Functions
Adds a conflict range to a transaction without performing the associated read or write
Modify the database snapshot represented by transaction to perform the operation indicated by operation_type with operand param to the value stored by the given key
Cancels the transaction. All pending or future uses of the transaction will return a transaction_cancelled error
Modifies the database snapshot represented by transaction to remove the given key from the database. If the key was not previously present in the database, there is no effect
Modify the database snapshot represented by transaction to remove all keys (if any) which are lexicographically greater than or equal to the given begin key and lexicographically less than the given end key
Attempts to commit the sets and clears previously applied to the database snapshot represented by transaction to the actual database. The commit may or may not succeed – in particular, if a conflicting transaction previously committed, then the commit must fail in order to preserve transactional isolation. If the commit does succeed, the transaction is durably committed to the database and all subsequently started transactions will observe its effects
Async version of commit/1
Creates a new transaction
Reads a value from the database snapshot represented by transaction
Returns a list of public network addresses as strings, one for each of the storage servers responsible for storing key and its associated value
Retrieves the database version number at which a given transaction was committed
Resolves a key selector against the keys in the database snapshot represented by transaction
Async version of get_key/2
Async version of get/3
Reads all key-value pairs in the database snapshot represented by transaction which have a key lexicographically greater than or equal to the key resolved by the begin key selector and lexicographically less than the key resolved by the end key selector
Returns the transaction snapshot read version
Async version of get_read_version/1
Returns an FDB.Future.t/0
which will be set to the FDB.Versionstamp.t/0
which was used by any versionstamp operations in this transaction
Async version of on_error/2
Modify the database snapshot represented by transaction to change the given key to have the given value
Changes the default options associated with the transaction
Refer FDB.Option
for the list of options. Any option that starts with transaction_option_
is allowed
Refer FDB.Option
for the list of options. Any option that starts with transaction_option_
is allowed
Sets the snapshot read version used by a transaction
Same as set, but replaces the placeholder versionstamp in the key
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
Link to this section Types
t() :: %FDB.Transaction{ coder: FDB.Transaction.Coder.t(), resource: identifier(), snapshot: integer() }
Link to this section Functions
Adds a conflict range to a transaction without performing the associated read or write.
Most applications will use the serializable isolation that transactions provide by default and will not need to manipulate conflict ranges.
Modify the database snapshot represented by transaction to perform the operation indicated by operation_type with operand param to the value stored by the given key.
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.
If a transaction uses both an atomic operation and a serializable read on the same key, the benefits of using the atomic operation (for both conflict checking and performance) are lost.
The modification affects the actual database only if transaction is
later committed with commit/1
.
Refer FDB.Option
for the list of operationtype. Any option that
starts with `mutation_type` is allowed
Cancels the transaction. All pending or future uses of the transaction will return a transaction_cancelled error.
If your program attempts to cancel a transaction after
commit/1
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 tocommit/1
appears to return a transaction_cancelled error, 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.
Modifies the database snapshot represented by transaction to remove the given key from the database. If the key was not previously present in the database, there is no effect.
The modification affects the actual database only if transaction is
later committed with commit/1
.
Modify the database snapshot represented by transaction to remove all keys (if any) which are lexicographically greater than or equal to the given begin key and lexicographically less than the given end key.
The modification affects the actual database only if transaction is
later committed with commit/1
.
Attempts to commit the sets and clears previously applied to the database snapshot represented by transaction to the actual database. The commit may or may not succeed – in particular, if a conflicting transaction previously committed, then the commit must fail in order to preserve transactional isolation. If the commit does succeed, the transaction is durably committed to the database and all subsequently started transactions will observe its effects.
It is not necessary to commit a read-only transaction.
As with other client/server databases, in some failure scenarios a
client may be unable to determine whether a transaction
succeeded. In these cases, commit/1
will return a
commit_unknown_result error. The FDB.Database.transact/2
function
treats this error as retryable, so this could execute the
transaction twice. In these cases, you must consider the idempotence
of the transaction.
Normally, commit will wait for outstanding reads to return. However,
if those reads were snapshot reads or the transaction option for
FDB.Option.transaction_option_read_your_writes_disable/0
has been
invoked, any outstanding reads will immediately return errors.
Async version of commit/1
create(FDB.Database.t(), map()) :: t()
Creates a new transaction.
Reads a value from the database snapshot represented by transaction.
If key is not present in the database, nil
is returned as the result.
Options
:snapshot
- (boolean) Defaults tofalse
.
Returns a list of public network addresses as strings, one for each of the storage servers responsible for storing key and its associated value.
Async version of get_addresses_for_key/2
Retrieves the database version number at which a given transaction was committed.
commit/1
must have been called on transaction and not an error
before this function is called, 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.
Note that database versions are not necessarily unique to a given
transaction and so cannot be used to determine in what order two
transactions completed. The only use for this function is to
manually enforce causal consistency when calling
set_read_version/2
on another subsequent transaction.
Most applications will not call this function.
Resolves a key selector against the keys in the database snapshot represented by transaction.
Returns the key in the database matching the key selector.
Async version of get_key/2
get_q(t(), any(), map()) :: FDB.Future.t()
Async version of get/3
get_range(t() | FDB.Database.t(), FDB.KeySelectorRange.t(), map()) :: Enumerable.t()
Reads all key-value pairs in the database snapshot represented by transaction which have a key lexicographically greater than or equal to the key resolved by the begin key selector and lexicographically less than the key resolved by the end key selector.
Multiple calls may be made to server to fetch the data. The amount
of data returned on each call is determined by the options like
target_bytes
and mode
.
A Stream
is returned which fetches the data lazily. This is
suitable for iterating over large list of key value pair.
Options
:snapshot
- (boolean) Defaults tofalse
.:reverse
- (boolean) Defaults tofalse
.:target_bytes
- (boolean) If non-zero, indicates a (soft) cap on the combined number of bytes of keys and values to return per call. Defaults to0
.:mode
- (FDB.Option.key/0
) ReferFDB.Option
for the list of options. Any option that starts withstreaming_mode_
is allowed. Defaults toFDB.Option.streaming_mode_iterator/0
.:limit
- (number) If non-zero, indicates the maximum number of key-value pairs to return. Defaults to0
.
Returns the transaction snapshot read version.
The transaction obtains a snapshot read version automatically at the
time of the first call to get_*
(including this one) and (unless
causal consistency has been deliberately compromised by transaction
options) is guaranteed to represent all transactions which were
reported committed before that call.
get_read_version_q(t()) :: FDB.Future.t()
Async version of get_read_version/1
get_versionstamp_q(t()) :: FDB.Future.t()
Returns an FDB.Future.t/0
which will be set to the FDB.Versionstamp.t/0
which was used by any versionstamp operations in this transaction.
The future will be ready only after the successful completion of a
call to commit/1
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.
on_error_q(t(), integer()) :: FDB.Future.t()
Async version of on_error/2
Modify the database snapshot represented by transaction to change the given key to have the given value.
If the given key was not previously present in the database it is
inserted. The modification affects the actual database only if
transaction is later committed with commit/1
.
Changes the default options associated with the transaction.
set_option(t(), FDB.Option.key()) :: :ok
Refer FDB.Option
for the list of options. Any option that starts with transaction_option_
is allowed.
set_option(t(), FDB.Option.key(), FDB.Option.value()) :: :ok
Refer FDB.Option
for the list of options. Any option that starts with transaction_option_
is allowed.
Sets the snapshot read version used by a transaction.
This is not needed in simple cases. If the given version is too old,
subsequent reads will fail with error_code_past_version; if it is
too new, subsequent reads may be delayed indefinitely and/or fail
with error_code_future_version. If any of get*
have been called on
this transaction already, the result is undefined.
Same as set, but replaces the placeholder versionstamp in the key
The semantics are same as set/4
except the key should have one
incomplete FDB.Versionstamp.t/0
. The versionstamp will get
replaced on commit of the transaction.
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 error.
This operation is not compatible with the READ_YOUR_WRITES_DISABLE transaction option and will generate an error if used with it.
Example
coder =
FDB.Transaction.Coder.new(
Coder.Tuple.new({Coder.ByteString.new(), Coder.Versionstamp.new()})
)
future =
Database.transact(db, fn t ->
:ok =
Transaction.set_versionstamped_key(
t,
{"stamped", FDB.Versionstamp.incomplete()},
random_value()
)
Transaction.get_versionstamp_q(t)
end)
stamp = Future.await(future)
[{{"stamped", key_stamp}, _}] =
Database.get_range(db, KeySelectorRange.starts_with({"stamped"}))
|> Enum.to_list()
assert stamp == key_stamp
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 the
FDB.Option.transaction_option_read_your_writes_disable/0
transaction option, and an attempt to do so will return an
watches_disabled error.
If the transaction used to create a watch encounters an error during commit, then the watch will be set with that error. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result error. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled error.
Returns an FDB.Future.t/0
representing an empty value that will
be set once the watch has detected a change to the value at the
specified key.
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 return a
too_many_watches error. This limit can be changed using the
FDB.Option.database_option_max_watches/0
database option.