Changeset 37595 in project


Ignore:
Timestamp:
05/12/19 11:17:32 (9 days ago)
Author:
sjamaan
Message:

postgresql: Document the new LISTEN/NOTIFY support

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/postgresql

    r35582 r37595  
    77=== Description
    88
    9 Bindings for [[http://www.postgresql.org/|PostgreSQL]]'s C-api.
     9Bindings for [[https://www.postgresql.org/|PostgreSQL]]'s C-api.
    1010
    1111=== Author
     
    3030
    3131You will also need to have
    32 [[http://www.postgresql.org/docs/current/interactive/libpq.html|libpq]]
     32[[https://www.postgresql.org/docs/current/interactive/libpq.html|libpq]]
    3333installed, including development headers.
    3434
     
    3636
    3737This extension provides an interface to the
    38 [[http://www.postgresql.org|PostgreSQL]] relational database.
     38[[https://www.postgresql.org|PostgreSQL]] relational database.
    3939
    4040==== Connection management
    4141
    42 <procedure>(connect [CONNECTION-SPEC [TYPE-PARSERS [TYPE-UNPARSERS]]])</procedure>
     42<procedure>(connect [CONNECTION-SPEC [TYPE-PARSERS [TYPE-UNPARSERS [NOTIFY-HANDLER]]]])</procedure>
    4343
    4444Opens a connection to the database given in CONNECTION-SPEC, which
     
    4646entries consisting of a symbol and a value.  The symbols should be
    4747connection keywords recognized by PostgreSQL's connection function.
    48 See the [[http://www.postgresql.org/docs/current/interactive/libpq-connect.html|list of PQconnectdbParams parameter keywords]] in the PostgreSQL documentation.
     48See the [[https://www.postgresql.org/docs/current/interactive/libpq-connect.html|list of PQconnectdbParams parameter keywords]] in the PostgreSQL documentation.
    4949At the time of writing, they are {{host}}, {{hostaddr}}, {{port}}, {{dbname}}, {{user}}, {{password}}, {{connect_timeout}}, {{options}}, {{sslmode}}, {{service}}.
    5050
     
    5252not supplied at all, the regular libpq rules apply.  That means it
    5353falls back to checking various
    54 [[http://www.postgresql.org/docs/current/interactive/libpq-envars.html|environment variables]]
     54[[https://www.postgresql.org/docs/current/interactive/libpq-envars.html|environment variables]]
    5555and settings from
    56 [[http://www.postgresql.org/docs/current/interactive/libpq-pgservice.html|pg_service.conf]],
    57 as well as passwords from [[http://www.postgresql.org/docs/current/interactive/libpq-pgpass.html|pgpass]].
     56[[https://www.postgresql.org/docs/current/interactive/libpq-pgservice.html|pg_service.conf]],
     57as well as passwords from [[https://www.postgresql.org/docs/current/interactive/libpq-pgpass.html|pgpass]].
    5858This is to be preferred over hardcoding connection settings in your code.
    5959
     
    7070{{(default-type-parsers)}} and {{(default-type-unparsers)}},
    7171respectively (see [[#type-conversion|below]]).
     72
     73{{NOTIFY-HANDLER}} is an optional procedure which should accept three
     74arguments: A channel name (string), the triggering backend's PID
     75(integer) and the payload (string).  It is invoked whenever there are
     76asynchronous notifications available through
     77[[https://www.postgresql.org/docs/current/sql-listen.html|{{LISTEN}}]].
     78It defaults to {{(default-notify-handler)}} (see
     79[[#listen-notify-support|below]]).  It may also be {{#f}} to disable
     80handling of notifications.
    7281
    7382The return value is a connection-object.
     
    738747; {{severity}} : One of the symbols {{error}}, {{fatal}}, {{panic}}, {{warning}}, {{notice}}, {{debug}}, {{info}}, {{log}} (unfortunately, this symbol may also be translated/localised, so you should not dispatch on them in code: use error-class and error-code for that). Always present in {{query}} type subconditions.
    739748; {{error-class}} : A string representing a Postgresql error class (the first two characters of {{error-code}}).  Always present in {{query}} type subconditions.
    740 ; {{error-code}} :  A string representing the full Postgresql error code (including the code class prefix).  See the [[http://www.postgresql.org/docs/8.3/static/errcodes-appendix.html|Postgresql documentation]] for a description of error codes and error classes. Always present in {{query}} type subconditions.
     749; {{error-code}} :  A string representing the full Postgresql error code (including the code class prefix).  See the [[https://www.postgresql.org/docs/current/errcodes-appendix.html|Postgresql documentation]] for a description of error codes and error classes. Always present in {{query}} type subconditions.
    741750; {{message-primary}} : The main error message.  Always present in {{query}} type subconditions.  The {{exn}} message will be a combination of this plus the optional detail and hint.
    742751; {{message-detail}} :  A secondary message with extra detail about the problem.
     
    930939unparsed recursively by their respective subparsers.
    931940
     941==== {{LISTEN}}/{{NOTIFY}} support
     942
     943PostgreSQL supports asynchronous notifications through
     944[[https://www.postgresql.org/docs/current/sql-listen.html|{{LISTEN}}]] and
     945[[https://www.postgresql.org/docs/current/sql-notify.html|{{NOTIFY}}]].
     946
     947When you want to receive these notifications, you can simply issue a
     948{{LISTEN}} on the desired channel via SQL.  Then, when the
     949notification arrives, the connection's notify handler will be invoked.
     950The handler can be set when initialising the connection.
     951
     952<parameter>(default-notify-handler [HANDLER])</parameter>
     953
     954The handler that will be used when setting up new connections, if none
     955was supplied to {{connect}}.  This must be a procedure of three
     956arguments, or {{#f}} if you don't want to handle notifications.
     957
     958The three arguments are: A channel name (string), the PID of the
     959backend which triggered the {{NOTIFY}} (integer) and the notification
     960payload (string).
     961
     962<procedure>(set-notify-handler! CONN HANDLER)</procedure>
     963
     964When you have an existing connection {{CONN}}, this procedure can
     965update its {{NOTIFY}} handler to a new value.
     966
     967{{HANDLER}} must be a procedure of three arguments, or {{#f}} if you
     968don't want to handle notifications.  The three arguments are: A
     969channel name (string), the PID of the backend which triggered the
     970{{NOTIFY}} (integer) and the notification payload (string).
     971
     972<procedure>(wait-for-notifications! CONN [DELAY])</procedure>
     973
     974Normally, asynchronous notifications will be piggy-backed on responses
     975after you issue a command to the backend.  But sometimes you just want
     976to idle until a notification arrives.  You can use
     977{{wait-for-notifications!}} to do this.  It will wait until either
     978{{DELAY}} (in milliseconds) has passed, or an event arrives on the
     979connection.  If {{DELAY}} is {{#f}} (or not supplied), it will wait
     980forever, until an event arrives.
     981
    932982
    933983=== Changelog
    934984
     985* 4.1.1 Forgot to expose {{default-notify-handler}}
     986* 4.1.0 Add {{LISTEN}}/{{NOTIFY}} support.
    935987* 4.0.0 Port to CHICKEN 5.
    936988* 3.9.4 If {{pkg-config}} doesn't know about {{libpq}}, don't use it.
     
    9721024=== License
    9731025
    974   Copyright (C) 2008-2016 Peter Bex
     1026  Copyright (C) 2008-2019 Peter Bex
    9751027  Copyright (C) 2004 Johannes GrÞdem <johs@copyleft.no>
    9761028  Redistribution and use in source and binary forms, with or without
Note: See TracChangeset for help on using the changeset viewer.