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.
# 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
Session class is a concrete class from the
MessageStore::Postgres library and namespace.
Session class provides:
executemethod for sending commands to the message store
transactionmethod for executing commands in an atomic transaction
connectmethods for connecting to the message store
closemethod for terminating the connection to the message store
open?methods for determining if the connection is open
resetmethod 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.
The result of executing a SQL command via the PG gem.
|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|
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.
|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
Instance of PG::Connection.
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
# Determine if a Sessions Connection is Open
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.
See see: https://deveiate.org/code/pg/PG/Connection.html#method-i-reset for more.
# Constructing a Session
Sessions can be constructed in one of two ways
- Via the initializer
- Via the constructor
# Via the Initializer
Instance of the
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
The constructor not only instantiates the session, but also sets the session's settings to operational values.
Instance of the
|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:
|session||Applied to all log messages recorded by a session|
|message_store||Applied to all log messages recorded inside the |
The following tags may be applied to log messages recorded by a session:
|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.