修订文件名遵循 [id].[timestamp].[name].sql 的模式。

时间戳是捕捉的绝佳元数据，而 jrny 为每个文件分配一个顺序 ID。这样做是为了强制执行比仅使用时间戳更严格的修订顺序，而无需在文件之间设置指针。（有关更多信息，请参阅 排序的合理性。）

ID 序列中的空缺是正常的（例如，如果您创建了两个新修订，删除了第一个，然后应用了第二个），并且只要修订未应用，就可以手动更改 ID。

审查旅程

为了总结修订状态，请运行 jrny review。如果您不在项目目录中，需要指定配置文件位置，并且您需要指定环境文件路径或直接提供数据库URL，例如

# From within project directory & default filenames
$ jrny review

# From outside the project directory *or* with a custom config filename.
#
# This will look for an environment file named `jrny-env.toml` in
# the same directory as the custom config file.
$ jrny review -c path/to/my-jrny-config.toml

# Same as above except can specify custom environment file with different name
# or in a different directory than the config file.
$ jrny review -c path/to/my-jrny-config.toml -e path/to/my-jrny-env.toml

# Specifying database URL within project directory & default config filename.
# Can be used in conjunction with custom config and/or environment file paths.
#
# If there is a default environment file in the current directory, the URL option
# will take precedence over the URL supplied by the environment file.
$ jrny review -d 'postgresql://user:password@host:5432/dbname'

这将列出所有有序修订，每个修订都包含创建时间和应用时间（如果应用到指定数据库）。

$ jrny review

The journey thus far:

  [1] my-first-revision
    Created on 30-Mar-2023 09:10:22
    Applied on 30-Mar-2023 09:11:06

  [2] another-revision
    Created on 30-Mar-2023 09:10:32
    Applied on 30-Mar-2023 09:11:06

  [3] YET-another-revision
    Created on 30-Mar-2023 09:27:58

此外，jrny 在审查期间执行多项检查以确保...

• 已应用修订的文件在应用后未被更改
• 已应用修订的文件未被删除
• 挂起修订未插入到应用修订之前
• 序列中的所有修订（挂起和已应用）具有唯一的ID

The journey thus far:

  [1] revision-that-gets-changed
    Created on 30-Mar-2023 09:31:05
    Applied on 30-Mar-2023 10:17:33
    Errors:
      - File has changed after being applied

  [2] revision-that-gets-removed
    Created on 30-Mar-2023 09:57:56
    Applied on 30-Mar-2023 10:17:33
    Errors:
      - File could not be found

  [3] a-revision-added-in-between
    Created on 30-Mar-2023 10:18:58
    Errors:
      - Later revisions have already been applied

  [4] some-revision-that-is-fine
    Created on 30-Mar-2023 09:58:19
    Applied on 30-Mar-2023 10:17:33

  [5] a-revision-that-was-fine
    Created on 30-Mar-2023 10:17:24
    Applied on 30-Mar-2023 10:17:33
    Errors:
      - Revision has a duplicate id

  [5] revision-with-duplicate-id
    Created on 30-Mar-2023 10:19:57
    Errors:
      - Revision has a duplicate id

The journey has problems:
  - 1 revision has been changed after being applied
  - 2 revisions have duplicate ids
  - 1 revision file could not be found
  - 1 pending revision has been inserted before revisions already applied

这些检查也不一定是互斥的，也就是说，单个修订可能具有多个错误，例如，在应用后已被更改并且具有重复的ID，如果序列也被更改。

注意：即使添加（或删除）空白或注释，审查也会失败；目前还没有尝试在生成用于确定文件是否在应用后被更改的校验和之前清除这些内容。

开始旅程吧！

要应用所有挂起修订，请运行 jrny embark。

与 jrny review 类似，应用修订会在当前目录中查找默认配置和环境文件，但这两者都可以被覆盖，并且可以直接提供数据库URL。

在应用任何挂起修订之前，将审查修订，如果文件已更改，不再存在于磁盘上等，则 jrny 将发出错误并退出，不应用任何新修订。

否则，jrny 将简单地列出已应用的修订名称...

$ jrny embark

Applying 1 revision(s)

  003.1680182878.YET-another-revision.sql

...或一条指示未找到挂起修订的消息。

$ jrny embark

No revisions to apply

此外，您可以使用 --through 或 -t 仅应用到指定ID的挂起修订。

例如，给定以下审查

$ jrny review

The journey thus far:

  [1] my-first-revision
    Created on 30-Mar-2023 09:10:22
    Applied on 30-Mar-2023 09:11:06

  [2] another-revision
    Created on 30-Mar-2023 09:10:32

  [3] YET-another-revision
    Created on 30-Mar-2023 09:27:58

  [4] shocker-a-revision
    Created on 19-Apr-2023 15:42:29

  [5] surprise-another-revision
    Created on 19-Apr-2023 15:42:36

如果您只想运行到 YET-another-revision，只需传递ID 3

$ jrny embark --through 3

Applying 2 revision(s), skipping 2

  002.1680181832.another-revision.sql
  008.1681952321.YET another revision.sql

use std::env;
use std::path::PathBuf;

use jrny::context as ctx;


fn main() {
    // Initialize a new `jrny` setup in the `./jrny-test` subdirectory.
    //
    // Note: In addition to creating the necessary revisions directory, this *also*
    // creates the `jrny.toml`, etc files that, when using `jrny` as a library,
    // are entirely unnecessary.
    //
    // See: https://github.com/kevlarr/jrny/issues/35
    jrny::begin(&PathBuf::from("jrny-test")).unwrap();

    // The rest of the commands will need to know the project configuration
    // and potentially other environment details as well.
    let cfg = ctx::Config {
        revisions: ctx::RevisionsSettings {
            directory: PathBuf::from("jrny-test/revisions"),
        },
        table: ctx::TableSettings {
            schema: "public".to_owned(),
            name: "jrny_revision".to_owned(),
        },
    };
    let env = ctx::Environment::from_database_url(&env::var("DATABASE_URL").unwrap());

    // Create a new empty migration
    jrny::plan(&cfg, "my first migration", None).unwrap();

    // Create another migration with some contents
    jrny::plan(&cfg, "a more useful migration", Some("
        create table my_cool_table (
            id bigint
                primary key
                generated always as identity
        )
    ")).unwrap();

    // Review the migrations
    jrny::review(&cfg, &env).unwrap();

    // Run the migrations
    jrny::embark(&cfg, &env).unwrap();
}