1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
= sequel_pg
sequel_pg overwrites the inner loop of the Sequel postgres adapter
row fetching code with a C version. The C version is significantly
faster than the pure ruby version that Sequel uses by default.
== Real world difference
The speed up that sequel_pg gives you depends on what you are
selecting, but it should be noticeable whenever many rows are selected.
Here's an example that shows the difference it makes on a couple of
models:
Track.count # => 202261
Album.count # => 7264
Without sequel_pg:
puts Benchmark.measure{Track.each{}}
# 3.400000 0.290000 3.690000 ( 4.005150)
puts Benchmark.measure{10.times{Album.each{}}}
# 2.180000 0.120000 2.300000 ( 2.479352)
With sequel_pg:
puts Benchmark.measure{Track.each{}}
# 1.660000 0.260000 1.920000 ( 2.287216)
puts Benchmark.measure{10.times{Album.each{}}}
# 0.960000 0.110000 1.070000 ( 1.260913)
sequel_pg also speeds up the following Dataset methods:
* map
* as_hash/to_hash
* to_hash_groups
* select_hash
* select_hash_groups
* select_map
* select_order_map
Additionally, in most cases sequel_pg also speeds up the loading of
model datasets by optimizing model instance creation.
== Streaming
If you are using PostgreSQL 9.2+ on the client, then sequel_pg
should enable streaming support. This allows you to stream returned
rows one at a time, instead of collecting the entire result set in
memory (which is how PostgreSQL works by default). You can check
if streaming is supported by:
Sequel::Postgres.supports_streaming?
If streaming is supported, you can load the streaming support into the
database:
DB.extension(:pg_streaming)
Then you can call the Dataset#stream method to have the dataset use
the streaming support:
DB[:table].stream.each{|row| ...}
If you want to enable streaming for all of a database's datasets, you
can do the following:
DB.stream_all_queries = true
== Installing the gem
gem install sequel_pg
Make sure the pg_config binary is in your PATH so the installation
can find the PostgreSQL shared library and header files. Alternatively,
you can use the POSTGRES_LIB and POSTGRES_INCLUDE environment
variables to specify the shared library and header directories.
== Running the specs
sequel_pg is designed to replace a part of Sequel, so it should be tested
using Sequel's specs (the spec_postgres rake task). There is a spec_cov
task that assumes you have Sequel checked out at ../sequel, and uses a
small spec suite for parts of sequel_pg not covered by Sequel's specs.
It sets the SEQUEL_PG_STREAM environment variable when running Sequel's
specs, make sure that spec/spec_config.rb in Sequel is set to connect
to PostgreSQL and use the following additional settings:
DB.extension(:pg_streaming)
DB.stream_all_queries = true
== Reporting issues/bugs
sequel_pg uses GitHub Issues for tracking issues/bugs:
http://github.com/jeremyevans/sequel_pg/issues
== Contributing
The source code is on GitHub:
http://github.com/jeremyevans/sequel_pg
To get a copy:
git clone git://github.com/jeremyevans/sequel_pg.git
There are only a few requirements, which you should probably
have before considering use of the library:
* Rake
* Sequel
* pg
* libpq headers and library
== Building
To build the library from a git checkout, after installing the
requirements:
rake build
== Known Issues
* You must be using the ISO PostgreSQL date format (which is the
default). Using the SQL, POSTGRESQL, or GERMAN date formats will
result in incorrect date/timestamp handling. In addition to
PostgreSQL defaulting to ISO, Sequel also manually sets the
date format to ISO by default, so unless you are overriding that
setting (via DB.use_iso_date_format = false), you should be OK.
* Adding your own type conversion procs only has an effect if those
types are not handled by default.
* You do not need to require the library, the sequel postgres adapter
will require it automatically. If you are using bundler, you
should add it to your Gemfile like so:
gem 'sequel_pg', require: 'sequel'
* Using a precompiled pg gem can cause issues in certain cases,
since it statically links a libpq that could differ from the system
libpq dynamically linked to the sequel_pg gem. You can work around
the issue by forcing the ruby platform for the pg gem:
# Manual install
gem install pg --platform ruby
# Gemfile
gem 'pg', force_ruby_platform: true
* sequel_pg currently calls functions defined in the pg gem, which
does not work on Windows and does not work in some unix-like
operating systems that disallow undefined functions in shared
libraries. If <tt>RbConfig::CONFIG['LDFLAGS']</tt> contains
<tt>-Wl,--no-undefined</tt>, you'll probably have issues installing
sequel_pg. You should probably fix <tt>RbConfig::CONFIG['LDFLAGS']</tt>
in that case.
== Author
Jeremy Evans <code@jeremyevans.net>
|
