From 42dc4421c6ffa5802402592c8dfd6b3bce679433 Mon Sep 17 00:00:00 2001 From: Dan McClain Date: Fri, 28 Jun 2013 10:04:42 -0400 Subject: [PATCH] Updates docs and description --- README.md | 49 +---------------------- docs/indexes.md | 28 -------------- docs/migrations.md | 92 -------------------------------------------- docs/type_casting.md | 70 --------------------------------- postgres_ext.gemspec | 4 +- 5 files changed, 3 insertions(+), 240 deletions(-) delete mode 100644 docs/indexes.md delete mode 100644 docs/migrations.md delete mode 100644 docs/type_casting.md diff --git a/README.md b/README.md index cd0128c..6db4fb4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PostgresExt -Adds support for missing PostgreSQL data types to ActiveRecord. +Provides a helpful querying API for Rails 4 + PostgreSQL [![Build Status](https://secure.travis-ci.org/dockyard/postgres_ext.png?branch=master)](http://travis-ci.org/dockyard/postgres_ext) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/dockyard/postgres_ext) @@ -36,54 +36,7 @@ Or install it yourself as: Just `require 'postgres_ext'` and use ActiveRecord as you normally would! postgres\_ext extends ActiveRecord's data type handling. - * [Migration/Schema.rb support](docs/migrations.md) - * [Type Casting support](docs/type_casting.md) * [Querying PostgreSQL datatypes](docs/querying.md) - * [Indexes](docs/indexes.md) - -## Usage Notes -Avoid the use of in place operators (ie `Array#<<`). These changes are -*not* tracked by Rails ([this issue](https://github.com/rails/rails/issues/6954)) -explains why). In place modifications also modify the default object. - -Assuming we have the following model: - -```ruby -create_table :items do |t| - t.string :names, :array => true, :default => [] -end - -class Item < ActiveRecord::Base -end -``` - -The following will modify the default value of the names attribute. - -```ruby -a = Item.new -a.names << 'foo' - -b = Item.new -puts b.names -# => ['foo'] -``` - -The supported way of modifying `a.names`: - -```ruby -a = Item.new -a.names += ['foo'] - -b = Item.new -puts b.names -# => [] -``` - -As a result, in place operators are discouraged and will not be -supported in postgres\_ext at this time. - - - ## Authors diff --git a/docs/indexes.md b/docs/indexes.md deleted file mode 100644 index a38075b..0000000 --- a/docs/indexes.md +++ /dev/null @@ -1,28 +0,0 @@ -# Indexes - -## Index types - -Postgres\_ext allows you to specify index type and index operator -class at index creation. - -```ruby -add_index :table_name, :column, :using => :gin -add_index :table_name, :column, :using => :gin, :index_opclass => :gin_trgm_ops -``` - -## Where clauses - -Postgres\_ext allows you to specify a where clause at index creation. - -```ruby -add_index :table_name, :column, :where => 'column < 50' -``` - -## Concurrent Indexes - -Postgres\_ext allows you to create indexes concurrently using the -`:algorithm` option - -```ruby -add_index :table_name, :column, :algorithm => :concurrently -``` diff --git a/docs/migrations.md b/docs/migrations.md deleted file mode 100644 index dcb9968..0000000 --- a/docs/migrations.md +++ /dev/null @@ -1,92 +0,0 @@ -# Migration/Schema.rb support - -## INET - -```ruby -create_table :testing do |t| - t.inet :inet_column - # or - t.inet :inet_column_1, :inet_column_2 - # or - t.column :inet_column, :inet -end -``` - -## CIDR - -```ruby -create_table :testing do |t| - t.cidr :cidr_column - # or - t.cidr :cidr_column_1, :cidr_column_2 - # or - t.column :cidr_column, :cidr -end -``` - -## MACADDR - -```ruby -create_table :testing do |t| - t.macaddr :macaddr_column - # or - t.macaddr :macaddr_column_1, :macaddr_column_2 - # or - t.column :macaddr_column, :macaddr -end -``` - -## UUID - -```ruby -create_table :testing do |t| - t.uuid :uuid_column - # or - t.uuid :uuid_column_1, :uuid_column_2 - # or - t.column :uuid_column, :uuid -end -``` - -## CITEXT - -```ruby -create_table :testing do |t| - t.citext :citext_column - # or - t.citext :citext_column_1, :citext_column_2 - # or - t.column :citext_column, :citext -end -``` - -## Arrays -Arrays are created from any ActiveRecord supported datatype (including -ones added by postgres\_ext), and respect length constraints - -```ruby -create_table :testing do |t| - t.integer :int_array, :array => true - # integer[] - t.integer :int_array, :array => true, :limit => 2 - # smallint[] - t.string :macaddr_column_1, :array => true, :limit => 30 - # char varying(30)[] -end -``` - -### Converting to Arrays - -If you have an existing column with a string-delimited array (e.g. 'val1 val2 val3') convert that data using SQL in your migration. - -```ruby -class AddLinkedArticleIdsToLinkSet < ActiveRecord::Migration - def change - add_column :link_sets, :linked_article_ids, :integer, :array => true, :default => [] - execute <<-eos - UPDATE link_sets - SET linked_article_ids = cast (string_to_array(linked_articles_string, ' ') as integer[]) - eos - end -end -```` diff --git a/docs/type_casting.md b/docs/type_casting.md deleted file mode 100644 index 2c3633d..0000000 --- a/docs/type_casting.md +++ /dev/null @@ -1,70 +0,0 @@ -# Type Casting support - -## INET and CIDR -INET and CIDR values are converted to -[IPAddr](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/ipaddr/rdoc/IPAddr.html) -objects when retrieved from the database, or set as a string. - -```ruby -create_table :inet_examples do |t| - t.inet :ip_address -end - -class InetExample < ActiveRecord::Base -end - -inetExample = InetExample.new -inetExample.ip_address = '127.0.0.0/24' -inetExample.ip_address -# => # -inetExample.save - -inet_2 = InetExample.first -inet_2.ip_address -# => # -``` - -## Arrays -Array values can be set with Array objects. Any array stored in the -database will be converted to a properly casted array of values on the -way out. - -```ruby -create_table :people do |t| - t.integer :favorite_numbers, :array => true -end - -class Person < ActiveRecord::Base -end - -person = Person.new -person.favorite_numbers = [1,2,3] -person.favorite_numbers -# => [1,2,3] -person.save - -person_2 = Person.first -person_2.favorite_numbers -# => [1,2,3] -person_2.favorite_numbers.first.class -# => Fixnum -``` - -## Ranges -Like array objects, postgres\_ext supports range types as well. -Numrange, in4range, int8range, daterange, tsrange, and tstzrange are all -supported, but there are some notable caveats. - -### Int and Date ranges -As integers and days are discrete measurements, PostgreSQL will -normalize these ranges as they are store in the database. PostgreSQL -will convert end-inclusive ranges to end-exclusive, meaning that `0..4` -becomes `0...5`. Developers should be aware of this when using integer -and date ranges, since ruby will treat these ranges differently from -PostgreSQL. - -### Timestamp with and without timezone -Ruby/Rails 3.2.x does not support datetime ranges that begin or end with -infinity. Rails 4 has patched datetime and time so that infinity -terminated ranges work, but currently postgres\_ext has not patched the -required methods. diff --git a/postgres_ext.gemspec b/postgres_ext.gemspec index cd16ffe..96d1480 100644 --- a/postgres_ext.gemspec +++ b/postgres_ext.gemspec @@ -4,8 +4,8 @@ require File.expand_path('../lib/postgres_ext/version', __FILE__) Gem::Specification.new do |gem| gem.authors = ["Dan McClain"] gem.email = ["git@danmcclain.net"] - gem.description = %q{Adds missing native PostgreSQL data types to ActiveRecord} - gem.summary = %q{Extends ActiveRecord to handle native PostgreSQL data types} + gem.description = %q{Provides a helpful querying API for Rails 4 + PostgreSQL} + gem.summary = %q{Provides a helpful querying API for Rails 4 + PostgreSQL} gem.homepage = "" gem.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }