crystal-pg

a postgres driver for crystal

crystal-pg

A native, non-blocking Postgres driver for Crystal

Build Status

usage

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

  • https://crystal-lang.org/docs/database/
  • https://crystal-lang.org/docs/database/connection_pool.html

shards

Add this to your shard.yml and run shards install

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.2 through 9.6. Since it uses protocol 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 precision. In this driver, it is represented as a PG::Numeric which retains 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 arbitrary precision, you can optionally require pg_ext/big_rational which adds #to_big_r, but requires that you have LibGMP installed.

Github statistic:
  • 303
  • 48
  • 17
  • 30
  • about 7 hours ago

License:

BSD 3-Clause "New" or "Revised" License

Links: