             select    : undefined    # if given, should be string or array of column names  -|  can give these
             table     : undefined    # if given, name of table                              -|  two instead of query
             params    : []
-            cache     : false        # TODO: implement this
+            cache     : false        # Will cache results for a few seconds or use cache.  Use this
+                                     # when speed is very important, and results that are a few seconds
+                                     # out of date are fine.
             where     : undefined    # Used for SELECT: If given, can be
                                      #  - a map with keys clauses with $::TYPE  (not $1::TYPE!)  and values
                                      #    the corresponding params.  Also, WHERE must not be in the query already.

class exports.PostgreSQL extends EventEmitter    # emits a 'connect' event whenever we successfully connect to the database.
    constructor: (opts) ->
        opts = defaults opts,
            host     : process.env['SMC_DB_HOST'] ? 'localhost'    # or 'hostname:port'
            database : process.env['SMC_DB'] ? 'smc'
            debug    : true
            connect  : true
        @setMaxListeners(10000)  # because of a potentially large number of changefeeds
        @_state = 'init'
        @_debug = opts.debug

            @_port = 5432
        @_database = opts.database
        @_concurrent_queries = 0
        if opts.cache_expiry and opts.cache_size
            @_query_cache = (new require('expiring-lru-cache'))(size:opts.cache_size, expiry: opts.cache_expiry)
        if opts.connect
            @connect()  # start trying to connect

