# mongoc_client_start_session()

## Synopsis

    mongoc_client_session_t *
    mongoc_client_start_session (mongoc_client_t *client,
                                 mongoc_session_opt_t *opts,
                                 bson_error_t *error)

Create a session for a sequence of operations.

Start a session with mongoc_client_start_session(), use the session for a sequence of operations and multi-document transactions, then free it with mongoc_client_session_destroy(). Any mongoc_cursor_t or mongoc_change_stream_t using a session must be destroyed before the session, and a session must be destroyed before the mongoc_client_t it came from.

By default, sessions are causally consistent. To disable causal consistency, before starting a session create a mongoc_session_opt_t with mongoc_session_opts_new() and call mongoc_session_opts_set_causal_consistency(), then free the struct with mongoc_session_opts_destroy().

Unacknowledged writes are prohibited with sessions.

A mongoc_client_session_t must be used by only one thread at a time. Due to session pooling, mongoc_client_start_session() may return a session that has been idle for some time and is about to be closed after its idle timeout. Use the session within one minute of acquiring it to refresh the session and avoid a timeout.

## Parameters

- `client`: A mongoc_client_t.
- `opts`: An optional mongoc_session_opt_t.
- `error`: A `bson_error_t`.

## Returns

If successful, this function returns a newly allocated mongoc_client_session_t that should be freed with mongoc_client_session_destroy() when no longer in use. On error, returns NULL and sets `error`.

## Errors

This function can fail if the driver is not built with crypto support, if `opts` is misconfigured, or if the session is configured with options that the server does not support.

### See Also:

mongoc_client_session_abort_transaction

mongoc_client_session_advance_cluster_time

mongoc_client_session_advance_operation_time

mongoc_client_session_commit_transaction

mongoc_client_session_destroy

mongoc_client_session_get_client

mongoc_client_session_get_cluster_time

mongoc_client_session_get_lsid

mongoc_client_session_get_operation_time

mongoc_client_session_get_opts

mongoc_client_session_get_server_id

mongoc_client_session_start_transaction

mongoc_client_session_t

mongoc_session_opts_clone

mongoc_session_opts_destroy

mongoc_session_opts_get_causal_consistency

mongoc_session_opts_get_default_transaction_opts

mongoc_session_opts_get_transaction_opts

mongoc_session_opts_new

mongoc_session_opts_set_causal_consistency

mongoc_session_opts_set_default_transaction_opts

mongoc_transaction_opts_clone

mongoc_transaction_opts_destroy

mongoc_transaction_opts_get_max_commit_time_ms

mongoc_transaction_opts_get_read_concern

mongoc_transaction_opts_get_read_prefs

mongoc_transaction_opts_get_write_concern

mongoc_transaction_opts_new

mongoc_transaction_opts_set_max_commit_time_ms

mongoc_transaction_opts_set_read_concern

mongoc_transaction_opts_set_read_prefs

mongoc_transaction_opts_set_write_concern