Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tarantool/pg
PostgreSQL connector for Tarantool
https://github.com/tarantool/pg
Last synced: 3 months ago
JSON representation
PostgreSQL connector for Tarantool
- Host: GitHub
- URL: https://github.com/tarantool/pg
- Owner: tarantool
- License: other
- Created: 2015-04-27T12:29:47.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-20T13:43:32.000Z (8 months ago)
- Last Synced: 2024-04-05T21:33:21.377Z (7 months ago)
- Language: C
- Size: 54.7 KB
- Stars: 38
- Watchers: 44
- Forks: 12
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tarantool - pg - (Packages / Clients)
README
# pg - PostgreSQL connector for [Tarantool][]
[](https://github.com/tarantool/pg/actions/workflows/test.yml)
## Getting Started
### Prerequisites
* Tarantool 1.6.5+ with header files (tarantool && tarantool-dev packages)
* PostgreSQL 8.1+ header files (libpq-dev package)
### Installation
Clone repository and then build it using CMake:
``` bash
git clone https://github.com/tarantool/pg.git
cd pg && cmake . -DCMAKE_BUILD_TYPE=RelWithDebugInfo
make
make install
```
You can also use LuaRocks:
``` bash
luarocks install https://raw.githubusercontent.com/tarantool/pg/master/pg-scm-1.rockspec --local
```
See [tarantool/rocks][TarantoolRocks] for LuaRocks configuration details.
### Usage
``` lua
local pg = require('pg')
local conn = pg.connect({host = localhost, user = 'user', pass = 'pass', db = 'db'})
local tuples = conn:execute("SELECT $1 AS a, 'xx' AS b", 42)
conn:begin()
conn:execute("INSERT INTO test VALUES(1, 2, 3)")
conn:commit()
```
## API Documentation
### `conn = pg:connect(opts = {})`
Connect to a database.
*Options*:
- `host` - a hostname to connect
- `port` - a port numner to connect
- `user` - username
- `pass` or `password` - a password
- `db` - a database name
- `conn_string` (mutual exclusive with host, port, user, pass, db) - PostgreSQL
[connection string][PQconnstring]
*Returns*:
- `connection ~= nil` on success
- `error(reason)` on error
### `conn:execute(statement, ...)`
Execute a statement with arguments in the current transaction.
*Returns*:
- `{ { { column1 = value, column2 = value }, ... }, { {column1 = value, ... }, ...}, ...}, true` on success
- `error(reason)` on error
*Example*:
```
tarantool> conn:execute("SELECT $1 AS a, 'xx' AS b", 42)
---
- - - a: 42
b: xx
...
```
### `conn:begin()`
Begin a transaction.
*Returns*: `true`
### `conn:commit()`
Commit current transaction.
*Returns*: `true`
### `conn:rollback()`
Rollback current transaction.
*Returns*: `true`
### `conn:ping()`
Execute a dummy statement to check that connection is alive.
*Returns*:
- `true` on success
- `false` on failure
#### `pool = pg.pool_create(opts = {})`
Create a connection pool with count of size established connections.
*Options*:
- `host` - hostname to connect to
- `port` - port number to connect to
- `user` - username
- `password` - password
- `db` - database name
- `size` - count of connections in pool
*Returns*
- `pool ~=nil` on success
- `error(reason)` on error
### `conn = pool:get()`
Get a connection from pool. Reset connection before returning it. If connection
is broken then it will be reestablished. If there is no free connections then
calling fiber will sleep until another fiber returns some connection to pool.
*Returns*:
- `conn ~= nil`
### `pool:put(conn)`
Return a connection to connection pool.
*Options*
- `conn` - a connection
## Comments
All calls to connections api will be serialized, so it should to be safe to
use one connection from some count of fibers. But you should understand,
that you can have some unwanted behavior across db calls, for example if
another fiber 'injects' some sql between two your calls.
# See Also
* [Tests][]
* [Tarantool][]
* [Tarantool Rocks][TarantoolRocks]
[Tarantool]: http://github.com/tarantool/tarantool
[Tests]: https://github.com/tarantool/pg/tree/master/test
[PQconnstring]: http://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNSTRING
[TarantoolRocks]: https://github.com/tarantool/rocks