PostgreSQL binding for R7RS Scheme ================================== This is a PostgreSQL socket frontend interface library written in pure R7RS Scheme. NOTE: it's still working state. Supported implementations ------------------------- - Sagittarius 0.5.9 or later - Gauche 0.9.4 - Chibi Scheme 0.7 This library should work in R7RS implementations which support the following SRFIs: - SRFI-60/SRFI-33 or R6RS library `(rnrs)` - SRFI-106 - SRFI-19 (Optional) High level APIs --------------- ### Library - `(postgresql)` The library provides high level APIs to communicate with PostgreSQL. ### Procedures - `(postgresql-connection? obj)` Returns `#t` if _obj_ is an PostgreSQL connection object. - `(make-postgresql-connection host port database username password)` `database` can be `#f`. All arguments must be a string except `database`. Creates a PostgreSQL connection. At this moment, the connection to the server is *not* established. - `(postgresql-open-connection! conn)` Establishes a connection with specified _conn_ object. - `(postgresql-login! conn)` Logging in to the PostgreSQL server. - `(postgresql-terminate! conn)` Terminates the session and disconnects from the server. - `(postgresql-prepared-statement? obj)` Return `#t` if _obj_ is a PostgreSQL prepared statement. - `(postgresql-prepared-statement conn sql)` Creates a prepared statement object. - `(postgresql-close-prepared-statement! prepared-statement)` Closes the prepared statement _prepared-statement_. - `(postgresql-bind-parameters! prepared-statement . params)` Binds parameter _params_ to given _prepared-statement_. - `(postgresql-execute! prepared-statement)` Executes the given _prepared-statement_ and returns either PostgreSQL query object for SELECT statement or affected row count. To retrieve the result, use the `postgresql-fetch-query!` procedure. - `(postgresql-query? obj)` Returns `#t` if _obj_ is a PostgreSQL query object. - `(postgresql-execute-sql! conn sql)` Executes the given _sql_ statement. If _sql_ is a select statement then the value returned is a PostgreSQL query object. Otherwise `#t`. This procedure retrieves all results in one go if _sql_ is a SELECT statement. So it may cause memory explosion if the result set is too big. - `(postgresql-fetch-query! query)` Fetch a row as a vector. If no more data are available, then returns `#f`. - `(postgresql-start-transaction! conn mode)` Issue `START TRANSACTION` statement to start a transaction. _mode_ specifies how the transation should be. The argument _mode_ must be either a PostgreSQL transaction mode object or `#f`. - `(postgresql-transaction-mode alist)` Creates a PostgreSQL transaction mode object. The _alist_ specifies how the transaction mode is created. It may have the following symbols as its key. - `isolation-level` - `access-mode` - `deferrable` Each key must have one of the followings: For `isolation-level`: - Variable: `postgresql-isolation-level-serializable` - Variable: `postgresql-isolation-level-repeatable-read` - Variable: `postgresql-isolation-level-read-committed` - Variable: `postgresql-isolation-level-read-uncommitted` For `access-mode`: - Variable: `postgresql-access-mode-read-write` - Variable: `postgresql-access-mode-read-only` For `deferrable`: - Variable: `postgresql-deferrable-on` - Variable: `postgresql-deferrable-off` - `(postgresql-commit! conn)` Issue `COMMIT` statement. - `(postgresql-rollback! conn)` Issue `ROLLBACK` statement. ### Parameters - `*postgresql-maximum-results*` Configuration parameter for how many result it should fetch. Default value is 50. - `*postgresql-copy-data-handler*` Handler of COPY to stdout command. The value must be a procedure and takes 2 arguments, data type and data. The data type should be one of the the following symbols: - header - data - complete When the data type is `header` then the given data is a list of data information. It contains 3 elements, the format of overall COPY command, 0 is textual, 1 is binary. When the data type is `data` then the given data is a bytevector whose content is the result of COPY command. When the data type is `complete` then the given data is `#f`. This indicates the COPY command is done. - `*postgresql-write-data-handler*` Handler of COPY from stdin command. The value must be a procedure and take 2 arguments, data type and data. The data type could be one of the following symbols; - header - data - complete When the data type is `header` then the given data is a list of data information. It contains 3 elements, the format of overall COPY command, 0 is textual, 1 is binary. When the data type is `data` then the given data is a `#f`. When there is no more data to send, then the handler must return `#f` otherwise it would go into inifinite loop. When the data type is `complete` then the given data is `#t`. This indicates the COPY command is done. These handlers are currently a thin wrapper of the COPY command. Using them, users need to know about how the data is sent. For more detail, please refer the PostgreSQL manual. - `*postgresql-unknown-type-handler*` Handler of unknown type, which is the library default couldn't handle converting the value according to the type identifier. The value must be aprocedure and take 2 arguments; _type_ and _value_. The _type_ is an integer which represents PostgreSQL internal type defined in `catalog/pg_type.h` header file of PostgreSQL source. The _value_ is a raw value of SQL query, bytevector. Low level APIs -------------- TBD Data conversion --------------- Data conversion is done automatically by high level APIs. The following table describes how it's done. | PostgreSQL type | Scheme type | |:--------------- | --------------------:| | Integers | Number | | Float | Inexact number | | Characters | String | | Date | SRFI-19 date | | Time | SRFI-19 date | | Timestamp | SRFI-19 time | | UUID | String | _Note_: If the implementation doesn't support SRFI-19, the scheme type will be string. Copyright and lincense ---------------------- Copyright 2014-2015 Takashi Kato. Code released under the BSD-style license. See [COPYING](COPYING). TODO ---- - Data conversion is not done properly - need some document but couldn't find it... - ~~Prepared statement~~ - ~~Maybe buffering~~ - ~~currently it can't execute second query unless it fetches all records.~~