1226 lines
41 KiB
Rust
1226 lines
41 KiB
Rust
// Copyright 2018 Mozilla
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
||
// this file except in compliance with the License. You may obtain a copy of the
|
||
// License at http://www.apache.org/licenses/LICENSE-2.0
|
||
// Unless required by applicable law or agreed to in writing, software distributed
|
||
// under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
|
||
// CONDITIONS OF ANY KIND, either express or implied. See the License for the
|
||
// specific language governing permissions and limitations under the License.
|
||
|
||
#[macro_use]
|
||
extern crate lazy_static;
|
||
|
||
#[macro_use]
|
||
extern crate mentat;
|
||
|
||
use mentat::vocabulary;
|
||
|
||
use mentat::vocabulary::{
|
||
Definition, SimpleVocabularySource, Version, VersionedStore, Vocabulary, VocabularyCheck,
|
||
VocabularyOutcome, VocabularySource, VocabularyStatus,
|
||
};
|
||
|
||
use mentat::query::IntoResult;
|
||
|
||
use mentat_core::HasSchema;
|
||
|
||
use core_traits::attribute::Unique;
|
||
|
||
// To check our working.
|
||
use mentat_db::AttributeValidation;
|
||
|
||
use mentat::{
|
||
Binding, Conn, InProgress, Keyword, KnownEntid, QueryInputs, Queryable, RelResult, Store,
|
||
TypedValue, ValueType,
|
||
};
|
||
|
||
use mentat::entity_builder::{BuildTerms, TermBuilder};
|
||
|
||
use mentat::errors::MentatError;
|
||
|
||
lazy_static! {
|
||
static ref FOO_NAME: Keyword = kw!(:foo/name);
|
||
static ref FOO_MOMENT: Keyword = kw!(:foo/moment);
|
||
static ref FOO_VOCAB: vocabulary::Definition = {
|
||
vocabulary::Definition {
|
||
name: kw!(:org.mozilla/foo),
|
||
version: 1,
|
||
attributes: vec![
|
||
(
|
||
FOO_NAME.clone(),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.build(),
|
||
),
|
||
(
|
||
FOO_MOMENT.clone(),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Instant)
|
||
.multival(false)
|
||
.index(true)
|
||
.build(),
|
||
),
|
||
],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
}
|
||
};
|
||
}
|
||
|
||
// Do some work with the appropriate level of paranoia for a shared system.
|
||
fn be_paranoid(
|
||
conn: &mut Conn,
|
||
sqlite: &mut rusqlite::Connection,
|
||
name: TypedValue,
|
||
moment: TypedValue,
|
||
) {
|
||
let mut in_progress = conn.begin_transaction(sqlite).expect("begun successfully");
|
||
assert!(in_progress.verify_core_schema().is_ok());
|
||
assert!(in_progress.ensure_vocabulary(&FOO_VOCAB).is_ok());
|
||
|
||
let a_moment = in_progress
|
||
.attribute_for_ident(&FOO_MOMENT)
|
||
.expect("exists")
|
||
.1;
|
||
let a_name = in_progress
|
||
.attribute_for_ident(&FOO_NAME)
|
||
.expect("exists")
|
||
.1;
|
||
|
||
let builder = in_progress.builder();
|
||
let mut entity = builder.describe_tempid("s");
|
||
entity.add(a_name, name).expect("added");
|
||
entity.add(a_moment, moment).expect("added");
|
||
assert!(entity.commit().is_ok()); // Discard the TxReport.
|
||
}
|
||
|
||
#[test]
|
||
fn test_real_world() {
|
||
let mut sqlite = mentat_db::db::new_connection("").unwrap();
|
||
let mut conn = Conn::connect(&mut sqlite).unwrap();
|
||
|
||
let alice: TypedValue = TypedValue::typed_string("Alice");
|
||
let barbara: TypedValue = TypedValue::typed_string("Barbara");
|
||
let now: TypedValue = TypedValue::current_instant();
|
||
|
||
be_paranoid(&mut conn, &mut sqlite, alice.clone(), now.clone());
|
||
be_paranoid(&mut conn, &mut sqlite, barbara.clone(), now.clone());
|
||
|
||
let results = conn
|
||
.q_once(
|
||
&sqlite,
|
||
r#"[:find ?name ?when
|
||
:order (asc ?name)
|
||
:where [?x :foo/name ?name]
|
||
[?x :foo/moment ?when]
|
||
]"#,
|
||
None,
|
||
)
|
||
.into_rel_result()
|
||
.expect("query succeeded");
|
||
assert_eq!(
|
||
results,
|
||
vec![vec![alice, now.clone()], vec![barbara, now]].into()
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn test_default_attributebuilder_complains() {
|
||
// ::new is helpful. ::default is not.
|
||
assert!(vocabulary::AttributeBuilder::default()
|
||
.value_type(ValueType::String)
|
||
.multival(true)
|
||
.fulltext(true)
|
||
.build()
|
||
.validate(|| "Foo".to_string())
|
||
.is_err());
|
||
|
||
assert!(vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(true)
|
||
.fulltext(true)
|
||
.build()
|
||
.validate(|| "Foo".to_string())
|
||
.is_ok());
|
||
}
|
||
|
||
#[test]
|
||
fn test_add_vocab() {
|
||
let thing2 = vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Instant)
|
||
.multival(false)
|
||
.index(true)
|
||
.build();
|
||
let thing3 = vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(true)
|
||
.fulltext(true)
|
||
.build();
|
||
let thing2_only = vec![(kw!(:foo/bar), thing2.clone())];
|
||
let thing3_only = vec![(kw!(:foo/baz), thing3.clone())];
|
||
let thing2_and_thing3 = vec![
|
||
(kw!(:foo/bar), thing2.clone()),
|
||
(kw!(:foo/baz), thing3.clone()),
|
||
];
|
||
|
||
let thing1_v1_a = vocabulary::Definition::new(kw!(:org.mozilla/foo), 1, thing2_only);
|
||
let thing1_v1_b = vocabulary::Definition::new(kw!(:org.mozilla/foo), 1, thing2_and_thing3);
|
||
|
||
let mut sqlite = mentat_db::db::new_connection("").unwrap();
|
||
let mut conn = Conn::connect(&mut sqlite).unwrap();
|
||
|
||
let thing1_version_query = r#"[:find [?version ?aa]
|
||
:where
|
||
[:org.mozilla/foo :db.schema/version ?version]
|
||
[:org.mozilla/foo :db.schema/attribute ?a]
|
||
[?a :db/ident ?aa]]"#;
|
||
let thing1_attributes_query = r#"[:find [?aa ...]
|
||
:where
|
||
[:org.mozilla/foo :db.schema/attribute ?a]
|
||
[?a :db/ident ?aa]]"#;
|
||
|
||
// Scoped borrow of `conn`.
|
||
{
|
||
let mut in_progress = conn
|
||
.begin_transaction(&mut sqlite)
|
||
.expect("begun successfully");
|
||
|
||
assert!(in_progress.verify_core_schema().is_ok());
|
||
assert_eq!(
|
||
VocabularyCheck::NotPresent,
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_a)
|
||
.expect("check completed")
|
||
);
|
||
assert_eq!(
|
||
VocabularyCheck::NotPresent,
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_b)
|
||
.expect("check completed")
|
||
);
|
||
|
||
// If we install v1.a, then it will succeed.
|
||
assert_eq!(
|
||
VocabularyOutcome::Installed,
|
||
in_progress
|
||
.ensure_vocabulary(&thing1_v1_a)
|
||
.expect("ensure succeeded")
|
||
);
|
||
|
||
// Now we can query to get the vocab.
|
||
let ver_attr = in_progress
|
||
.q_once(thing1_version_query, None)
|
||
.into_tuple_result()
|
||
.expect("query returns")
|
||
.expect("a result");
|
||
assert_eq!(ver_attr[0], TypedValue::Long(1).into());
|
||
assert_eq!(
|
||
ver_attr[1],
|
||
TypedValue::typed_ns_keyword("foo", "bar").into()
|
||
);
|
||
|
||
// If we commit, it'll stick around.
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
// It's still there.
|
||
let ver_attr = conn
|
||
.q_once(&sqlite, thing1_version_query, None)
|
||
.into_tuple_result()
|
||
.expect("query returns")
|
||
.expect("a result");
|
||
assert_eq!(ver_attr[0], TypedValue::Long(1).into());
|
||
assert_eq!(
|
||
ver_attr[1],
|
||
TypedValue::typed_ns_keyword("foo", "bar").into()
|
||
);
|
||
|
||
// Scoped borrow of `conn`.
|
||
{
|
||
let mut in_progress = conn
|
||
.begin_transaction(&mut sqlite)
|
||
.expect("begun successfully");
|
||
|
||
// Subsequently ensuring v1.a again will succeed with no work done.
|
||
assert_eq!(
|
||
VocabularyCheck::Present,
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_a)
|
||
.expect("check completed")
|
||
);
|
||
|
||
// Checking for v1.b will say that we have work to do.
|
||
assert_eq!(
|
||
VocabularyCheck::PresentButMissingAttributes {
|
||
attributes: vec![&thing3_only[0]],
|
||
},
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_b)
|
||
.expect("check completed")
|
||
);
|
||
|
||
// Ensuring v1.b will succeed.
|
||
assert_eq!(
|
||
VocabularyOutcome::InstalledMissingAttributes,
|
||
in_progress
|
||
.ensure_vocabulary(&thing1_v1_b)
|
||
.expect("ensure succeeded")
|
||
);
|
||
|
||
// Checking v1.a or v1.b again will still succeed with no work done.
|
||
assert_eq!(
|
||
VocabularyCheck::Present,
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_a)
|
||
.expect("check completed")
|
||
);
|
||
assert_eq!(
|
||
VocabularyCheck::Present,
|
||
in_progress
|
||
.check_vocabulary(&thing1_v1_b)
|
||
.expect("check completed")
|
||
);
|
||
|
||
// Ensuring again does nothing.
|
||
assert_eq!(
|
||
VocabularyOutcome::Existed,
|
||
in_progress
|
||
.ensure_vocabulary(&thing1_v1_b)
|
||
.expect("ensure succeeded")
|
||
);
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
// We have both attributes.
|
||
let actual_attributes = conn
|
||
.q_once(&sqlite, thing1_attributes_query, None)
|
||
.into_coll_result()
|
||
.expect("query returns");
|
||
assert_eq!(
|
||
actual_attributes,
|
||
vec![
|
||
TypedValue::typed_ns_keyword("foo", "bar").into(),
|
||
TypedValue::typed_ns_keyword("foo", "baz").into(),
|
||
]
|
||
);
|
||
|
||
// Now let's modify our vocabulary without bumping the version. This is invalid and will result
|
||
// in an error.
|
||
let malformed_baz = vocabulary::AttributeBuilder::default()
|
||
.value_type(ValueType::Instant)
|
||
.multival(true)
|
||
.build();
|
||
let bar_and_malformed_baz = vec![
|
||
(kw!(:foo/bar), thing2),
|
||
(kw!(:foo/baz), malformed_baz.clone()),
|
||
];
|
||
|
||
let foo_v1_malformed =
|
||
vocabulary::Definition::new(kw!(:org.mozilla/foo), 1, bar_and_malformed_baz);
|
||
|
||
// Scoped borrow of `conn`.
|
||
{
|
||
let mut in_progress = conn
|
||
.begin_transaction(&mut sqlite)
|
||
.expect("begun successfully");
|
||
match in_progress
|
||
.ensure_vocabulary(&foo_v1_malformed)
|
||
.expect_err("expected vocabulary to fail")
|
||
{
|
||
MentatError::ConflictingAttributeDefinitions(vocab, version, attr, theirs, ours) => {
|
||
assert_eq!(vocab.as_str(), ":org.mozilla/foo");
|
||
assert_eq!(attr.as_str(), ":foo/baz");
|
||
assert_eq!(version, 1);
|
||
assert_eq!(&theirs, &thing3);
|
||
assert_eq!(&ours, &malformed_baz);
|
||
}
|
||
_ => panic!(),
|
||
}
|
||
}
|
||
|
||
// Some alterations -- cardinality/one to cardinality/many, unique to weaker unique or
|
||
// no unique, unindexed to indexed -- can be applied automatically, so long as you
|
||
// bump the version number.
|
||
|
||
let multival_bar = vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Instant)
|
||
.multival(true)
|
||
.index(true)
|
||
.build();
|
||
let multival_bar_and_baz = vec![(kw!(:foo/bar), multival_bar), (kw!(:foo/baz), thing3)];
|
||
|
||
let altered_vocabulary =
|
||
vocabulary::Definition::new(kw!(:org.mozilla/foo), 2, multival_bar_and_baz);
|
||
|
||
// foo/bar starts single-valued.
|
||
assert_eq!(
|
||
false,
|
||
conn.current_schema()
|
||
.attribute_for_ident(&kw!(:foo/bar))
|
||
.expect("attribute")
|
||
.0
|
||
.multival
|
||
);
|
||
|
||
// Scoped borrow of `conn`.
|
||
{
|
||
let mut in_progress = conn
|
||
.begin_transaction(&mut sqlite)
|
||
.expect("begun successfully");
|
||
assert_eq!(
|
||
in_progress
|
||
.ensure_vocabulary(&altered_vocabulary)
|
||
.expect("success"),
|
||
VocabularyOutcome::Upgraded
|
||
);
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
// Now it's multi-valued.
|
||
assert_eq!(
|
||
true,
|
||
conn.current_schema()
|
||
.attribute_for_ident(&kw!(:foo/bar))
|
||
.expect("attribute")
|
||
.0
|
||
.multival
|
||
);
|
||
}
|
||
|
||
/// A helper to turn rows from `[:find ?e ?a :where [?e ?a ?v]]` into a tuple.
|
||
fn ea(row: Vec<Binding>) -> (KnownEntid, KnownEntid) {
|
||
let mut row = row.into_iter();
|
||
match (row.next(), row.next()) {
|
||
(Some(Binding::Scalar(TypedValue::Ref(e))), Some(Binding::Scalar(TypedValue::Ref(a)))) => {
|
||
(KnownEntid(e), KnownEntid(a))
|
||
}
|
||
_ => panic!("Incorrect query shape for 'ea' helper."),
|
||
}
|
||
}
|
||
|
||
/// A helper to turn rows from `[:find ?a ?v :where [?e ?a ?v]]` into a tuple.
|
||
/// Panics if any of the values are maps or vecs.
|
||
fn av(row: Vec<Binding>) -> (KnownEntid, TypedValue) {
|
||
let mut row = row.into_iter();
|
||
match (row.next(), row.next()) {
|
||
(Some(Binding::Scalar(TypedValue::Ref(a))), Some(v)) => {
|
||
(KnownEntid(a), v.into_scalar().unwrap())
|
||
}
|
||
_ => panic!("Incorrect query shape for 'av' helper."),
|
||
}
|
||
}
|
||
|
||
/// A helper to turn rows from `[:find ?e ?v :where [?e ?a ?v]]` into a tuple.
|
||
/// Panics if any of the values are maps or vecs.
|
||
fn ev(row: Vec<Binding>) -> (KnownEntid, TypedValue) {
|
||
// This happens to be the same as `av`.
|
||
av(row)
|
||
}
|
||
|
||
type Inches = i64;
|
||
type Centimeters = i64;
|
||
|
||
/// ```
|
||
/// assert_eq!(inches_to_cm(100), 254);
|
||
/// ```
|
||
fn inches_to_cm(inches: Inches) -> Centimeters {
|
||
(inches as f64 * 2.54f64) as Centimeters
|
||
}
|
||
|
||
fn height_of_person(in_progress: &InProgress<'_, '_>, name: &str) -> Option<i64> {
|
||
let h = in_progress
|
||
.q_once(
|
||
r#"[:find ?h .
|
||
:in ?name
|
||
:where [?p :person/name ?name]
|
||
[?p :person/height ?h]]"#,
|
||
QueryInputs::with_value_sequence(vec![(var!(?name), TypedValue::typed_string(name))]),
|
||
)
|
||
.into_scalar_result()
|
||
.expect("result");
|
||
match h {
|
||
Some(Binding::Scalar(TypedValue::Long(v))) => Some(v),
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
// This is a real-world-style test that evolves a schema with data changes.
|
||
// We start with a basic vocabulary in three parts:
|
||
//
|
||
// Part 1 describes foods by name.
|
||
// Part 2 describes movies by title.
|
||
// Part 3 describes people: their names and heights, and their likes.
|
||
//
|
||
// We simulate four common migrations:
|
||
//
|
||
// 1. We made a trivial modeling error: movie names should not be unique.
|
||
// We simply fix this -- removing a uniqueness constraint cannot fail.
|
||
//
|
||
// 2. We need to normalize some non-unique data: we recorded heights in inches when they should be
|
||
// in centimeters. We fix this with a migration function and a version bump on the people schema.
|
||
//
|
||
// 3. We need to normalize some data: food names should all be lowercase, and they should be unique
|
||
// so that we can more easily refer to them during writes.
|
||
//
|
||
// That combination of changes can fail in either order if there are currently foods whose names
|
||
// differ only by case.
|
||
//
|
||
// (We might know that it can't fail thanks to application restrictions, in which case we can
|
||
// treat this as we did the height alteration.)
|
||
//
|
||
// In order for this migration to succeed, we need to merge duplicates, then alter the schema.
|
||
//
|
||
// 4. We made a more significant modeling error: we used 'like' to identify both movies and foods,
|
||
// and we have decided that food preferences and movie preferences should be different attributes.
|
||
// We wish to split these up and deprecate the old attribute. In order to do so we need to retract
|
||
// all of the datoms that use the old attribute, transact new attributes _in both movies and foods_,
|
||
// then re-assert the data.
|
||
//
|
||
// This one's a little contrived, because it can also be solved without cross-vocabulary work,
|
||
// but it's close enough to reality to be illustrative.
|
||
#[test]
|
||
fn test_upgrade_with_functions() {
|
||
let mut store = Store::open("").expect("open");
|
||
|
||
let food_v1 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/food),
|
||
version: 1,
|
||
attributes: vec![(
|
||
kw!(:food/name),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.build(),
|
||
)],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
let movies_v1 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/movies),
|
||
version: 1,
|
||
attributes: vec![
|
||
(
|
||
kw!(:movie/year),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Long) // No need for Instant here.
|
||
.multival(false)
|
||
.build(),
|
||
),
|
||
(
|
||
kw!(:movie/title),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.index(true)
|
||
.build(),
|
||
),
|
||
],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
let people_v1 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/people),
|
||
version: 1,
|
||
attributes: vec![
|
||
(
|
||
kw!(:person/name),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.index(true)
|
||
.build(),
|
||
),
|
||
(
|
||
kw!(:person/height),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Long)
|
||
.multival(false)
|
||
.build(),
|
||
),
|
||
(
|
||
kw!(:person/likes),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Ref)
|
||
.multival(true)
|
||
.build(),
|
||
),
|
||
],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
// Apply v1 of each.
|
||
let mut v1_provider =
|
||
SimpleVocabularySource::with_definitions(vec![food_v1, movies_v1, people_v1.clone()]);
|
||
|
||
// Mutable borrow of store.
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
|
||
in_progress
|
||
.ensure_vocabularies(&mut v1_provider)
|
||
.expect("success");
|
||
|
||
// Also add some data. We do this in one transaction 'cos -- thanks to the modeling errors
|
||
// we are about to fix! -- it's a little awkward to make references to entities without
|
||
// unique attributes.
|
||
in_progress
|
||
.transact(
|
||
r#"[
|
||
{:movie/title "John Wick"
|
||
:movie/year 2014
|
||
:db/id "mjw"}
|
||
{:movie/title "Terminator 2: Judgment Day"
|
||
:movie/year 1991
|
||
:db/id "mt2"}
|
||
{:movie/title "Dune"
|
||
:db/id "md"
|
||
:movie/year 1984}
|
||
{:movie/title "Upstream Color"
|
||
:movie/year 2013
|
||
:db/id "muc"}
|
||
{:movie/title "Primer"
|
||
:db/id "mp"
|
||
:movie/year 2004}
|
||
|
||
;; No year: not yet released.
|
||
{:movie/title "The Modern Ocean"
|
||
:db/id "mtmo"}
|
||
|
||
{:food/name "Carrots" :db/id "fc"}
|
||
{:food/name "Weird blue worms" :db/id "fwbw"}
|
||
{:food/name "Spice" :db/id "fS"}
|
||
{:food/name "spice" :db/id "fs"}
|
||
|
||
;; Sam likes action movies, carrots, and lowercase spice.
|
||
{:person/name "Sam"
|
||
:person/height 64
|
||
:person/likes ["mjw", "mt2", "fc", "fs"]}
|
||
|
||
;; Beth likes thoughtful and weird movies, weird blue worms, and Spice.
|
||
{:person/name "Beth"
|
||
:person/height 68
|
||
:person/likes ["muc", "mp", "md", "fwbw", "fS"]}
|
||
|
||
]"#,
|
||
)
|
||
.expect("transacted");
|
||
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
//
|
||
// Migration 1: removal of a uniqueness constraint.
|
||
//
|
||
|
||
// Crap, there are several movies named Dune. We need to de-uniqify that attribute.
|
||
let movies_v2 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/movies),
|
||
version: 2,
|
||
attributes: vec![(
|
||
kw!(:movie/title),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.non_unique()
|
||
.index(true)
|
||
.build(),
|
||
)],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
// Mutable borrow of store.
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
in_progress.ensure_vocabulary(&movies_v2).expect("success");
|
||
|
||
// We can now add another Dune movie: Denis Villeneuve's 2019 version.
|
||
// (Let's just pretend that it's been released, here in 2018!)
|
||
in_progress
|
||
.transact(
|
||
r#"[
|
||
{:movie/title "Dune"
|
||
:movie/year 2019}
|
||
]"#,
|
||
)
|
||
.expect("transact succeeded");
|
||
|
||
// And we can query both.
|
||
let years = in_progress
|
||
.q_once(
|
||
r#"[:find [?year ...]
|
||
:where [?movie :movie/title "Dune"]
|
||
[?movie :movie/year ?year]
|
||
:order (asc ?year)]"#,
|
||
None,
|
||
)
|
||
.into_coll_result()
|
||
.expect("coll");
|
||
assert_eq!(
|
||
years,
|
||
vec![
|
||
Binding::Scalar(TypedValue::Long(1984)),
|
||
Binding::Scalar(TypedValue::Long(2019))
|
||
]
|
||
);
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
//
|
||
// Migration 2: let's fix those heights!
|
||
//
|
||
|
||
fn convert_heights_to_centimeters(
|
||
ip: &mut InProgress<'_, '_>,
|
||
from: &Vocabulary,
|
||
) -> mentat::errors::Result<()> {
|
||
let mut builder = TermBuilder::new();
|
||
|
||
// We keep a redundant safety check here to avoid running twice!
|
||
if from.version < 2 {
|
||
// Find every height and multiply it by 2.54.
|
||
let person_height = ip.get_entid(&kw!(:person/height)).unwrap();
|
||
for row in ip
|
||
.q_once("[:find ?p ?h :where [?p :person/height ?h]]", None)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
{
|
||
let mut row = row.into_iter();
|
||
if let (
|
||
Some(Binding::Scalar(TypedValue::Ref(person))),
|
||
Some(Binding::Scalar(TypedValue::Long(height))),
|
||
) = (row.next(), row.next())
|
||
{
|
||
// No need to explicitly retract: cardinality-one.
|
||
builder.add(
|
||
KnownEntid(person),
|
||
person_height,
|
||
TypedValue::Long(inches_to_cm(height)),
|
||
)?;
|
||
}
|
||
}
|
||
}
|
||
|
||
if builder.is_empty() {
|
||
return Ok(());
|
||
}
|
||
|
||
ip.transact_builder(builder).and(Ok(())).map_err(|e| e)
|
||
}
|
||
|
||
fn people_v1_to_v2(
|
||
ip: &mut InProgress<'_, '_>,
|
||
from: &Vocabulary,
|
||
) -> mentat::errors::Result<()> {
|
||
convert_heights_to_centimeters(ip, from)?;
|
||
|
||
// Let's update our documentation, too.
|
||
if from.version < 2 {
|
||
ip.transact(
|
||
r#"[
|
||
[:db/add :person/height :db/doc "A person's height in centimeters."]
|
||
]"#,
|
||
)?;
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
// Note that this definition is exactly the same as v1, but the version number is different,
|
||
// and we add some functions to do cleanup.
|
||
let people_v2 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/people),
|
||
version: 2,
|
||
attributes: people_v1.attributes.clone(),
|
||
pre: Definition::no_op,
|
||
post: people_v1_to_v2,
|
||
};
|
||
|
||
// Mutable borrow of store.
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
|
||
// Before, Sam's height is 64 (inches).
|
||
assert_eq!(Some(64), height_of_person(&in_progress, "Sam"));
|
||
|
||
in_progress
|
||
.ensure_vocabulary(&people_v2)
|
||
.expect("expected success");
|
||
|
||
// Now, Sam's height is 162 (centimeters).
|
||
assert_eq!(Some(162), height_of_person(&in_progress, "Sam"));
|
||
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
//
|
||
// Migration 3: food names should be unique and lowercase.
|
||
// Unfortunately, we have "spice" and "Spice"!
|
||
//
|
||
|
||
/// This is a straightforward migration -- replace the old name with the new one.
|
||
/// This would be everything we need if we _knew_ there were no collisions (e.g., we were
|
||
/// cleaning up UUIDs).
|
||
fn lowercase_names(ip: &mut InProgress<'_, '_>) -> mentat::errors::Result<()> {
|
||
let food_name = ip.get_entid(&kw!(:food/name)).unwrap();
|
||
let mut builder = TermBuilder::new();
|
||
for row in ip
|
||
.q_once("[:find ?f ?name :where [?f :food/name ?name]]", None)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
{
|
||
let mut row = row.into_iter();
|
||
if let (
|
||
Some(Binding::Scalar(TypedValue::Ref(food))),
|
||
Some(Binding::Scalar(TypedValue::String(name))),
|
||
) = (row.next(), row.next())
|
||
{
|
||
if name.chars().any(|c| !c.is_lowercase()) {
|
||
let lowercased = name.to_lowercase();
|
||
println!(
|
||
"Need to rename {} from '{}' to '{}'",
|
||
food, name, lowercased
|
||
);
|
||
|
||
let new_name: TypedValue = lowercased.into();
|
||
builder.add(KnownEntid(food), food_name, new_name)?;
|
||
}
|
||
}
|
||
}
|
||
|
||
if builder.is_empty() {
|
||
return Ok(());
|
||
}
|
||
|
||
ip.transact_builder(builder).and(Ok(())).map_err(|e| e)
|
||
}
|
||
|
||
/// This is the function we write to dedupe. This logic is very suitable for sharing:
|
||
/// indeed, "make this attribute unique by merging entities" is something we should
|
||
/// lift out for reuse.
|
||
fn merge_foods_with_same_name(ip: &mut InProgress<'_, '_>) -> mentat::errors::Result<()> {
|
||
let mut builder = TermBuilder::new();
|
||
for row in ip
|
||
.q_once(
|
||
"[:find ?a ?b
|
||
:where [?a :food/name ?name]
|
||
[?b :food/name ?name]
|
||
[(unpermute ?a ?b)]]",
|
||
None,
|
||
)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
{
|
||
let mut row = row.into_iter();
|
||
if let (
|
||
Some(Binding::Scalar(TypedValue::Ref(left))),
|
||
Some(Binding::Scalar(TypedValue::Ref(right))),
|
||
) = (row.next(), row.next())
|
||
{
|
||
let keep = KnownEntid(left);
|
||
let replace = KnownEntid(right);
|
||
|
||
// For each use of the second entity, retract it and re-assert with the first.
|
||
// We should offer some support for doing this, 'cos this is long-winded and has
|
||
// the unexpected side-effect of also trying to retract metadata about the entity…
|
||
println!("Replacing uses of {} to {}.", replace.0, keep.0);
|
||
for (a, v) in ip
|
||
.q_once(
|
||
"[:find ?a ?v
|
||
:in ?old
|
||
:where [?old ?a ?v]]",
|
||
QueryInputs::with_value_sequence(vec![(var!(?old), replace.into())]),
|
||
)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
.map(av)
|
||
{
|
||
builder.retract(replace, a, v.clone())?;
|
||
builder.add(keep, a, v)?;
|
||
}
|
||
for (e, a) in ip
|
||
.q_once(
|
||
"[:find ?e ?a
|
||
:in ?old
|
||
:where [?e ?a ?old]]",
|
||
QueryInputs::with_value_sequence(vec![(var!(?old), replace.into())]),
|
||
)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
.map(ea)
|
||
{
|
||
builder.retract(e, a, replace)?;
|
||
builder.add(e, a, keep)?;
|
||
}
|
||
// TODO: `retractEntity` on `replace` (when we support that).
|
||
}
|
||
}
|
||
|
||
if builder.is_empty() {
|
||
return Ok(());
|
||
}
|
||
|
||
ip.transact_builder(builder).and(Ok(())).map_err(|e| e)
|
||
}
|
||
|
||
// This migration is bad: it can't impose the uniqueness constraint because we end up with
|
||
// two entities both with `:food/name "spice"`. We expect it to fail.
|
||
let food_v2_bad = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/food),
|
||
version: 2,
|
||
attributes: vec![(
|
||
kw!(:food/name),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.build(),
|
||
)],
|
||
pre: |ip, from| {
|
||
if from.version < 2 {
|
||
lowercase_names(ip) // <- no merging!
|
||
} else {
|
||
Ok(())
|
||
}
|
||
},
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
// This migration is better: once we rewrite the names, we merge the entities.
|
||
let food_v2_good = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/food),
|
||
version: 2,
|
||
attributes: vec![(
|
||
kw!(:food/name),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.build(),
|
||
)],
|
||
pre: |ip, from| {
|
||
if from.version < 2 {
|
||
lowercase_names(ip).and_then(|_| merge_foods_with_same_name(ip))
|
||
} else {
|
||
Ok(())
|
||
}
|
||
},
|
||
post: Definition::no_op,
|
||
};
|
||
|
||
// Mutable borrow of store.
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
|
||
// Yep, the bad one fails!
|
||
let _err = in_progress
|
||
.ensure_vocabulary(&food_v2_bad)
|
||
.expect_err("expected error");
|
||
}
|
||
|
||
// Before the good migration, Sam and Beth don't like any of the same foods.
|
||
assert!(store
|
||
.q_once(
|
||
r#"[:find [?food ...]
|
||
:where [?sam :person/name "Sam"]
|
||
[?beth :person/name "Beth"]
|
||
[?sam :person/likes ?f]
|
||
[?beth :person/likes ?f]
|
||
[?f :food/name ?food]]"#,
|
||
None
|
||
)
|
||
.into_coll_result()
|
||
.expect("success")
|
||
.is_empty());
|
||
|
||
// Mutable borrow of store.
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
|
||
// The good one succeeded!
|
||
in_progress
|
||
.ensure_vocabulary(&food_v2_good)
|
||
.expect("expected success");
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
// After, Sam and Beth both like "spice" — the same entity.
|
||
assert_eq!(
|
||
store
|
||
.q_once(
|
||
r#"[:find [?food ...]
|
||
:where [?sam :person/name "Sam"]
|
||
[?beth :person/name "Beth"]
|
||
[?sam :person/likes ?f]
|
||
[?beth :person/likes ?f]
|
||
[?f :food/name ?food]]"#,
|
||
None
|
||
)
|
||
.into_coll_result()
|
||
.expect("success"),
|
||
vec![TypedValue::typed_string("spice").into()]
|
||
);
|
||
|
||
//
|
||
// Migration 4: multi-definition migration.
|
||
//
|
||
// Here we apply a function to a collection of definitions, not just the definitions
|
||
// themselves.
|
||
//
|
||
// In this example we _could_ split up the work -- have :org.mozilla/movies port the movie
|
||
// likes, and :org.mozilla/food port the food likes -- but for the sake of illustration we'll
|
||
// write an enclosing function to do it.
|
||
//
|
||
// Further, the v3 versions of all vocabularies _can be applied to earlier versions_
|
||
// and our migrations will still work. This vocabulary definition set will work for empty, v1, and
|
||
// v2 of each definition.
|
||
//
|
||
let movies_v3 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/movies),
|
||
version: 3,
|
||
attributes: vec![
|
||
(
|
||
kw!(:movie/title),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.non_unique()
|
||
.index(true)
|
||
.build(),
|
||
),
|
||
// This phrasing is backward, but this is just a test.
|
||
(
|
||
kw!(:movie/likes),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Ref)
|
||
.multival(true)
|
||
.build(),
|
||
),
|
||
],
|
||
pre: Definition::no_op,
|
||
post: Definition::no_op,
|
||
};
|
||
let food_v3 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/food),
|
||
version: 3,
|
||
attributes: vec![
|
||
(
|
||
kw!(:food/name),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::String)
|
||
.multival(false)
|
||
.unique(Unique::Identity)
|
||
.build(),
|
||
),
|
||
// This phrasing is backward, but this is just a test.
|
||
(
|
||
kw!(:food/likes),
|
||
vocabulary::AttributeBuilder::helpful()
|
||
.value_type(ValueType::Ref)
|
||
.multival(true)
|
||
.build(),
|
||
),
|
||
],
|
||
pre: |ip, from| {
|
||
if from.version < 2 {
|
||
lowercase_names(ip).and_then(|_| merge_foods_with_same_name(ip))?;
|
||
}
|
||
if from.version < 3 {
|
||
// Nothing we need to do here. We're going to do the 'like' split outside.
|
||
}
|
||
Ok(())
|
||
},
|
||
post: Definition::no_op,
|
||
};
|
||
let people_v3 = vocabulary::Definition {
|
||
name: kw!(:org.mozilla/people),
|
||
version: 3,
|
||
attributes: people_v1.attributes,
|
||
pre: Definition::no_op,
|
||
post: |ip, from| {
|
||
if from.version < 2 {
|
||
people_v1_to_v2(ip, from)?;
|
||
}
|
||
if from.version < 3 {
|
||
// Nothing we need to do here. We're going to do the 'like' split outside.
|
||
}
|
||
Ok(())
|
||
},
|
||
};
|
||
|
||
// For this more complex option, let's implement the VocabularySource trait rather than
|
||
// using the simple struct. This will allow us to build stateful migrations where the
|
||
// pre and post steps are linked.
|
||
struct CustomVocabulary {
|
||
pre_food_version: Version,
|
||
post_done: bool,
|
||
definitions: Vec<Definition>,
|
||
}
|
||
|
||
let mut all_three = CustomVocabulary {
|
||
pre_food_version: 0,
|
||
post_done: false,
|
||
definitions: vec![people_v3, food_v3, movies_v3],
|
||
};
|
||
|
||
impl VocabularySource for CustomVocabulary {
|
||
fn definitions(&mut self) -> Vec<Definition> {
|
||
self.definitions.clone()
|
||
}
|
||
|
||
fn pre(
|
||
&mut self,
|
||
_in_progress: &mut InProgress<'_, '_>,
|
||
checks: &dyn VocabularyStatus,
|
||
) -> mentat::errors::Result<()> {
|
||
// Take a look at the work the vocabulary manager thinks needs to be done, and see whether we
|
||
// need to migrate data.
|
||
// We'll simulate that here by tracking the version.
|
||
match checks.get(&kw!(:org.mozilla/food)) {
|
||
Some((_, &VocabularyCheck::PresentButNeedsUpdate { ref older_version })) => {
|
||
self.pre_food_version = older_version.version;
|
||
Ok(())
|
||
}
|
||
_ => {
|
||
panic!("Test expected a different state.");
|
||
}
|
||
}
|
||
}
|
||
|
||
fn post(&mut self, ip: &mut InProgress<'_, '_>) -> mentat::errors::Result<()> {
|
||
self.post_done = true;
|
||
|
||
// We know that if this function is running, some upgrade was necessary, and we're now
|
||
// at v3 for all of the vocabulary we care about.
|
||
// Given that this change is safe to try more than once, we don't bother checking versions here.
|
||
let mut builder = TermBuilder::new();
|
||
let person_likes = ip.get_entid(&kw!(:person/likes)).unwrap();
|
||
let food_likes = ip.get_entid(&kw!(:food/likes)).unwrap();
|
||
let movie_likes = ip.get_entid(&kw!(:movie/likes)).unwrap();
|
||
let db_doc = ip.get_entid(&kw!(:db/doc)).unwrap();
|
||
|
||
// Find all uses of :person/likes, splitting them into the two properties we just
|
||
// introduced.
|
||
for (e, v) in ip
|
||
.q_once(
|
||
"[:find ?e ?v
|
||
:where [?e :person/likes ?v]
|
||
[?v :food/name _]]",
|
||
None,
|
||
)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
.map(ev)
|
||
{
|
||
builder.retract(e, person_likes, v.clone())?;
|
||
builder.add(e, food_likes, v)?;
|
||
}
|
||
|
||
for (e, v) in ip
|
||
.q_once(
|
||
"[:find ?e ?v
|
||
:where [?e :person/likes ?v]
|
||
[?v :movie/title _]]",
|
||
None,
|
||
)
|
||
.into_rel_result()?
|
||
.into_iter()
|
||
.map(ev)
|
||
{
|
||
builder.retract(e, person_likes, v.clone())?;
|
||
builder.add(e, movie_likes, v)?;
|
||
}
|
||
|
||
builder.add(
|
||
person_likes,
|
||
db_doc,
|
||
TypedValue::typed_string("Deprecated. Use :movie/likes or :food/likes instead."),
|
||
)?;
|
||
ip.transact_builder(builder).and(Ok(())).map_err(|e| e)
|
||
}
|
||
}
|
||
|
||
{
|
||
let mut in_progress = store.begin_transaction().expect("began");
|
||
|
||
// The good one succeeded!
|
||
in_progress
|
||
.ensure_vocabularies(&mut all_three)
|
||
.expect("expected success");
|
||
in_progress.commit().expect("commit succeeded");
|
||
}
|
||
|
||
// Our custom migrator was able to hold on to state.
|
||
assert_eq!(all_three.pre_food_version, 2);
|
||
assert!(all_three.post_done);
|
||
|
||
// Now we can fetch just the foods or movies that Sam likes, without having to filter on
|
||
// :food/name or :movie/title -- they're separate relations.
|
||
assert_eq!(
|
||
store
|
||
.q_once(
|
||
r#"[:find [?f ...]
|
||
:where [?sam :person/name "Sam"]
|
||
[?sam :food/likes ?f]]"#,
|
||
None
|
||
)
|
||
.into_coll_result()
|
||
.expect("success")
|
||
.len(),
|
||
2
|
||
);
|
||
assert_eq!(
|
||
store
|
||
.q_once(
|
||
r#"[:find [?m ...]
|
||
:where [?sam :person/name "Sam"]
|
||
[?sam :movie/likes ?m]]"#,
|
||
None
|
||
)
|
||
.into_coll_result()
|
||
.expect("success")
|
||
.len(),
|
||
2
|
||
);
|
||
|
||
// Find the height and name of anyone who likes both spice and movies released after 2012,
|
||
// sorted by height.
|
||
let q = r#"[:find ?name ?height
|
||
:order (asc ?height)
|
||
:where [?p :movie/likes ?m]
|
||
[?m :movie/year ?year]
|
||
[(> ?year 2012)]
|
||
[?p :food/likes ?f]
|
||
[?f :food/name "spice"]
|
||
[?p :person/height ?height]
|
||
[?p :person/name ?name]]"#;
|
||
let r = store.q_once(q, None).into_rel_result().unwrap();
|
||
let expected: RelResult<Binding> = vec![
|
||
vec![TypedValue::typed_string("Sam"), TypedValue::Long(162)],
|
||
vec![TypedValue::typed_string("Beth"), TypedValue::Long(172)],
|
||
]
|
||
.into();
|
||
assert_eq!(expected, r);
|
||
|
||
// Find foods that Upstream Color fans like.
|
||
let q = r#"[:find [?food ...]
|
||
:order (asc ?food)
|
||
:where [?uc :movie/title "Upstream Color"]
|
||
[?p :movie/likes ?uc]
|
||
[?p :food/likes ?f]
|
||
[?f :food/name ?food]]"#;
|
||
let r = store.q_once(q, None).into_coll_result().unwrap();
|
||
let expected: Vec<Binding> = vec![
|
||
TypedValue::typed_string("spice").into(),
|
||
TypedValue::typed_string("weird blue worms").into(),
|
||
];
|
||
assert_eq!(expected, r);
|
||
}
|