rotate_rds {rotor}

Serialize R objects to disk (with backup)

Description

The ⁠rotate_rds*()⁠ functions are wrappers around base::saveRDS() that create a backup of the destination file (if it exists) instead of just overwriting it.

Usage

rotate_rds(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  on_change_only = FALSE
)

rotate_rds_date(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

rotate_rds_time(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

Arguments

object

R object to serialize.

file

a connection or the name of the file where the R object is saved to or read from.

ascii

a logical. If TRUE or NA, an ASCII representation is written; otherwise (default), a binary one is used. See the comments in the help for save.

version

the workspace format version to use. NULL specifies the current default version (3). The only other supported value is 2, the default from R 1.4.0 to R 3.5.0.

compress

a logical specifying whether saving to a named file is to use "gzip" compression, or one of "gzip", "bzip2" or "xz" to indicate the type of compression to be used. Ignored if file is a connection.

refhook

a hook function for handling reference objects.

...

Arguments passed on to rotate, rotate_date, rotate_time

max_backups

maximum number of backups to keep

• an integer scalar: Maximum number of backups to keep

In addition for timestamped backups the following value are supported:

• a Date scalar: Remove all backups before this date

• a character scalar representing a Date in ISO format (e.g. "2019-12-31")

• a character scalar representing an Interval in the form "<number> <interval>" (see below for more info)

size

scalar integer, character or Inf. Backup/rotate only if file is larger than this size. Integers are interpreted as bytes. You can pass character vectors that contain a file size suffix like ⁠1k⁠ (kilobytes), ⁠3M⁠ (megabytes), ⁠4G⁠ (gigabytes), ⁠5T⁠ (terabytes). Instead of these short forms you can also be explicit and use the IEC suffixes KiB, MiB, GiB, TiB. In Both cases 1 kilobyte is 1024 bytes, 1 megabyte is 1024 kilobytes, etc... .

(if age and size are provided, both criteria must be TRUE to trigger rotation)

dir

character scalar. The directory in which the backups of file are stored (defaults to dirname(file))

compression

Whether or not backups should be compressed

• FALSE for uncompressed backups,

• TRUE for zip compression; uses zip()

• a scalar integer between 1 and 9 to specify a compression level (requires the zip package, see its documentation for details)

• the character scalars "utils::zip()" or "zip::zipr" to force a specific zip command

dry_run

logical scalar. If TRUE no changes are applied to the file system (no files are created or deleted)

verbose

logical scalar. If TRUE additional informative messages are printed

create_file

logical scalar. If TRUE create an empty file in place of file after rotating.

format

a scalar character that can be a subset of of valid strftime() formatting strings. The default setting is "%Y-%m-%d--%H-%M-%S".

• You can use an arbitrary number of dashes anywhere in the format, so "%Y-%m-%d--%H-%M-%S" and "%Y%m%d%H%M%S" are both legal.

• T and ⁠_⁠ can also be used as separators. For example, the following datetime formats are also possible: ⁠%Y-%m-%d_%H-%M-%S⁠ (Python logging default), ⁠%Y%m%dT%H%M%S⁠ (ISO 8601)

• All datetime components except ⁠%Y⁠ are optional. If you leave out part of the timestamp, the first point in time in the period is assumed. For example (assuming the current year is 2019) ⁠%Y⁠ is identical to 2019-01-01--00-00-00.

• The timestamps must be lexically sortable, so "%Y-%m-%d" is legal, "%m-%d-%Y" and ⁠%Y-%d⁠ are not.

now

The current Date or time (POSIXct) as a scalar. You can pass a custom value here to to override the real system time. As a convenience you can also pass in character strings that follow the guidelines outlined above for format, but please note that these differ from the formats understood by as.POSIXct() or as.Date().

overwrite

logical scalar. If TRUE overwrite backups if a backup of the same name (usually due to timestamp collision) exists.

on_change_only

logical scalaror a list. Rotate only if object is different from the object saved in file. If a list, arguments that will be passed on to data.table::all.equal (only when both obects are data.tables)

age

minimum age after which to backup/rotate a file; can be

• a character scalar representing an Interval in the form "<number> <interval>" (e.g. "2 months", see Intervals section below).

• a Date or a character scalar representing a Date for a fixed point in time after which to backup/rotate. See format for which Date/Datetime formats are supported by rotor.

(if age and size are provided, both criteria must be TRUE to trigger rotation)

Value

the path to file (invisibly)

Note

The default value for age is different for rotate_rds_date() (-1) than for rotate_date() (1) to make it a bit safer. This means if you execute rotate_date() twice on the same file on a given day it will silently not rotate the file, while rotate_rds_date() will throw an error.

Examples

dest <- tempfile()
rotate_rds(iris, dest)
rotate_rds(iris, dest)
rotate_rds(iris, dest)

list_backups(dest)

# cleanup
unlink(list_backups(dest))
unlink(dest)