# Module `resty.session.postgres`

Postgres backend for session library.

## Configuration

configuration | Postgres storage backend configuration

## Constructors

module.new ([configuration]) | Create a Postgres storage.

## Storage

instance:set (name, key, value, ttl, current_time[, old_key], stale_ttl[, metadata], remember) | Store session data.
instance:get (name, key) | Retrieve session data.
instance:delete (name, key[, metadata]) | Delete session data.
instance:read_metadata (name, audience, subject, current_time) | Read session metadata.

## Database

sessions | Sessions table.
metadata | Sessions metadata table.

## Configuration

configuration
  Postgres storage backend configuration

  ### Fields:

  - host The host to connect (defaults to `"127.0.0.1"`).
  - port The port to connect (defaults to `5432`).
  - application Set the name of the connection as displayed in pg_stat_activity (defaults to `"pgmoon"`).
  - username The database username to authenticate (defaults to `"postgres"`).
  - password Password for authentication, may be required depending on server configuration.
  - database The database name to connect.
  - table_name Name of database table to which to store session data (can be `database schema` prefixed) (defaults to `"sessions"`).
  - table_name_meta Name of database meta data table to which to store session meta data (can be `database schema` prefixed) (defaults to `"sessions_meta"`).
  - connect_timeout Controls the default timeout value used in TCP/unix-domain socket object’s `connect` method.
  - send_timeout Controls the default timeout value used in TCP/unix-domain socket object’s `send` method.
  - read_timeout Controls the default timeout value used in TCP/unix-domain socket object’s `receive` method.
  - keepalive_timeout Controls the default maximal idle time of the connections in the connection pool.
  - pool A custom name for the connection pool being used.
  - pool_size The size of the connection pool.
  - backlog A queue size to use when the connection pool is full (configured with @pool_size).
  - ssl Enable SSL (defaults to `false`).
  - ssl_verify Verify server certificate (defaults to `nil`).
  - ssl_required Abort the connection if the server does not support SSL connections (defaults to `nil`).

## Constructors

module.new ([configuration])
  Create a Postgres storage.

  This creates a new Postgres storage instance.

  ### Parameters:

  - configuration table postgres storage configuration (optional)

  ### Returns:

  table postgres storage instance

## Storage

instance:set (name, key, value, ttl, current_time[, old_key], stale_ttl[, metadata], remember)
  Store session data.

  ### Parameters:

  - name string cookie name
  - key string session key
  - value string session value
  - ttl number session ttl
  - current_time number current time
  - old_key string old session id (optional)
  - stale_ttl string stale ttl
  - metadata table table of metadata (optional)
  - remember boolean whether storing persistent session or not

  ### Returns:

  1. true or nil ok
  2. string error message
instance:get (name, key)
  Retrieve session data.

  ### Parameters:

  - name string cookie name
  - key string session key

  ### Returns:

  1. string or nil session data
  2. string error message
instance:delete (name, key[, metadata])
  Delete session data.

  ### Parameters:

  - name string cookie name
  - key string session key
  - metadata table session meta data (optional)

  ### Returns:

  1. boolean or nil session data
  2. string error message
instance:read_metadata (name, audience, subject, current_time)
  Read session metadata.

  ### Parameters:

  - name string cookie name
  - audience string session key
  - subject string session key
  - current_time number current time

  ### Returns:

  1. table or nil session metadata
  2. string error message

## Database

sessions
  Sessions table.

  Database table that stores session data.

  ### Usage:

      CREATE TABLE IF NOT EXISTS sessions (
        sid  TEXT PRIMARY KEY,
        name TEXT,
        data TEXT,
        exp  TIMESTAMP WITH TIME ZONE
      );
      CREATE INDEX ON sessions (exp);

metadata
  Sessions metadata table.

  This is only needed if you want to store session metadata.

  ### Usage:

      CREATE TABLE IF NOT EXISTS sessions_meta (
        aud TEXT,
        sub TEXT,
        sid TEXT REFERENCES sessions (sid) ON DELETE CASCADE ON UPDATE CASCADE,
        PRIMARY KEY (aud, sub, sid)
      );

generated by LDoc 1.5.0 Last updated 2023-08-16 18:11:28