mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
Merge pull request #32646 from derekprior/dp-schema-dumper-documentation
Update schema.rb documentation [CI SKIP]
This commit is contained in:
commit
42c9b560cb
2 changed files with 37 additions and 47 deletions
|
@ -71,11 +71,11 @@ module ActiveRecord
|
|||
# of editing this file, please use the migrations feature of Active Record to
|
||||
# incrementally modify your database, and then regenerate this schema definition.
|
||||
#
|
||||
# Note that this schema.rb definition is the authoritative source for your
|
||||
# database schema. If you need to create the application database on another
|
||||
# system, you should be using db:schema:load, not running all the migrations
|
||||
# from scratch. The latter is a flawed and unsustainable approach (the more migrations
|
||||
# you'll amass, the slower it'll run and the greater likelihood for issues).
|
||||
# This file is the source Rails uses to define your schema when running `rails
|
||||
# db:schema:load`. When creating a new database, `rails db:schema:load` tends to
|
||||
# be faster and is potentially less error prone than running all of your
|
||||
# migrations from scratch. Old migrations may fail to apply correctly if those
|
||||
# migrations use external dependencies or application code.
|
||||
#
|
||||
# It's strongly recommended that you check this file into your version control system.
|
||||
|
||||
|
|
|
@ -917,35 +917,29 @@ Schema Dumping and You
|
|||
### What are Schema Files for?
|
||||
|
||||
Migrations, mighty as they may be, are not the authoritative source for your
|
||||
database schema. That role falls to either `db/schema.rb` or an SQL file which
|
||||
Active Record generates by examining the database. They are not designed to be
|
||||
edited, they just represent the current state of the database.
|
||||
database schema. Your database remains the authoritative source. By default,
|
||||
Rails generates `db/schema.rb` which attempts to capture the current state of
|
||||
your database schema.
|
||||
|
||||
There is no need (and it is error prone) to deploy a new instance of an app by
|
||||
replaying the entire migration history. It is much simpler and faster to just
|
||||
load into the database a description of the current schema.
|
||||
|
||||
For example, this is how the test database is created: the current development
|
||||
database is dumped (either to `db/schema.rb` or `db/structure.sql`) and then
|
||||
loaded into the test database.
|
||||
It tends to be faster and less error prone to create a new instance of your
|
||||
application's database by loading the schema file via `rails db:schema:load`
|
||||
than it is to replay the entire migration history. Old migrations may fail to
|
||||
apply correctly if those migrations use changing external dependencies or rely
|
||||
on application code which evolves separately from your migrations.
|
||||
|
||||
Schema files are also useful if you want a quick look at what attributes an
|
||||
Active Record object has. This information is not in the model's code and is
|
||||
frequently spread across several migrations, but the information is nicely
|
||||
summed up in the schema file. The
|
||||
[annotate_models](https://github.com/ctran/annotate_models) gem automatically
|
||||
adds and updates comments at the top of each model summarizing the schema if
|
||||
you desire that functionality.
|
||||
summed up in the schema file.
|
||||
|
||||
### Types of Schema Dumps
|
||||
|
||||
There are two ways to dump the schema. This is set in `config/application.rb`
|
||||
by the `config.active_record.schema_format` setting, which may be either `:sql`
|
||||
or `:ruby`.
|
||||
The format of the schema dump generated by Rails is controlled by the
|
||||
`config.active_record.schema_format` setting in `config/application.rb`. By
|
||||
default, the format is `:ruby`, but can also be set to `:sql`.
|
||||
|
||||
If `:ruby` is selected, then the schema is stored in `db/schema.rb`. If you look
|
||||
at this file you'll find that it looks an awful lot like one very big
|
||||
migration:
|
||||
at this file you'll find that it looks an awful lot like one very big migration:
|
||||
|
||||
```ruby
|
||||
ActiveRecord::Schema.define(version: 20080906171750) do
|
||||
|
@ -967,36 +961,32 @@ end
|
|||
|
||||
In many ways this is exactly what it is. This file is created by inspecting the
|
||||
database and expressing its structure using `create_table`, `add_index`, and so
|
||||
on. Because this is database-independent, it could be loaded into any database
|
||||
that Active Record supports. This could be very useful if you were to
|
||||
distribute an application that is able to run against multiple databases.
|
||||
on.
|
||||
|
||||
NOTE: `db/schema.rb` cannot express database specific items such as triggers,
|
||||
sequences, stored procedures or check constraints, etc. Please note that while
|
||||
custom SQL statements can be run in migrations, these statements cannot be reconstituted
|
||||
by the schema dumper. If you are using features like this, then you
|
||||
should set the schema format to `:sql`.
|
||||
`db/schema.rb` cannot express everything your database may support such as
|
||||
triggers, sequences, stored procedures, check constraints, etc. While migrations
|
||||
may use `execute` to create database constructs that are not supported by the
|
||||
Ruby migration DSL, these constructs may not be able to be reconstituted by the
|
||||
schema dumper. If you are using features like these, you should set the schema
|
||||
format to `:sql` in order to get an accurate schema file that is useful to
|
||||
create new database instances.
|
||||
|
||||
Instead of using Active Record's schema dumper, the database's structure will
|
||||
be dumped using a tool specific to the database (via the `db:structure:dump`
|
||||
rails task) into `db/structure.sql`. For example, for PostgreSQL, the `pg_dump`
|
||||
utility is used. For MySQL and MariaDB, this file will contain the output of
|
||||
`SHOW CREATE TABLE` for the various tables.
|
||||
When the schema format is set to `:sql`, the database structure will be dumped
|
||||
using a tool specific to the database into `db/structure.sql`. For example, for
|
||||
PostgreSQL, the `pg_dump` utility is used. For MySQL and MariaDB, this file will
|
||||
contain the output of `SHOW CREATE TABLE` for the various tables.
|
||||
|
||||
Loading these schemas is simply a question of executing the SQL statements they
|
||||
contain. By definition, this will create a perfect copy of the database's
|
||||
structure. Using the `:sql` schema format will, however, prevent loading the
|
||||
schema into a RDBMS other than the one used to create it.
|
||||
To load the schema from `db/strcuture.sql`, run `rails db:structure:load`.
|
||||
Loading this file is done by executing the SQL statements it contains. By
|
||||
definition, this will create a perfect copy of the database's structure.
|
||||
|
||||
### Schema Dumps and Source Control
|
||||
|
||||
Because schema dumps are the authoritative source for your database schema, it
|
||||
is strongly recommended that you check them into source control.
|
||||
Because schema files are commonly used to create new databases, it is strongly
|
||||
recommended that you check your schema file into source control.
|
||||
|
||||
`db/schema.rb` contains the current version number of the database. This
|
||||
ensures conflicts are going to happen in the case of a merge where both
|
||||
branches touched the schema. When that happens, solve conflicts manually,
|
||||
keeping the highest version number of the two.
|
||||
Merge conflicts can occur in your schema file when two branches modify schema.
|
||||
To resolve these conflicts run `rails db:migrate` to regenerate the schema file.
|
||||
|
||||
Active Record and Referential Integrity
|
||||
---------------------------------------
|
||||
|
|
Loading…
Reference in a new issue