cwinters / pg_sequencer

Create and dump postgres sequences in your Rails app!

pg_sequencer¶ ↑

pg_sequencer adds methods to your migrations to allow you to create, drop and change sequence objects in PostgreSQL. It also dumps sequences to schema.rb.

This is especially useful if you are connecting to a legacy database where the primary key field is declared as an INTEGER and a sequence is queried for the value of the next record.

The design of pg_sequencer is heavily influenced on Matthew Higgins’ Foreigner gem:

• github.com/matthuhiggins/foreigner

Installation¶ ↑

Add this to your Gemfile:

gem 'pg_sequencer'

API¶ ↑

pg_sequencer adds the following methods to migrations:

• create_sequence(sequence_name, options)

• change_sequence(sequence_name, options)

• drop_sequence(sequence_name)

• sequence_exists?(sequence_name)

• sequence_value(sequence_name)

The methods closely mimic the manipulation syntax of the PostgreSQL SQL for CREATE SEQUENCE, DROP SEQUENCE and ALTER SEQUENCE. The existence check scans pg_class, and fetching the next value uses NEXTVAL. See the REFERENCES section below for more information.

Options¶ ↑

For create_sequence and change_sequence, all options are the same, except create_sequence will look for :start or :start_with, and change_sequence will look for :restart or :restart_with.

• :increment/:increment_by (integer) - The value to increment the sequence by.

• :min (integer/false) - The minimum value of the sequence. If specified as false (e.g. :min => false), “NO MINVALUE” is sent to Postgres.

• :max (integer/false) - The maximum value of the sequence. May be specified as “:max => false” to generate “NO MAXVALUE”

• :start/:start_with (integer) - The starting value of the sequence (create_sequence only)

• :restart/:restart_with (integer) The value to restart the sequence with (change_sequence only)

• :cache (integer) - The number of values the sequence should cache.

• :cycle (boolean) - Whether the sequence should cycle. Generated at “CYCLE” or “NO CYCLE”

Examples¶ ↑

Creating a sequence¶ ↑

If it doesn’t already exist, create a sequence called “seq_user”, incrementing by 1, min of 1, max of 2000000, starts at 1, caches 10 values, and disallows cycles:

create_sequence("seq_user", {
  :increment => 1,
  :min => 1,
  :max => 2000000,
  :start => 1,
  :cache => 10,
  :cycle => false
})

This is equivalent to:

CREATE SEQUENCE seq_user INCREMENT BY 1 MIN 1 MAX 2000000 START 1 CACHE 10 NO CYCLE

Reset a sequence’s value:¶ ↑

change_sequence "seq_accounts", :restart_with => 50

This is equivalent to:

ALTER SEQUENCE seq_accounts RESTART WITH 50

Removing a sequence:¶ ↑

drop_sequence "seq_products"

Only remove a sequence if it exists and has a value > 1000¶ ↑

unless sequence_exists?("seq_products") && sequence_value("seq_products") > 1000
  drop_sequence "seq_products"
end

Caveats / Bugs¶ ↑

• Tested with postgres 9.0.4, should work down to 8.1.

• Listing all the sequences in a database creates n+1 queries (1 to get the names and n to describe each sequence). Is there a way to fully describe all sequences in a database in one query?

• The “SET SCHEMA” fragment of the ALTER command is not implemented.

• Oracle/other databases not supported

• Other unknown bugs :)

References¶ ↑

• www.postgresql.org/docs/8.1/static/sql-createsequence.html

• www.postgresql.org/docs/8.1/static/sql-altersequence.html

• www.alberton.info/postgresql_meta_info.html

License¶ ↑

Copyright © 2011 Code 42 Software.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.