{"action":"created","issue":{"url":"https://api.github.com/repos/rails/rails/issues/22911","repository_url":"https://api.github.com/repos/rails/rails","labels_url":"https://api.github.com/repos/rails/rails/issues/22911/labels{/name}","comments_url":"https://api.github.com/repos/rails/rails/issues/22911/comments","events_url":"https://api.github.com/repos/rails/rails/issues/22911/events","html_url":"https://github.com/rails/rails/pull/22911","id":124767565,"number":22911,"title":"Add support for specifying comments for tables, columns, and indexes in database itself","user":{"login":"Envek","id":264400,"avatar_url":"https://avatars.githubusercontent.com/u/264400?v=3","gravatar_id":"","url":"https://api.github.com/users/Envek","html_url":"https://github.com/Envek","followers_url":"https://api.github.com/users/Envek/followers","following_url":"https://api.github.com/users/Envek/following{/other_user}","gists_url":"https://api.github.com/users/Envek/gists{/gist_id}","starred_url":"https://api.github.com/users/Envek/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Envek/subscriptions","organizations_url":"https://api.github.com/users/Envek/orgs","repos_url":"https://api.github.com/users/Envek/repos","events_url":"https://api.github.com/users/Envek/events{/privacy}","received_events_url":"https://api.github.com/users/Envek/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/rails/rails/labels/activerecord","name":"activerecord","color":"0b02e1"}],"state":"open","locked":false,"assignee":{"login":"rafaelfranca","id":47848,"avatar_url":"https://avatars.githubusercontent.com/u/47848?v=3","gravatar_id":"","url":"https://api.github.com/users/rafaelfranca","html_url":"https://github.com/rafaelfranca","followers_url":"https://api.github.com/users/rafaelfranca/followers","following_url":"https://api.github.com/users/rafaelfranca/following{/other_user}","gists_url":"https://api.github.com/users/rafaelfranca/gists{/gist_id}","starred_url":"https://api.github.com/users/rafaelfranca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rafaelfranca/subscriptions","organizations_url":"https://api.github.com/users/rafaelfranca/orgs","repos_url":"https://api.github.com/users/rafaelfranca/repos","events_url":"https://api.github.com/users/rafaelfranca/events{/privacy}","received_events_url":"https://api.github.com/users/rafaelfranca/received_events","type":"User","site_admin":false},"milestone":null,"comments":12,"created_at":"2016-01-04T14:23:07Z","updated_at":"2016-04-16T17:43:39Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/rails/rails/pulls/22911","html_url":"https://github.com/rails/rails/pull/22911","diff_url":"https://github.com/rails/rails/pull/22911.diff","patch_url":"https://github.com/rails/rails/pull/22911.patch"},"body":"This pull request adds support for specifying comments for database objects in migrations, storing them inside database, and dumping them into `db/schema.rb` file for PostgreSQL and MySQL.\r\n\r\n```ruby\r\ncreate_table \"pages\", force: :cascade, comment: 'Arbitrary content pages' do |t|\r\n  # ...\r\n  t.string \"path\",    comment: \"Path fragment of page URL used for routing\"\r\n  t.string \"locale\",  comment: \"RFC 3066 locale code of website language section\"\r\n  t.index [\"locale\", \"path\"], name: 'page_uri_index' comment: \"Main index used to lookup page by it's URI.\"\r\n  t.text   \"content\", comment: \"HTML code of page\"\r\n  # ...\r\nend\r\n```\r\n\r\nIn my opinion it is really useful feature, allowing people to create documented data model right from Rails migrations. New people can look for tables, columns, and indexes meaning right in `db/schema.rb` (or right in model files with gems like @ctran's [annotate_models]) and DBA can view that information directly from MySQL Workbench, PgAdmin III, DBeaver or anything else. Afterwards any existing data modelling tool can be used to generate data model documentation (such as ER diagrams and table structure) automatically with minimal editing.\r\n\r\nFor example in my work recently was situation when we were need to send documentation to customer and database schema was part of it. We lost a day helping writers to make this docs as we explained tables and table columns meaning only in our internal wiki (and it was incomplete because everyone always forgets to edit it when writing a migration) and writers came to us with autogenerated docs from our staging database. And there was a lot of manual docs merging and investigation.\r\n\r\nAmong built in adapters only PostgreSQL and MySQL supports it (SQLite does not). Also [oracle_enhanced] adapter supports comments with exactly same syntax (actually I follow it's syntax). May be @rsim, @yahonda, or @cdinger will also review and say whether I should change something for ease of integration of [oracle_enhanced] implementation with my implementation.\r\n\r\nComment implementation in RDBMS differs heavily:\r\n\r\n * PostgreSQL have only separate `COMMENT` command to set or delete comments on any database objects (like Oracle) and have no syntax to specify comments at time of creation or modification object. See docs: http://www.postgresql.org/docs/current/static/sql-comment.html\r\n * MySQL only have special options in syntax of `CREATE TABLE` and `ALTER TABLE` commands and column and index definitions. No separate commands. See docs: http://dev.mysql.com/doc/refman/5.7/en/create-table.html\r\n\r\nHere ActiveRecord takes all dirty work and hides all differences between implementations. I think this is awesome.\r\n\r\nUnfortunately I'm not really experienced in ActiveRecord hacking and most of the work I have done blindly, just by inserting code chunks here and there and seeing what errors will occur and whether tests will pass. Is there any docs about ActiveRecord internals and architecture? I would be glad to read them. Please review carefully and tell me what I should change. I think this PR should be considered as Work In Progress, hence it already do it's job well.\r\n\r\nAlso I think that note about importance of schema documentation should be added to guides, but can't imagine good place and good words for it (and my English really isn't good enough for guides yet). Any suggestions are welcome!\r\n\r\n[annotate_models]: https://github.com/ctran/annotate_models\r\n[oracle_enhanced]: https://github.com/rsim/oracle-enhanced"},"comment":{"url":"https://api.github.com/repos/rails/rails/issues/comments/210862525","html_url":"https://github.com/rails/rails/pull/22911#issuecomment-210862525","issue_url":"https://api.github.com/repos/rails/rails/issues/22911","id":210862525,"user":{"login":"Envek","id":264400,"avatar_url":"https://avatars.githubusercontent.com/u/264400?v=3","gravatar_id":"","url":"https://api.github.com/users/Envek","html_url":"https://github.com/Envek","followers_url":"https://api.github.com/users/Envek/followers","following_url":"https://api.github.com/users/Envek/following{/other_user}","gists_url":"https://api.github.com/users/Envek/gists{/gist_id}","starred_url":"https://api.github.com/users/Envek/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Envek/subscriptions","organizations_url":"https://api.github.com/users/Envek/orgs","repos_url":"https://api.github.com/users/Envek/repos","events_url":"https://api.github.com/users/Envek/events{/privacy}","received_events_url":"https://api.github.com/users/Envek/received_events","type":"User","site_admin":false},"created_at":"2016-04-16T17:43:39Z","updated_at":"2016-04-16T17:43:39Z","body":"@rafaelfranca Is there any chance to get it into 5.0?"}}