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:
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_Handles all work related to database table partitioning
Handles all work related to database table partitioning
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!`.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |