edge
更多資訊請參考 rubyonrails.org: 更多 Ruby on Rails

Active Record 和 PostgreSQL

本指南介紹了 Active Record 在 PostgreSQL 中的特定用法。

閱讀完本指南後，您將了解：

要使用 PostgreSQL 适配器，您需要安装至少 9.3 版本的 PostgreSQL。不支持旧版本。

要开始使用 PostgreSQL，请查看 配置 Rails 指南。 它描述了如何正确设置 Active Record 以使用 PostgreSQL。

1 數據類型

PostgreSQL 提供了一些特定的數據類型。以下是 PostgreSQL 适配器支持的類型列表。

1.1 Bytea

# db/migrate/20140207133952_create_documents.rb
create_table :documents do |t|
  t.binary 'payload'
end

# app/models/document.rb
class Document < ApplicationRecord
end

# 用法
data = File.read(Rails.root + "tmp/output.pdf")
Document.create payload: data

1.2 Array

# db/migrate/20140207133952_create_books.rb
create_table :books do |t|
  t.string 'title'
  t.string 'tags', array: true
  t.integer 'ratings', array: true
end
add_index :books, :tags, using: 'gin'
add_index :books, :ratings, using: 'gin'

# app/models/book.rb
class Book < ApplicationRecord
end

# 用法
Book.create title: "Brave New World",
            tags: ["fantasy", "fiction"],
            ratings: [4, 5]

## 單個標籤的書籍
Book.where("'fantasy' = ANY (tags)")

## 多個標籤的書籍
Book.where("tags @> ARRAY[?]::varchar[]", ["fantasy", "fiction"])

## 有 3 個或更多評分的書籍
Book.where("array_length(ratings, 1) >= 3")

1.3 Hstore

注意：您需要启用 hstore 擴展才能使用 hstore。

# db/migrate/20131009135255_create_profiles.rb
class CreateProfiles < ActiveRecord::Migration[7.0]
  enable_extension 'hstore' unless extension_enabled?('hstore')
  create_table :profiles do |t|
    t.hstore 'settings'
  end
end

# app/models/profile.rb
class Profile < ApplicationRecord
end

irb> Profile.create(settings: { "color" => "blue", "resolution" => "800x600" })

irb> profile = Profile.first
irb> profile.settings
=> {"color"=>"blue", "resolution"=>"800x600"}

irb> profile.settings = {"color" => "yellow", "resolution" => "1280x1024"}
irb> profile.save!

irb> Profile.where("settings->'color' = ?", "yellow")
=> #<ActiveRecord::Relation [#<Profile id: 1, settings: {"color"=>"yellow", "resolution"=>"1280x1024"}>]>

1.4 JSON 和 JSONB

# db/migrate/20131220144913_create_events.rb
# ... for json 數據類型：
create_table :events do |t|
  t.json 'payload'
end
# ... 或者 for jsonb 數據類型：
create_table :events do |t|
  t.jsonb 'payload'
end

# app/models/event.rb
class Event < ApplicationRecord
end

irb> Event.create(payload: { kind: "user_renamed", change: ["jack", "john"]})

irb> event = Event.first
irb> event.payload
=> {"kind"=>"user_renamed", "change"=>["jack", "john"]}

## 基於 JSON 文檔的查詢
# -> 運算符返回原始的 JSON 類型（可能是對象），而 ->> 返回文本
irb> Event.where("payload->>'kind' = ?", "user_renamed")

1.5 範圍類型

此類型映射到 Ruby Range 對象。

# db/migrate/20130923065404_create_events.rb
create_table :events do |t|
  t.daterange 'duration'
end

# app/models/event.rb
class Event < ApplicationRecord
end

irb> Event.create(duration: Date.new(2014, 2, 11)..Date.new(2014, 2, 12))

irb> event = Event.first
irb> event.duration
=> Tue, 11 Feb 2014...Thu, 13 Feb 2014

## 指定日期的所有事件
irb> Event.where("duration @> ?::date", Date.new(2014, 2, 12))

## 使用範圍邊界
irb> event = Event.select("lower(duration) AS starts_at").select("upper(duration) AS ends_at").first

irb> event.starts_at
=> Tue, 11 Feb 2014
irb> event.ends_at
=> Thu, 13 Feb 2014

1.6 複合類型

目前對於複合類型沒有特殊的支持。它們映射為普通的文本列：

CREATE TYPE full_address AS
(
  city VARCHAR(90),
  street VARCHAR(90)
);

# db/migrate/20140207133952_create_contacts.rb
execute <<-SQL
  CREATE TYPE full_address AS
  (
    city VARCHAR(90),
    street VARCHAR(90)
  );
SQL
create_table :contacts do |t|
  t.column :address, :full_address
end

# app/models/contact.rb
class Contact < ApplicationRecord
end

irb> Contact.create address: "(Paris,Champs-Élysées)"
irb> contact = Contact.first
irb> contact.address
=> "(Paris,Champs-Élysées)"
irb> contact.address = "(Paris,Rue Basse)"
irb> contact.save!

1.7 枚舉類型

該類型可以映射為普通的文本列，或者映射為 ActiveRecord::Enum。

# db/migrate/20131220144913_create_articles.rb
def change
  create_enum :article_status, ["draft", "published", "archived"]

  create_table :articles do |t|
    t.enum :status, enum_type: :article_status, default: "draft", null: false
  end
end

您還可以創建一個枚舉類型並將枚舉列添加到現有表中：

# db/migrate/20230113024409_add_status_to_articles.rb
def change
  create_enum :article_status, ["draft", "published", "archived"]

  add_column :articles, :status, :enum, enum_type: :article_status, default: "draft", null: false
end

上述遷移都是可逆的，但如果需要，您可以定義單獨的 #up 和 #down 方法。在刪除枚舉類型之前，請確保刪除依賴於該枚舉類型的任何列或表：

def down
  drop_table :articles

  # OR: remove_column :articles, :status
  drop_enum :article_status
end

在模型中聲明枚舉屬性會添加輔助方法並防止將無效值分配給該類的實例：

# app/models/article.rb
class Article < ApplicationRecord
  enum status: {
    draft: "draft", published: "published", archived: "archived"
  }, _prefix: true
end

irb> article = Article.create
irb> article.status
=> "draft" # 默認狀態來自 PostgreSQL，如上面的遷移中定義的

irb> article.status_published!
irb> article.status
=> "published"

irb> article.status_archived?
=> false

irb> article.status = "deleted"
ArgumentError: 'deleted' 不是有效的狀態

要重命名枚舉，可以使用 rename_enum 並更新任何模型使用情況：

# db/migrate/20150718144917_rename_article_status.rb
def change
  rename_enum :article_status, to: :article_state
end

要添加新值，可以使用 add_enum_value：

# db/migrate/20150720144913_add_new_state_to_articles.rb
def up
  add_enum_value :article_state, "archived", # 將位於 published 之後
  add_enum_value :article_state, "in review", before: "published"
  add_enum_value :article_state, "approved", after: "in review"
end

注意：無法刪除枚舉值，這也意味著 add_enum_value 是不可逆的。您可以在此處閱讀原因。

要重命名值，可以使用 rename_enum_value：

# db/migrate/20150722144915_rename_article_state.rb
def change
  rename_enum_value :article_state, from: "archived", to: "deleted"
end

提示：要顯示所有枚舉的所有值，可以在 bin/rails db 或 psql 控制台中調用此查詢：

SELECT n.nspname AS enum_schema,
       t.typname AS enum_name,
       e.enumlabel AS enum_value
  FROM pg_type t
      JOIN pg_enum e ON t.oid = e.enumtypid
      JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace

UUID

注意：如果您使用的是早於 13.0 版本的 PostgreSQL，您可能需要啟用特殊擴展來使用 UUID。啟用 pgcrypto 擴展（PostgreSQL >= 9.4）或 uuid-ossp 擴展（更早的版本）。

# db/migrate/20131220144913_create_revisions.rb
create_table :revisions do |t|
  t.uuid :identifier
end

# app/models/revision.rb
class Revision < ApplicationRecord
end

irb> Revision.create identifier: "A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11"

irb> revision = Revision.first
irb> revision.identifier
=> "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

您可以使用 uuid 類型在遷移中定義引用：

# db/migrate/20150418012400_create_blog.rb
enable_extension 'pgcrypto' unless extension_enabled?('pgcrypto')
create_table :posts, id: :uuid

create_table :comments, id: :uuid do |t|
  # t.belongs_to :post, type: :uuid
  t.references :post, type: :uuid
end

# app/models/post.rb
class Post < ApplicationRecord
  has_many :comments
end

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :post
end

有關使用 UUID 作為主鍵的詳細信息，請參見此部分。

位串類型

# db/migrate/20131220144913_create_users.rb
create_table :users, force: true do |t|
  t.column :settings, "bit(8)"
end

# app/models/user.rb
class User < ApplicationRecord
end

irb> User.create settings: "01010011"
irb> user = User.first
irb> user.settings
=> "01010011"
irb> user.settings = "0xAF"
irb> user.settings
=> "10101111"
irb> user.save!

網絡地址類型

inet 和 cidr 類型被映射為 Ruby IPAddr 對象。macaddr 類型被映射為普通文本。

# db/migrate/20140508144913_create_devices.rb
create_table(:devices, force: true) do |t|
  t.inet 'ip'
  t.cidr 'network'
  t.macaddr 'address'
end

# app/models/device.rb
class Device < ApplicationRecord
end

irb> macbook = Device.create(ip: "192.168.1.12", network: "192.168.2.0/24", address: "32:01:16:6d:05:ef")

irb> macbook.ip
=> #<IPAddr: IPv4:192.168.1.12/255.255.255.255>

irb> macbook.network
=> #<IPAddr: IPv4:192.168.2.0/255.255.255.0>

irb> macbook.address
=> "32:01:16:6d:05:ef"

幾何類型

除了 points 之外的所有幾何類型都被映射為普通文本。點被轉換為包含 x 和 y 坐標的數組。

間隔

此類型被映射為 ActiveSupport::Duration 對象。

# db/migrate/20200120000000_create_events.rb
create_table :events do |t|
  t.interval 'duration'
end

# app/models/event.rb
class Event < ApplicationRecord
end

irb> Event.create(duration: 2.days)

irb> event = Event.first
irb> event.duration
=> 2 days

2 UUID 主鍵

注意：您需要啟用 pgcrypto（僅限 PostgreSQL >= 9.4）或 uuid-ossp 擴展來生成隨機 UUID。 ```ruby

db/migrate/20131220144913_create_devices.rb

enable_extension 'pgcrypto' unless extension_enabled?('pgcrypto') create_table :devices, id: :uuid do |t| t.string :kind end ```

# app/models/device.rb
class Device < ApplicationRecord
end

irb> device = Device.create
irb> device.id
=> "814865cd-5a1d-4771-9306-4268f188fe9e"

注意：如果在create_table中沒有傳遞:default選項，則假設使用pgcrypto中的gen_random_uuid()。

若要使用Rails模型生成器創建使用UUID作為主鍵的表，請將--primary-key-type=uuid傳遞給模型生成器。

例如：

$ rails generate model Device --primary-key-type=uuid kind:string

在建立引用此UUID的外鍵的模型時，將uuid視為本地字段類型，例如：

$ rails generate model Case device_id:uuid

3 索引

PostgreSQL包含各種索引選項。除了常見的索引選項外，PostgreSQL適配器還支持以下選項。

3.1 包含

在創建新索引時，可以使用:include選項包含非鍵列。這些鍵不用於搜索索引掃描，但可以在僅索引掃描期間讀取，而無需訪問相關聯的表。

# db/migrate/20131220144913_add_index_users_on_email_include_id.rb

add_index :users, :email, include: :id

支持多個列：

# db/migrate/20131220144913_add_index_users_on_email_include_id_and_created_at.rb

add_index :users, :email, include: [:id, :created_at]

4 生成列

注意：自PostgreSQL 12.0版本起支持生成列。

# db/migrate/20131220144913_create_users.rb
create_table :users do |t|
  t.string :name
  t.virtual :name_upcased, type: :string, as: 'upper(name)', stored: true
end

# app/models/user.rb
class User < ApplicationRecord
end

# 使用方法
user = User.create(name: 'John')
User.last.name_upcased # => "JOHN"

5 可延遲的外鍵

預設情況下，PostgreSQL中的表約束在每個語句之後立即進行檢查。它有意不允許創建引用表中尚未存在的引用記錄的記錄。但是，可以通過在外鍵定義中添加DEFERRABLE來在事務提交時稍後運行此完整性檢查。要默認推遲所有檢查，可以將其設置為DEFERRABLE INITIALLY DEFERRED。Rails通過在add_reference和add_foreign_key方法的foreign_key選項中添加:deferrable鍵來公開此PostgreSQL功能。

一個例子是即使創建了外鍵，也可以在事務中創建循環依賴關係，只需添加deferrable: :deferred選項。

add_reference :person, :alias, foreign_key: { deferrable: :deferred }
add_reference :alias, :person, foreign_key: { deferrable: :deferred }

如果使用foreign_key: true選項創建了引用，則在執行第一個INSERT語句時，以下事務將失敗。但是，如果設置了deferrable: :deferred選項，則不會失敗。

ActiveRecord::Base.connection.transaction do
  person = Person.create(id: SecureRandom.uuid, alias_id: SecureRandom.uuid, name: "John Doe")
  Alias.create(id: person.alias_id, person_id: person.id, name: "jaydee")
end

當deferrable選項設置為immediate時，讓外鍵保持默認行為，即立即檢查約束，但允許在事務中手動推遲檢查，使用SET CONSTRAINTS ALL DEFERRED。這將導致在提交事務時檢查外鍵：

ActiveRecord::Base.transaction do
  ActiveRecord::Base.connection.execute("SET CONSTRAINTS ALL DEFERRED")
  person = Person.create(alias_id: SecureRandom.uuid, name: "John Doe")
  Alias.create(id: person.alias_id, person_id: person.id, name: "jaydee")
end

默認情況下，:deferrable為false，約束始終立即檢查。

6 唯一約束

# db/migrate/20230422225213_create_items.rb
create_table :items do |t|
  t.integer :position, null: false
  t.unique_key [:position], deferrable: :immediate
end

如果要將現有的唯一索引更改為可推遲，可以使用:using_index創建可推遲的唯一約束。

add_unique_key :items, deferrable: :deferred, using_index: "index_items_on_position"

與外鍵一樣，通過將:deferrable設置為immediate或deferred，可以推遲唯一約束。默認情況下，:deferrable為false，約束始終立即檢查。

7 排除約束

# db/migrate/20131220144913_create_products.rb
create_table :products do |t|
  t.integer :price, null: false
  t.daterange :availability_range, null: false

  t.exclusion_constraint "price WITH =, availability_range WITH &&", using: :gist, name: "price_check"
end

與外鍵一樣，通過將:deferrable設置為immediate或deferred，可以推遲排除約束。默認情況下，:deferrable為false，約束始終立即檢查。

8 全文搜索

# db/migrate/20131220144913_create_documents.rb
create_table :documents do |t|
  t.string :title
  t.string :body
end

add_index :documents, "to_tsvector('english', title || ' ' || body)", using: :gin, name: 'documents_idx'

# app/models/document.rb
class Document < ApplicationRecord
end

# 使用方法
Document.create(title: "貓和狗", body: "很可愛！")

## 所有符合 '貓和狗' 的文件
Document.where("to_tsvector('english', title || ' ' || body) @@ to_tsquery(?)",
                 "貓 & 狗")

可選地，您可以將向量存儲為自動生成的列（從 PostgreSQL 12.0 開始）：

# db/migrate/20131220144913_create_documents.rb
create_table :documents do |t|
  t.string :title
  t.string :body

  t.virtual :textsearchable_index_col,
            type: :tsvector, as: "to_tsvector('english', title || ' ' || body)", stored: true
end

add_index :documents, :textsearchable_index_col, using: :gin, name: 'documents_idx'

# 使用方法
Document.create(title: "貓和狗", body: "很可愛！")

## 所有符合 '貓和狗' 的文件
Document.where("textsearchable_index_col @@ to_tsquery(?)", "貓 & 狗")

9 數據庫視圖

假設您需要使用包含以下表的舊版數據庫進行工作：

rails_pg_guide=# \d "TBL_ART"
                                        表格 "public.TBL_ART"
   列名   |            類型             |                         修飾符
------------+-----------------------------+------------------------------------------------------------
 INT_ID     | 整數                        | 非空默認值 nextval('"TBL_ART_INT_ID_seq"'::regclass)
 STR_TITLE  | 字符串                      |
 STR_STAT   | 字符串                      | 默認值 'draft'::字符
 DT_PUBL_AT | 沒有時區的時間戳             |
 BL_ARCH    | 布爾值                      | 默認值 false
索引：
    "TBL_ART_pkey" 主鍵, btree ("INT_ID")

該表格完全不符合 Rails 的慣例。 由於簡單的 PostgreSQL 視圖默認是可更新的， 我們可以將其封裝如下：

# db/migrate/20131220144913_create_articles_view.rb
execute <<-SQL
CREATE VIEW articles AS
  SELECT "INT_ID" AS id,
         "STR_TITLE" AS title,
         "STR_STAT" AS status,
         "DT_PUBL_AT" AS published_at,
         "BL_ARCH" AS archived
  FROM "TBL_ART"
  WHERE "BL_ARCH" = 'f'
SQL

# app/models/article.rb
class Article < ApplicationRecord
  self.primary_key = "id"
  def archive!
    update_attribute :archived, true
  end
end

irb> first = Article.create! title: "冬天來了", status: "已發布", published_at: 1.year.ago
irb> second = Article.create! title: "做好準備", status: "草稿", published_at: 1.month.ago

irb> Article.count
=> 2
irb> first.archive!
irb> Article.count
=> 1

注意：此應用程序僅關注未存檔的 文章。視圖還允許條件，因此我們可以直接排除已存檔的 文章。

10 結構備份

如果您的 config.active_record.schema_format 是 :sql，Rails 將調用 pg_dump 生成結構備份。

您可以使用 ActiveRecord::Tasks::DatabaseTasks.structure_dump_flags 配置 pg_dump。 例如，要從結構備份中排除註釋，請將以下代碼添加到初始化程序中：

ActiveRecord::Tasks::DatabaseTasks.structure_dump_flags = ['--no-comments']

回饋

歡迎協助提升本指南的品質。

如果您發現任何錯別字或事實錯誤，請貢獻您的力量。 開始之前，您可以閱讀我們的 文件貢獻 部分。

您也可能會發現不完整的內容或過時的資訊。 請為主要的文件補充任何遺漏的內容。請先檢查 Edge 指南，以確認問題是否已經修復或尚未在主分支上修復。 請參考 Ruby on Rails 指南指引 以了解風格和慣例。

如果您發現需要修復但無法自行修補的問題，請 開啟一個問題。

最後但同樣重要的是，關於 Ruby on Rails 文件的任何討論都非常歡迎在 官方 Ruby on Rails 論壇 上進行。