Sessions

Overview

Every TCP connection to Kronotop creates exactly one session. The session holds all per-client state: configuration attributes, query cursors, and the active FoundationDB transaction. When the connection closes, the session is destroyed and all of its state is discarded.

SESSION.CLOSE provides a way to reset the session without dropping the underlying connection. This is useful for connection-pooling scenarios or for returning a session to a known-good state between logical units of work.

Session State

A session tracks the following categories of state:

• Configuration attributes: reply format, input format, batch size, object ID format
• Active FoundationDB transaction, at most one at a time, with its post-commit hooks and version counter
• Query cursors, three independent pools for read, delete, and update operations
• Cursor ID counter, a monotonically increasing integer scoped to the session
• Current namespace, set with NAMESPACE USE
• Snapshot read setting, set with SNAPSHOTREAD
• Client name and library info, set with CLIENT SETNAME and CLIENT SETINFO
• Authentication state, when authentication is enabled

All of this state is connection-scoped and invisible to other sessions. The last two items live as long as the connection does, so SESSION.CLOSE leaves them untouched.

Session Attributes

Four configurable attributes control how the session processes commands and formats responses:

Attribute	Type	Default	Valid Values	Description
reply_type	enum	bson	bson, json	Data interchange format for responses
input_type	enum	bson	bson, json	Data interchange format for inputs
batch	integer	100	> 0	Number of documents returned per batch
object_id_format	enum	bytes	bytes, hex	Encoding format for object ID values in responses

Use SESSION.ATTRIBUTE LIST to view current values and SESSION.ATTRIBUTE SET to change them:

> SESSION.ATTRIBUTE LIST
1# reply_type => bson
2# input_type => bson
3# batch => (integer) 100
4# object_id_format => bytes

> SESSION.ATTRIBUTE SET batch 50
OK

Attributes are reset to default values by SESSION.CLOSE or when the connection closes.

Cursors

Queries do not return all matching documents at once. Instead, the first response includes a batch of results together with a cursor_id. The client uses BUCKET.ADVANCE with that cursor ID to fetch subsequent batches until the result set is exhausted.

> BUCKET.QUERY users '{"age": {"$gt": 18}}'
1# cursor_id => (integer) 1
2# entries => [ ... first batch ... ]

> BUCKET.ADVANCE QUERY 1
1# cursor_id => (integer) 1
2# entries => [ ... next batch ... ]

Cursor IDs are integers starting at 1 and increment within the session. Three independent cursor pools exist, one each for read, delete, and update operations, so a read cursor and a delete cursor may share the same numeric ID without a conflict.

BUCKET.CLOSE releases a specific cursor before it is naturally exhausted. SESSION.CLOSE releases all cursors at once.

Interaction with Transactions

By default, sessions operate in auto-commit mode. Each command that touches FoundationDB creates, executes, and commits its own transaction. BEGIN opens an explicit transaction that spans multiple commands until COMMIT or ROLLBACK.

An explicit transaction is bound to the session. If the client issues SESSION.CLOSE while a transaction is in progress, the transaction is automatically rolled back:

> BEGIN
OK

> SESSION.CLOSE
OK

> ROLLBACK
(error) TRANSACTION there is no transaction in progress.

Cursors are independent of transactions. A cursor created inside an explicit transaction survives COMMIT or ROLLBACK and can continue to be advanced afterward.

Watched keys (WATCH) are also session-scoped. SESSION.CLOSE unwatches all keys, just as DISCARD does.

Session Reset

SESSION.CLOSE performs a full session reset without closing the network connection. The reset proceeds in order:

1. Clear all cursors: read, delete, and update cursor pools are emptied
2. Roll back the active transaction: the FoundationDB transaction is closed and all uncommitted changes are lost
3. Reset MULTI state: queued commands are discarded and the MULTI flag is cleared
4. Unwatch all keys: every key in the session’s watch list is released
5. Reset the cursor ID counter: the next cursor will start at 1 again
6. Restore session defaults: the four configuration attributes revert to their configured defaults, the snapshot read setting goes back to off, and the current namespace goes back to the default one

After SESSION.CLOSE returns OK, the session is back to the state of a freshly opened connection. What survives is the state that belongs to the connection itself: the negotiated RESP version, the authentication state, and the client name and library info. A pooled connection can therefore be reused without a new AUTH round trip.

> SESSION.ATTRIBUTE SET batch 50
OK

> SESSION.CLOSE
OK

> SESSION.ATTRIBUTE LIST
1# reply_type => bson
2# input_type => bson
3# batch => (integer) 100
4# object_id_format => bytes

Commands

Command	Description
SESSION.ATTRIBUTE	View and modify session attributes
SESSION.CLOSE	Reset all session state to defaults