Liking cljdoc? Tell your friends :D

puppetlabs.puppetdb.scf.migrate

Schema migrations

The initialize-schema function can be used to prepare the database, applying all the pending migrations to the database, in ascending order of schema version. Pending is defined as having a schema version greater than the current version in the database.

A migration is specified by defining a function of arity 0 and adding it to the migrations map, along with its schema version. To apply the migration, the migration function will be invoked, and the schema version and current time will be recorded in the schema_migrations table.

A migration function can return a map with ::vacuum-analyze to indicate what tables need to be analyzed post-migration.

NOTE: in order to support bug-fix schema changes to older branches without breaking the ability to upgrade, it is possible to define a sequence of migrations with non-sequential integers. e.g., if the 1.0.x branch contains migrations 1-5, and the 2.0.x branch contains schema migrations 1-10, and then a bugfix schema change (such as creating or adding an index) is identified, this migration can be defined as #11 in both branches. Code in the 1.0.x branch should happily apply #11 even though it does not have a definition for 6-10. Then when a 1.0.x user upgrades to 2.0.x, migrations 6-10 will be applied, and 11 will be skipped because it's already been run. Because of this, it is crucial to be extremely careful about numbering new migrations if they are going into multiple branches. It's also crucial to be absolutely certain that the schema change in question is compatible with both branches and that the migrations missing from the earlier branch can reasonably and safely be applied after the bugfix migration, because that is what will happen for upgrading users.

In short, here are some guidelines re: applying schema changes to multiple branches:

  1. If at all possible, avoid it.
  2. Seriously, are you sure you need to do this? :)
  3. OK, if you really must do it, make sure that the schema change in question is as independent as humanly possible. For example, things like creating or dropping an index on a table should be fairly self-contained. You should think long and hard about any change more complex than that.
  4. Determine what the latest version of the schema is in each of the two branches.
  5. Examine every migration that exists in the newer branch but not the older branch, and make sure that your new schema change will not conflict with any of those migrations. Your change must be able to execute successfully regardless of whether it is applied BEFORE all of those migrations or AFTER them.
  6. If you're certain you've met the conditions described above, choose the next available integer from the newer branch and add your migration to both branches using this integer. This will result in a gap between the integers in the migrations array in the old branch, but that is not a problem.

TODO: consider using multimethods for migration funcs

Schema migrations

 The `initialize-schema` function can be used to prepare the
database, applying all the pending migrations to the database, in
ascending order of schema version. Pending is defined as having a
schema version greater than the current version in the database.

 A migration is specified by defining a function of arity 0 and adding it to
 the `migrations` map, along with its schema version. To apply the migration,
 the migration function will be invoked, and the schema version and current
 time will be recorded in the schema_migrations table.

 A migration function can return a map with ::vacuum-analyze to indicate what tables
 need to be analyzed post-migration.

 NOTE: in order to support bug-fix schema changes to older branches without
 breaking the ability to upgrade, it is possible to define a sequence of
 migrations with non-sequential integers.  e.g., if the 1.0.x branch
 contains migrations 1-5, and the 2.0.x branch contains schema migrations
 1-10, and then a bugfix schema change (such as creating or adding an index)
 is identified, this migration can be defined as #11 in both branches.  Code
 in the 1.0.x branch should happily apply #11 even though it does not have
 a definition for 6-10.  Then when a 1.0.x user upgrades to 2.0.x, migrations
 6-10 will be applied, and 11 will be skipped because it's already been run.
 Because of this, it is crucial to be extremely careful about numbering new
 migrations if they are going into multiple branches.  It's also crucial to
 be absolutely certain that the schema change in question is compatible
 with both branches and that the migrations missing from the earlier branch
 can reasonably and safely be applied *after* the bugfix migration, because
 that is what will happen for upgrading users.

 In short, here are some guidelines re: applying schema changes to multiple
 branches:

 1. If at all possible, avoid it.
 2. Seriously, are you sure you need to do this? :)
 3. OK, if you really must do it, make sure that the schema change in question
    is as independent as humanly possible.  For example, things like creating
    or dropping an index on a table should be fairly self-contained.  You should
    think long and hard about any change more complex than that.
 4. Determine what the latest version of the schema is in each of the two branches.
 5. Examine every migration that exists in the newer branch but not the older
    branch, and make sure that your new schema change will not conflict with
    *any* of those migrations.  Your change must be able to execute successfully
    regardless of whether it is applied BEFORE all of those migrations or AFTER
    them.
 6. If you're certain you've met the conditions described above, choose the next
    available integer from the *newer* branch and add your migration to both
    branches using this integer.  This will result in a gap between the integers
    in the migrations array in the old branch, but that is not a problem.

 _TODO: consider using multimethods for migration funcs_
raw docstring

puppetlabs.puppetdb.scf.storage

Catalog persistence

Catalogs are persisted in a relational database. Roughly speaking, the schema looks like this:

  • resource_parameters are associated 0 to N catalog_resources (they are deduped across catalogs). It's possible for a resource_param to exist in the database, yet not be associated with a catalog. This is done as a performance optimization.

  • edges are associated with a single catalog

  • catalogs are associated with a single certname

  • facts are associated with a single certname

The standard set of operations on information in the database will likely result in dangling resources and catalogs; to clean these up, it's important to run garbage-collect!.

Catalog persistence

Catalogs are persisted in a relational database. Roughly speaking,
the schema looks like this:

* resource_parameters are associated 0 to N catalog_resources (they are
deduped across catalogs). It's possible for a resource_param to exist in the
database, yet not be associated with a catalog. This is done as a
performance optimization.

* edges are associated with a single catalog

* catalogs are associated with a single certname

* facts are associated with a single certname

 The standard set of operations on information in the database will
 likely result in dangling resources and catalogs; to clean these
 up, it's important to run `garbage-collect!`.
raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
Move to previous article
Move to next article
Ctrl+/Jump to the search field
× close