Permalink
Browse files

Create gh-pages branch via GitHub

  • Loading branch information...
1 parent 5a0b4fb commit edaac309acd84ed3ccebf2227c957900b304c36c @diogob committed Feb 7, 2013
Showing with 9 additions and 19 deletions.
  1. +8 −18 index.html
  2. +1 −1 params.json
View
@@ -101,16 +101,20 @@
<p>You’re done.
Well, not yet. Don’t forget to add indexes. Like this:</p>
-<p><code>sql CREATE INDEX people_gist_data ON people USING GIST(data);</code>
-or
-<code>sql CREATE INDEX people_gin_data ON people USING GIN(data);</code></p>
+<div class="highlight"><pre><span class="k">CREATE</span> <span class="k">INDEX</span> <span class="n">people_gist_data</span> <span class="k">ON</span> <span class="n">people</span> <span class="k">USING</span> <span class="n">GIST</span><span class="p">(</span><span class="k">data</span><span class="p">);</span>
+</pre></div>
+
+<p>or</p>
+
+<div class="highlight"><pre><span class="k">CREATE</span> <span class="k">INDEX</span> <span class="n">people_gin_data</span> <span class="k">ON</span> <span class="n">people</span> <span class="k">USING</span> <span class="n">GIN</span><span class="p">(</span><span class="k">data</span><span class="p">);</span>
+</pre></div>
<p>This gem provides some functions to generate this kind of index inside your migrations.
For the model Person we could create an index (defaults to type GIST) over the data field with this migration:</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">AddIndexToPeople</span> <span class="o">&lt;</span> <span class="no">ActiveRecord</span><span class="o">::</span><span class="no">Migration</span>
<span class="k">def</span> <span class="nf">change</span>
- <span class="n">add_hstore_index</span> <span class="ss">:people</span><span class="p">,</span> <span class="ss">:data</span>
+ <span class="n">add_hstore_index</span> <span class="ss">:people</span><span class="p">,</span> <span class="ss">:data</span>
<span class="k">end</span>
<span class="k">end</span>
</pre></div>
@@ -135,14 +139,6 @@
<span class="k">end</span>
</pre></div>
-<p>If you want a default value (say, an empty hash) you should pass it as an argument when you
-initialize the serializer, like so:</p>
-
-<div class="highlight"><pre><span class="k">class</span> <span class="nc">Person</span> <span class="o">&lt;</span> <span class="no">ActiveRecord</span><span class="o">::</span><span class="no">Base</span>
- <span class="n">serialize</span> <span class="ss">:data</span><span class="p">,</span> <span class="no">ActiveRecord</span><span class="o">::</span><span class="no">Coders</span><span class="o">::</span><span class="no">Hstore</span><span class="o">.</span><span class="n">new</span><span class="p">({})</span>
-<span class="k">end</span>
-</pre></div>
-
<p>This way, you will automatically start with an empty hash that you can write attributes to.</p>
<pre><code>irb(main):001:0&gt; person = Person.new
@@ -151,12 +147,6 @@
=&gt; "blue"
</code></pre>
-<p>If you skip this step, you will have to manually initialize the value to an empty hash before
-writing to the attribute, or else you will get an error:</p>
-
-<pre><code>NoMethodError: undefined method `[]=' for nil:NilClass
-</code></pre>
-
<h3>Querying the database</h3>
<p>Now you just need to learn a little bit of new
View
@@ -1 +1 @@
-{"google":"","note":"Don't delete this file! It's used internally to help with page regeneration.","body":"#Goodbye serialize, hello hstore. [![Build Status](https://secure.travis-ci.org/softa/activerecord-postgres-hstore.png?branch=master)](http://travis-ci.org/softa/activerecord-postgres-hstore)\r\n\r\nYou need dynamic columns in your tables. What do you do?\r\n\r\n* Create lots of tables to handle it. Nice, now you’ll need more models and lots of additional sqls. Insertion and selection will be slow as hell.\r\n* Use a noSQL database just for this issue. Good luck.\r\n* Create a serialized column. Nice, insertion will be fine, and reading data from a record too. But, what if you have a condition in your select that includes serialized data? Yeah, regular expressions.\r\n\r\n##Note about 0.7\r\n\r\nI have decided to clean up the old code and provide only a custom serializer in this new version.\r\n\r\nIn order to acomplish this I had to drop support for older versions of Rails (3.0 and earlier) and also\r\nremove some monkey patches that added functionality to the Hash, String, and some ActiveRecord objects.\r\nThis monkey patches provided methods such as Hash\\#to\\_hstore and String\\#from\\_hstore.\r\n\r\n\r\n**If you rely on this feature please stick to 0.6 version** and there is still a branch named 0.6 to which you can submit your pull requests.\r\n\r\n##Requirements\r\n\r\nPostgresql 8.4+ with contrib and Rails 3.1+ (If you want to try on older rails versions I recommend the 0.6 and ealier versions of this gem)\r\nOn Ubuntu, this is easy: `sudo apt-get install postgresql-contrib-9.1`\r\n\r\nOn Mac you have a couple of options:\r\n\r\n* [the binary package kindly provided by EnterpriseDB](http://www.enterprisedb.com/products-services-training/pgdownload#osx)\r\n* [Homebrew’s](https://github.com/mxcl/homebrew) Postgres installation also includes the contrib packages: `brew install postgres`\r\n* [Postgres.app](http://postgresapp.com/)\r\n\r\n##Install\r\n\r\n\r\nHstore is a PostgreSQL contrib type, [check it out first](http://www.postgresql.org/docs/9.2/static/hstore.html).\r\n\r\nThen, just add this to your Gemfile:\r\n\r\n`gem 'activerecord-postgres-hstore'`\r\n\r\nAnd run your bundler:\r\n\r\n`bundle install`\r\n\r\nNow you need to create a migration that adds hstore support for your\r\nPostgreSQL database:\r\n\r\n`rails g hstore:setup`\r\n\r\nRun it:\r\n\r\n`rake db:migrate`\r\n\r\nFinally you can create your own tables using hstore type. It’s easy:\r\n\r\n rails g model Person name:string data:hstore\r\n rake db:migrate\r\n\r\nYou’re done.\r\nWell, not yet. Don’t forget to add indexes. Like this:\r\n\r\n```sql CREATE INDEX people_gist_data ON people USING GIST(data);```\r\nor\r\n```sql CREATE INDEX people_gin_data ON people USING GIN(data);```\r\n\r\nThis gem provides some functions to generate this kind of index inside your migrations.\r\nFor the model Person we could create an index (defaults to type GIST) over the data field with this migration:\r\n\r\n```ruby\r\nclass AddIndexToPeople < ActiveRecord::Migration\r\n def change\r\n add_hstore_index :people, :data \r\n end \r\nend\r\n```\r\n\r\nTo understand the difference between the two types of indexes take a\r\nlook at [PostgreSQL docs](http://www.postgresql.org/docs/9.2/static/textsearch-indexes.html).\r\n\r\n##Usage\r\n\r\nThis gem only provides a custom serialization coder.\r\nIf you want to use it just put in your Gemfile:\r\n\r\n gem 'activerecord-postgres-hstore'\r\n\r\nNow add a line (for each hstore column) on the model you have your hstore columns.\r\nAssuming a model called **Person**, with a **data** field on it, the\r\ncode should look like:\r\n\r\n```ruby\r\nclass Person < ActiveRecord::Base\r\n serialize :data, ActiveRecord::Coders::Hstore\r\nend\r\n```\r\n\r\nIf you want a default value (say, an empty hash) you should pass it as an argument when you\r\ninitialize the serializer, like so:\r\n\r\n```ruby\r\nclass Person < ActiveRecord::Base\r\n serialize :data, ActiveRecord::Coders::Hstore.new({})\r\nend\r\n```\r\n\r\nThis way, you will automatically start with an empty hash that you can write attributes to.\r\n\r\n irb(main):001:0> person = Person.new\r\n => #<Person id: nil, name: nil, data: {}, created_at: nil, updated_at: nil>\r\n irb(main):002:0> person.data['favorite_color'] = 'blue'\r\n => \"blue\"\r\n\r\nIf you skip this step, you will have to manually initialize the value to an empty hash before\r\nwriting to the attribute, or else you will get an error:\r\n\r\n NoMethodError: undefined method `[]=' for nil:NilClass\r\n\r\n###Querying the database\r\n\r\nNow you just need to learn a little bit of new\r\nsqls for selecting stuff (creating and updating is transparent).\r\nFind records that contains a key named 'foo’:\r\n\r\n Person.where(\"data ? 'foo'\")\r\n\r\nFind records where 'foo’ is equal to 'bar’:\r\n\r\n Person.where(\"data -> 'foo' = 'bar'\")\r\n\r\nThis same sql is at least twice as fast (using indexes) if you do it\r\nthat way:\r\n\r\n Person.where(\"data @> 'foo=>bar'\")\r\n\r\nFind records where 'foo’ is not equal to 'bar’:\r\n\r\n Person.where(\"data -> 'foo' <> 'bar'\")\r\n\r\nFind records where 'foo’ is like 'bar’:\r\n\r\n Person.where(\"data -> 'foo' LIKE '%bar%'\")\r\n\r\nIf you need to delete a key in a record, you can do it that way:\r\n\r\n person.destroy_key(:data, :foo)\r\n\r\nThis way you’ll also save the record:\r\n\r\n person.destroy_key!(:data, :foo)\r\n\r\nThe destroy\\_key method returns 'self’, so you can chain it:\r\n\r\n person.destroy_key(:data, :foo).destroy_key(:data, :bar).save\r\n\r\nBut there is a shortcuts for that:\r\n\r\n person.destroy_keys(:data, :foo, :bar)\r\n\r\nAnd finally, if you need to delete keys in many rows, you can:\r\n\r\n Person.delete_key(:data, :foo)\r\n\r\nand with many keys:\r\n\r\n Person.delete_keys(:data, :foo, :bar)\r\n\r\n##Caveats\r\n\r\nhstore keys and values have to be strings. This means `true` will become `\"true\"` and `42` will become `\"42\"` after you save the record. Only `nil` values are preserved.\r\n\r\nIt is also confusing when querying:\r\n\r\n Person.where(\"data -> 'foo' = :value\", value: true).to_sql\r\n #=> SELECT \"people\".* FROM \"people\" WHERE (\"data -> 'foo' = 't'\") # notice 't'\r\n\r\nTo avoid the above, make sure all named parameters are strings:\r\n\r\n Person.where(\"data -> 'foo' = :value\", value: some_var.to_s)\r\n\r\nHave fun.\r\n\r\n##Test Database\r\n\r\nTo have hstore enabled when you load your database schema (as happens in rake db:test:prepare), you\r\nhave two options.\r\n\r\nThe first option is creating a template database with hstore installed and set the template option\r\nin database.yml to that database.\r\n\r\nThe second option is to uncomment or add the following line in config/application.rb\r\n\r\n config.active_record.schema_format = :sql\r\n\r\nThis will change your schema dumps from Ruby to SQL. If you're\r\nunsure about the implications of this change, we suggest reading this\r\n[Rails Guide](http://guides.rubyonrails.org/migrations.html#schema-dumping-and-you).\r\n\r\n##Help\r\n\r\nYou can use issues in github for that. Or else you can reach us at\r\ntwitter: [@dbiazus](https://twitter.com/#!/dbiazus) or [@joaomilho](https://twitter.com/#!/joaomilho)\r\n\r\n##Note on Patches/Pull Requests\r\n\r\n\r\n* Fork the project.\r\n* Make your feature addition or bug fix.\r\n* Add tests for it. This is important so I don’t break it in a future version unintentionally.\r\n* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)\r\n* Send me a pull request. Bonus points for topic branches.\r\n\r\n##Copyright\r\n\r\nCopyright © 2010 Juan Maiz. See LICENSE for details.\r\n","name":"activerecord-postgres-hstore","tagline":"Goodbye serialize, hello hstore. Speed up hashes in the database."}
+{"tagline":"Goodbye serialize, hello hstore. Speed up hashes in the database.","google":"","body":"#Goodbye serialize, hello hstore. [![Build Status](https://secure.travis-ci.org/softa/activerecord-postgres-hstore.png?branch=master)](http://travis-ci.org/softa/activerecord-postgres-hstore)\r\n\r\nYou need dynamic columns in your tables. What do you do?\r\n\r\n* Create lots of tables to handle it. Nice, now you’ll need more models and lots of additional sqls. Insertion and selection will be slow as hell.\r\n* Use a noSQL database just for this issue. Good luck.\r\n* Create a serialized column. Nice, insertion will be fine, and reading data from a record too. But, what if you have a condition in your select that includes serialized data? Yeah, regular expressions.\r\n\r\n##Note about 0.7\r\n\r\nI have decided to clean up the old code and provide only a custom serializer in this new version.\r\n\r\nIn order to acomplish this I had to drop support for older versions of Rails (3.0 and earlier) and also\r\nremove some monkey patches that added functionality to the Hash, String, and some ActiveRecord objects.\r\nThis monkey patches provided methods such as Hash\\#to\\_hstore and String\\#from\\_hstore.\r\n\r\n\r\n**If you rely on this feature please stick to 0.6 version** and there is still a branch named 0.6 to which you can submit your pull requests.\r\n\r\n##Requirements\r\n\r\nPostgresql 8.4+ with contrib and Rails 3.1+ (If you want to try on older rails versions I recommend the 0.6 and ealier versions of this gem)\r\nOn Ubuntu, this is easy: `sudo apt-get install postgresql-contrib-9.1`\r\n\r\nOn Mac you have a couple of options:\r\n\r\n* [the binary package kindly provided by EnterpriseDB](http://www.enterprisedb.com/products-services-training/pgdownload#osx)\r\n* [Homebrew’s](https://github.com/mxcl/homebrew) Postgres installation also includes the contrib packages: `brew install postgres`\r\n* [Postgres.app](http://postgresapp.com/)\r\n\r\n##Install\r\n\r\n\r\nHstore is a PostgreSQL contrib type, [check it out first](http://www.postgresql.org/docs/9.2/static/hstore.html).\r\n\r\nThen, just add this to your Gemfile:\r\n\r\n`gem 'activerecord-postgres-hstore'`\r\n\r\nAnd run your bundler:\r\n\r\n`bundle install`\r\n\r\nNow you need to create a migration that adds hstore support for your\r\nPostgreSQL database:\r\n\r\n`rails g hstore:setup`\r\n\r\nRun it:\r\n\r\n`rake db:migrate`\r\n\r\nFinally you can create your own tables using hstore type. It’s easy:\r\n\r\n rails g model Person name:string data:hstore\r\n rake db:migrate\r\n\r\nYou’re done.\r\nWell, not yet. Don’t forget to add indexes. Like this:\r\n\r\n```sql\r\nCREATE INDEX people_gist_data ON people USING GIST(data);\r\n```\r\nor\r\n```sql \r\nCREATE INDEX people_gin_data ON people USING GIN(data);\r\n```\r\n\r\nThis gem provides some functions to generate this kind of index inside your migrations.\r\nFor the model Person we could create an index (defaults to type GIST) over the data field with this migration:\r\n\r\n```ruby\r\nclass AddIndexToPeople < ActiveRecord::Migration\r\n def change\r\n add_hstore_index :people, :data\r\n end \r\nend\r\n```\r\n\r\nTo understand the difference between the two types of indexes take a\r\nlook at [PostgreSQL docs](http://www.postgresql.org/docs/9.2/static/textsearch-indexes.html).\r\n\r\n##Usage\r\n\r\nThis gem only provides a custom serialization coder.\r\nIf you want to use it just put in your Gemfile:\r\n\r\n gem 'activerecord-postgres-hstore'\r\n\r\nNow add a line (for each hstore column) on the model you have your hstore columns.\r\nAssuming a model called **Person**, with a **data** field on it, the\r\ncode should look like:\r\n\r\n```ruby\r\nclass Person < ActiveRecord::Base\r\n serialize :data, ActiveRecord::Coders::Hstore\r\nend\r\n```\r\n\r\nThis way, you will automatically start with an empty hash that you can write attributes to.\r\n\r\n irb(main):001:0> person = Person.new\r\n => #<Person id: nil, name: nil, data: {}, created_at: nil, updated_at: nil>\r\n irb(main):002:0> person.data['favorite_color'] = 'blue'\r\n => \"blue\"\r\n\r\n###Querying the database\r\n\r\nNow you just need to learn a little bit of new\r\nsqls for selecting stuff (creating and updating is transparent).\r\nFind records that contains a key named 'foo’:\r\n\r\n Person.where(\"data ? 'foo'\")\r\n\r\nFind records where 'foo’ is equal to 'bar’:\r\n\r\n Person.where(\"data -> 'foo' = 'bar'\")\r\n\r\nThis same sql is at least twice as fast (using indexes) if you do it\r\nthat way:\r\n\r\n Person.where(\"data @> 'foo=>bar'\")\r\n\r\nFind records where 'foo’ is not equal to 'bar’:\r\n\r\n Person.where(\"data -> 'foo' <> 'bar'\")\r\n\r\nFind records where 'foo’ is like 'bar’:\r\n\r\n Person.where(\"data -> 'foo' LIKE '%bar%'\")\r\n\r\nIf you need to delete a key in a record, you can do it that way:\r\n\r\n person.destroy_key(:data, :foo)\r\n\r\nThis way you’ll also save the record:\r\n\r\n person.destroy_key!(:data, :foo)\r\n\r\nThe destroy\\_key method returns 'self’, so you can chain it:\r\n\r\n person.destroy_key(:data, :foo).destroy_key(:data, :bar).save\r\n\r\nBut there is a shortcuts for that:\r\n\r\n person.destroy_keys(:data, :foo, :bar)\r\n\r\nAnd finally, if you need to delete keys in many rows, you can:\r\n\r\n Person.delete_key(:data, :foo)\r\n\r\nand with many keys:\r\n\r\n Person.delete_keys(:data, :foo, :bar)\r\n\r\n##Caveats\r\n\r\nhstore keys and values have to be strings. This means `true` will become `\"true\"` and `42` will become `\"42\"` after you save the record. Only `nil` values are preserved.\r\n\r\nIt is also confusing when querying:\r\n\r\n Person.where(\"data -> 'foo' = :value\", value: true).to_sql\r\n #=> SELECT \"people\".* FROM \"people\" WHERE (\"data -> 'foo' = 't'\") # notice 't'\r\n\r\nTo avoid the above, make sure all named parameters are strings:\r\n\r\n Person.where(\"data -> 'foo' = :value\", value: some_var.to_s)\r\n\r\nHave fun.\r\n\r\n##Test Database\r\n\r\nTo have hstore enabled when you load your database schema (as happens in rake db:test:prepare), you\r\nhave two options.\r\n\r\nThe first option is creating a template database with hstore installed and set the template option\r\nin database.yml to that database.\r\n\r\nThe second option is to uncomment or add the following line in config/application.rb\r\n\r\n config.active_record.schema_format = :sql\r\n\r\nThis will change your schema dumps from Ruby to SQL. If you're\r\nunsure about the implications of this change, we suggest reading this\r\n[Rails Guide](http://guides.rubyonrails.org/migrations.html#schema-dumping-and-you).\r\n\r\n##Help\r\n\r\nYou can use issues in github for that. Or else you can reach us at\r\ntwitter: [@dbiazus](https://twitter.com/#!/dbiazus) or [@joaomilho](https://twitter.com/#!/joaomilho)\r\n\r\n##Note on Patches/Pull Requests\r\n\r\n\r\n* Fork the project.\r\n* Make your feature addition or bug fix.\r\n* Add tests for it. This is important so I don’t break it in a future version unintentionally.\r\n* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)\r\n* Send me a pull request. Bonus points for topic branches.\r\n\r\n##Copyright\r\n\r\nCopyright © 2010 Juan Maiz. See LICENSE for details.\r\n","note":"Don't delete this file! It's used internally to help with page regeneration.","name":"activerecord-postgres-hstore"}

0 comments on commit edaac30

Please sign in to comment.