Eventide

# Session

A session controls the lifecycle of a connection to a message store database, and the execution of data storage and retrieval commands and atomic database transactions.

By default, a session's connection settings are read from a file, but settings can be assigned by any means.

# Session Facts

  • A database connection is not opened when a session is constructed
  • A session's database connection is not opened until a database command is executed
  • Once a connection is opened, it remains connected throughout the lifetime of the session, or until the database server resets or closes the connection
  • If a database connection is closed, it will be reconnected when the next database command is executed
  • Atomic transactions must be started and controlled explicitly (if they are used at all)
  • The database connection initialization data are provided to a session by the Settings class

# MessageStore::Postgres::Session Class

The Session class is a concrete class from the MessageStore::Postgres library and namespace.

The Session class provides:

  • The execute method for sending commands to the message store
  • The transaction method for executing commands in an atomic transaction
  • The open/connect methods for connecting to the message store
  • The close method for terminating the connection to the message store
  • The connected/open? methods for determining if the connection is open
  • The reset method for resetting the connection

# Executing a SQL Command

A SQL command is executed by the session object using the session's database connection. If the connection has not been opened, a connection will be opened before the command is executed by the session.

execute(sql_command, params=nil)

Returns

The result of executing a SQL command via the PG (opens new window) gem.

Parameters

Name Description Type
sql_command A SQL statement to be executed by the database String
params An array of values to substitute for the SQL command's parameter placeholders Array

See PG::Connection.exec() (opens new window) and PG::Connection.exec_params() (opens new window) for more.

# Transaction

All database operations executed within a transaction will either succeed as a whole or be rolled back as a whole if any individual operation fails. If a connection has not been opened, a connection will be opened before the transaction is started.

transaction(&blk)

Parameters

Name Description Type
blk A block that is executed within the bounds of a database transaction Proc
session.transaction do
  session.execute(some_command_1)
  session.execute(some_command_2)
end

Note that the transaction mechanism is used by message writers to write batches of messages as an atomic unit.

# Connecting to the Message Store Database

open()

Alias

connect

Returns

Instance of PG::Connection (opens new window).

The connect method sets the session object's connection attribute. The connection is used throughout the lifecycle of the session.

If the session object already has a connection object when connect is invoked, the existing connection is used.

# Close a Session's Connection

close()

# Determine if a Session's Connection is Open

connected?

Alias

open?

Returns

Boolean

The session will return true if the connection is open.

session.connect

session.connected?
# => true

session.close
session.connected?
# => false

# Reset a Session's Connection

Reset's the session's database connection.

reset()

See see: https://deveiate.org/code/pg/PG/Connection.html#method-i-reset (opens new window) for more.

# Determining the Time of the Last SQL Statement Execution

The session records the time of the last SQL statement sent to the database via the session.

executed_time()

Returns

Time

Note that the executed time will not be set until a statement is executed. Until then, the executed time is nil.

# Determining the Elapsed Milliseconds since the Last SQL Statement Execution

The session can report the elapsed time in milliseconds since the last execution of a SQL statement. The elapsed time is calculated based on the current clock time and the time of the last execution.

executed_time_elapsed_milliseconds()

Returns

Integer

Note that the executed time will not be set until a statement is executed. Until then, the elapsed milliseconds is nil.

# Constructing a Session

Sessions can be constructed in one of two ways

  • Via the initializer
  • Via the constructor

# Via the Initializer

Session.new()

Returns

Instance of the Session class.

By constructing a session using the initializer, the session's settings are not set to operational values. A session instance in this state must still be assigned with operational connection initialization data before a database connection can be made.

# Via the Constructor

self.build(settings: MessageStore::Postgres::Settings.instance)

The constructor not only instantiates the session, but also sets the session's settings to operational values.

Returns

Instance of the Session class.

Parameters

Name Description Type
settings A settings object containing connection initialization data Settings
session = Session.build()

# Log Tags

The following tags are applied to log messages recorded by a session:

Tag Description
session Applied to all log messages recorded by a session
message_store Applied to all log messages recorded inside the MessageStore namespace

The following tags may be applied to log messages recorded by a session:

Tag Description
sql Applied to log messages that record the SQL commands sent to the message store through the session
data Applied to log messages that record the content of data

See the logging user guide for more on log tags.