a postgres driver for crystal
Crystal
Latest commit cafef60 Feb 21, 2017 @will v0.13.2
Permalink
Failed to load latest commit information.
examples All specs pass Oct 3, 2016
spec ensure listen/notify spec works in same connection Feb 21, 2017
src v0.13.2 Feb 21, 2017
.gitignore update gitignore Dec 10, 2016
.travis.yml drop nightly travis for now Sep 5, 2016
CHANGELOG v0.13.2 Feb 21, 2017
CONTRIBUTING CONTRIBUTING Apr 28, 2015
CONTRIBUTORS v0.13.2 Feb 21, 2017
LICENSE LICENSE Apr 26, 2015
README.md v0.13.0 Dec 22, 2016
shard.yml v0.13.2 Feb 21, 2017

README.md

crystal-pg

A native, non-blocking Postgres driver for Crystal

Build Status docrystal.org

usage

This driver now uses the crystal-db project. Documention on connecting, quering, etc, can be found at:

shards

Add this to your shard.yml and run crystal deps

dependencies:
  pg:
    github: will/crystal-pg

Listen/Notify

There are two ways to listen for notifications. For docs on NOTIFY, please read https://www.postgresql.org/docs/current/static/sql-notify.html.

  1. Any connection can be given a callback to run on notifications. However they are only received when other traffic is going on.
  2. A special listen-only connection can be established for instant notification processing with PG.connect_listen.
# see full example in examples/listen_notify.cr
PG.connect_listen("postgres:///", "a", "b") do |n| # connect and  listen on "a" and "b"
  puts "    got: #{n.payload} on #{n.channel}"     # print notifications as they come in
end

Arrays

Crystal-pg supports several popular array types. If you only need a 1 dimensional array, you can cast down to the appropriate Crystal type:

PG_DB.query_one("select ARRAY[1, null, 3]", &.read(Array(Int32?))
# => [1, nil, 3]

PG_DB.query_one("select '{hello, world}'::text[]", &.read(Array(String))
# => ["hello", "world"]

Requirements

Crystal-pg is tested on Postgres versions 9.1 through 9.4 and developed on 9.6 (travis does not currently have 9.5 support). Since it uses protocal version 3, older versions probably also work but are not guaranteed.

Supported Datatypes

  • text
  • boolean
  • int8, int4, int2
  • float4, float8
  • timestamptz, date, timestamp (but no one should use ts when tstz exists!)
  • json and jsonb
  • uuid
  • bytea
  • numeric/decimal (1)
  • varchar
  • regtype
  • geo types: point, box, path, lseg, polygon, circle, line
  • array types: int8, int4, int2, float8, float4, bool, text

1: A note on numeric: In postgres this type has arbitrary percision. In this driver, it is represented as a PG::Numeric which retians all precision, but if you need to do any math on it, you will probably need to cast it to a float first. If you need true abitrary percision, you can optionally require pg_ext/big_rational which adds #to_big_r, but requires that you have LibGMP installed.