Rebuild the report database

Rebuild the report database. This is necessary when the orderly database schema changes, and you will be prompted to run this function after upgrading orderly in that case.

Usage

orderly_rebuild(
  root = NULL,
  locate = TRUE,
  verbose = TRUE,
  if_schema_changed = FALSE
)

Arguments

root

The path to an orderly root directory, or NULL (the default) to search for one from the current working directory if locate is TRUE.

locate

Logical, indicating if the configuration should be searched for. If TRUE and config is not given, then orderly looks in the working directory and up through its parents until it finds an orderly_config.yml file.

verbose

Logical, indicating if information about the rebuild should be printed as it runs

if_schema_changed

Logical, indicating if the rebuild should take place only if the schema has changed. This is designed to be safe to use in (say) deployment scripts because it will be fast enough to call regularly.

Value

No return value, this function is called only for its side effects

Details

The report database (orderly's "destination" database) is essentially an index over all the metadata associated with reports. It is used by orderly itself, and can be used by applications that extend orderly (e.g., OrderlyWeb. All the data in this database can be rebuilt from files stored with the committed (archive) orderly reports, using the orderly_rebuild function.

Examples

path <- orderly1::orderly_example("minimal")
id <- orderly1::orderly_run("example", root = path)
#> [ name       ]  example
#> [ id         ]  20250731-134550-60270c49
#> [ start      ]  2025-07-31 13:45:50.377876
#> [ data       ]  source => dat: 20 x 2
#> 
#> > png("mygraph.png")
#> 
#> > par(mar = c(15, 4, 0.5, 0.5))
#> 
#> > barplot(setNames(dat$number, dat$name), las = 2)
#> 
#> > dev.off()
#> agg_record_653975181 
#>                    2 
#> [ end        ]  2025-07-31 13:45:50.39643
#> [ elapsed    ]  Ran report in 0.01855493 secs
#> [ artefact   ]  mygraph.png: a7b94ccda59d3cdc6de2c3b088822f33
orderly1::orderly_commit(id, root = path)
#> [ commit     ]  example/20250731-134550-60270c49
#> [ copy       ]
#> [ import     ]  example:20250731-134550-60270c49
#> [ success    ]  :)
#> [1] "/tmp/Rtmp82yBdj/file1cbf5e1e3db6/archive/example/20250731-134550-60270c49"

con <- orderly1::orderly_db("destination", root = path)
DBI::dbReadTable(con, "report_version")
#>                         id  report                       date displayname
#> 1 20250731-134550-60270c49 example 2025-07-31 13:45:50.410308        <NA>
#>   description connection published    elapsed git_sha git_branch git_clean
#> 1        <NA>          0         0 0.01855493    <NA>       <NA>        NA
DBI::dbDisconnect(con)

# The database can be removed and will be rebuilt if requested
# (this is only a good idea if you do not extend the database with
# your own fields - only the fields that orderly looks after can
# be recovered!)
file.remove(file.path(path, "orderly.sqlite"))
#> [1] TRUE
orderly1::orderly_rebuild(path)
#> [ backup     ]  orderly.sqlite => backup/db/orderly.sqlite.20250731-134550
#> [ rebuild    ]  db
#> 20250731-134550-60270c49 (example)
file.exists(file.path(path, "orderly.sqlite"))
#> [1] TRUE
con <- orderly1::orderly_db("destination", root = path)
DBI::dbReadTable(con, "report_version")
#>                         id  report                       date displayname
#> 1 20250731-134550-60270c49 example 2025-07-31 13:45:50.410308        <NA>
#>   description connection published    elapsed git_sha git_branch git_clean
#> 1        <NA>          0         0 0.01855493    <NA>       <NA>        NA
DBI::dbDisconnect(con)

# It is safe to rebuild a database repeatedly, though this can be
# slow with larger databases.
orderly1::orderly_rebuild(path)
#> [ backup     ]  orderly.sqlite => backup/db/orderly.sqlite.20250731-134550
#> [ rebuild    ]  db
#> 20250731-134550-60270c49 (example)