guacamole 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da19a1adc7e260053f9749aaaa5af277e706fbda
-  data.tar.gz: 08392381e86a454d91a3da30efac6b86599234be
+  metadata.gz: 8e3a2220d3b6b1d046bb962bf652a800b899e825
+  data.tar.gz: 2de4ad8f20cfc6af2cb55aaf312177507974cac8
 SHA512:
-  metadata.gz: 40ec254c0113a1f8ee0bc2dbdb8624c2d5f3c0ea55cb1e981e45d91b38eb4167f590896cce392d9c5a8419ddea208ce29600f116b24fbf7f2108aa0181c54b47
-  data.tar.gz: b7b301e8c84692d620316a29e02ee654b6358427e5e92016957a7f66aeb9b249268eacffffe9d715bb28f7508f9ec3ca8746ef92f043326c56ecc7a0f4cab708
+  metadata.gz: 78e8fd40d3284e7abd1eac0c97d46d59413c53edc8c23693d8f6f686948486aa353443b3484fa67f5d39b247382674b17840d05591e00353b61735b008226db2
+  data.tar.gz: cbaeb3e19f0223bdca0f52122d042169528b4ba8f9ef7d983a4364d016b29d40ed39463ea7d77c08d9ccd9f1c59a82a7f2dbd0adb8a4672e0ee5739277c2b1e3

data/.hound.yml

@@ -22,7 +22,7 @@ CollectionMethods:
   PreferredMethods:
     collect:  'map'
     inject:   'reduce'
-    find:     'detect'
+    find:     'find'
     find_all: 'select'
 
 SignalException:

data/.travis.yml

@@ -1,24 +1,25 @@
 language: ruby
-bundler_args: --without debug
+bundler_args: "--without debug"
 before_script:
-  - ./spec/setup/arangodb.sh
+- "./spec/setup/arangodb.sh"
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.2
-  - jruby-19mode
-  - jruby-head
-  - rbx-19mode
-  - ruby-head
+- 1.9.3
+- 2.0.0
+- 2.1.2
+- jruby-19mode
+- jruby-head
+- ruby-head
 env:
-  - ARANGODB_DISABLE_AUTHENTIFICATION=true VERSION=2.0
+- ARANGODB_DISABLE_AUTHENTIFICATION=true VERSION=2.2
 matrix:
   allow_failures:
-    - rvm: jruby-19mode
-    - rvm: ruby-head
-    - rvm: jruby-head
-    - rvm: rbx-19mode
-script: "bundle exec rake ci"
+  - rvm: jruby-19mode
+  - rvm: ruby-head
+  - rvm: jruby-head
+script: bundle exec rake ci
 addons:
   code_climate:
     repo_token: cd5dd119d022e5b0d4fda98d25aa93473ed5b580c3f621475c3e605a858f5790
+notifications:
+  slack:
+    secure: H8F0Eo0dc0uP0kh4Wm4D6kDuDeEQrjTotUpz2n4Ls8errJp0r0C9CbXrRE574B1VeZF/tBzm9IUx4wDRuR2xaYfIww5gJTz2+RKp+thgspz8L3KW5nuLttxzqp8cNP2b9Gedj72nTebQK3gEt7v/HFgo9lg2QSEvZ4n7zYFkmIc=

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## Version 0.4.0
+
+**Codename: Theatre of Pain**
+
+This release focus on the graph integration of ArangoDB 2.2. We implemented relations on top of graphs. The old implementation for relations **has been removed**. If you still need it **don't just upgrade**.
+
+Notable changes are:
+
+  * Implement relations with a graph (#83)
+  * Added section about design to GOALS.md
+  * AQL Support is default now (#91)
+  * Typo fixes in the README (@badboy, @ifraixedes, @solnic @timoschilling)
+  * Internal changes
+    * Relations based on foreign keys have been removed
+
+
 ## Version 0.3.0
 
 **Codename: Spread your Wings**

data/GOALS.md

@@ -6,9 +6,17 @@
 * Reflect the nature of NoSQL in general and ArangoDB in particular
     * Use the Datamapper pattern, because it allows us to leverage ArangoDB features like nesting in a really nice way
     * Support ArangoDB features like transactions, the query language and graphs
+* Don't cut corners on quality
+* Strive for simplicity
 
 *The two main goals may conflict from time to time.*
 
+## Design Decisions
+
+We are well aware that the decision for data mapper in favor of active record has certain drawbacks. But this is the case with every single decision one will ever make in software development. We have strong believes in a simple software design. We think when it comes to building applications a good simple design can only be achieved by using simple libraries and frameworks. ActiveRecord is not simple anymore. And its usage will result in a not simple application. In our opinion one reason for this is the usage of the active record pattern. ActiveRecord is very convenient but it is not simple. Going with a data mapper approach is less convenient at first but will pay off in the long run.
+
+At the same time Guacamole should enable people to use [ArangoDB](https://www.arangodb.com) in their Ruby and especially Rails projects. Due to this we will always have to compromise between our pursuit of simplicity and the usability for a wide range of developers who are mostly used to the Rails Way of doing things. We try do be more on the simple side but eventually we will fail from time to time. We don't think this is inherently a bad thing because to fail is to learn as well. We will always re-evaluate our decisions and refactor whenever possible.
+
 ## Features of Guacamole 1.0
 
 **This is definitely a moving target and up to discussion. For non-moving targets refer to our [milestones](https://github.com/triAGENS/guacamole/issues/milestones).**

data/Guardfile

@@ -7,3 +7,7 @@ guard 'rspec', spec_paths: ['spec/unit'] do
   watch(%r{spec/.+\.rb})
   watch(%r{lib/guacamole/(.+)\.rb$}) { |m| "spec/unit/#{m[1]}_spec.rb" }
 end
+
+guard 'rspec', spec_path: ['spec/acceptance'] do
+  watch(%r{spec/acceptance/.+\.rb})
+end

data/README.md

@@ -3,10 +3,11 @@
 [![Code Climate](http://img.shields.io/codeclimate/github/triAGENS/guacamole.svg)](https://codeclimate.com/github/triAGENS/guacamole)
 [![Inline docs](http://inch-ci.org/github/triAGENS/guacamole.svg)](http://inch-ci.org/github/triAGENS/guacamole)
 [![Gem Version](http://img.shields.io/gem/v/guacamole.svg)](https://rubygems.org/gems/guacamole)
+[![Codeship Status](https://codeship.io/projects/a30d6040-350a-0132-1102-3e0229153f11/status)](https://codeship.io/projects/40903)
 
 # Guacamole
 
-Guacamole is an Object Document Mapper (ODM) for the multi-model NoSQL database [ArangoDB](https://www.arangodb.org/). Its main goal is to support easy integration into Ruby on Rails but will likely work in other Rack-based frameworks as well. There are a couple of design goals behind Guacamole which should drive all our development effort:
+Guacamole is an Object Document Mapper (ODM) for the multi-model NoSQL database [ArangoDB](https://www.arangodb.com/). Its main goal is to support easy integration into Ruby on Rails but will likely work in other Rack-based frameworks as well. There are a couple of design goals behind Guacamole which should drive all our development effort:
 
   * Easy integration on the View layer (i.e. form builders)
   * Reflect the nature of NoSQL in general and ArangoDB in particular
@@ -86,7 +87,7 @@ After you created a configuration file you can create the database as in any oth
 bundle exec rake db:create
 ```
 
-If you're using Capistrano or something else make sure you change your deployment recipes accordingly to use the `guacamole.yml` and not the `database.yml`. Of course you would want to add [authentication](https://www.arangodb.org/manuals/2/DbaManualAuthentication.html) for the production environment. Additionally you may want to consider putting ArangoDB behind a SSL-proxy or use the [built in SSL support](https://www.arangodb.org/manuals/2/CommandLine.html#CommandLineArangoEndpoint).
+If you're using Capistrano or something else make sure you change your deployment recipes accordingly to use the `guacamole.yml` and not the `database.yml`. Of course you would want to add [authentication](https://docs.arangodb.com/ConfigureArango/Authentication.html) for the production environment. Additionally you may want to consider putting ArangoDB behind a SSL-proxy or use the [built in SSL support](https://docs.arangodb.com/ConfigureArango/Arangod.html).
 
 Now where everything is set up we can go ahead and create our application's logic. Before we give you some code to copy and paste we first give you a general usage and design overview.
 
@@ -146,7 +147,7 @@ We will automatically add both a `created_at` and an `updated_at` attribute to a
 
 #### The ID of a model
 
-In ArangoDB a document has three internal fields: `_id`, `_key` and `_rev`. For a detailed explanation how these three work together please refer to the [ArangoDB documentation](https://www.arangodb.org/manuals/2/HandlingDocuments.html#HandlingDocumentsIntro). Within Guacamole we will always use the `_key` because it is enough the identify any document within a collection. Both the `_key` and `_rev` attribute are available through the `Guacamole::Model#key` and `Guacamole::Model#rev` attribute. You don't have to do anything for this, we will take care of this for you.
+In ArangoDB a document has three internal fields: `_id`, `_key` and `_rev`. For a detailed explanation how these three work together please refer to the [ArangoDB documentation](https://docs.arangodb.com/Documents/DocumentAddress.html). Within Guacamole we will always use the `_key` because it is enough the identify any document within a collection. Both the `_key` and `_rev` attribute are available through the `Guacamole::Model#key` and `Guacamole::Model#rev` attribute. You don't have to do anything for this, we will take care of this for you.
 
 Additionally you will find an `id` method on you models. This is just an alias for `key`. This was added for `ActiveModel::Conversion` compliance. You **should always** use `key`.
 
@@ -189,10 +190,10 @@ As with the models we provide a generator to help you creating your collection c
 bundle exec rails generate collection ponies
 ```
 
-Currently your options what you can do with a collection are quire limited. We will eventually add more features, but for now you basically have this features:
+Currently your options what you can do with a collection are quite limited. We will eventually add more features, but for now you basically have this features:
 
   * CRUD operations for your models
-  * Where the "Read"-part is limited to [Simple Queries](https://www.arangodb.org/manuals/2/SimpleQueries.html). But more on this later.
+  * Where the "Read"-part is limited to [Simple Queries](https://docs.arangodb.com/SimpleQueries/README.html). But more on this later.
   * Mapping embedded models
   * Realizing basic associations
 
@@ -235,7 +236,7 @@ PoniesCollection.delete existing_pony
 
 #### Retrieve models
 
-As mentioned before querying for models is quite limited as of now. We only support [Simple Queries](https://www.arangodb.org/manuals/2/SimpleQueries.html) at this point. You can perform the following basic operations with them:
+As mentioned before querying for models is quite limited as of now. We only support [Simple Queries](https://docs.arangodb.com/SimpleQueries/README.html) at this point. You can perform the following basic operations with them:
 
   * Getting a single model `by_key`
   * Getting `all` models from a collection.
@@ -252,7 +253,7 @@ some_ponies.first
 # => #<Pony:0x90u81 …>
 ```
 
-We're well aware this is not sufficient for building sophisticated applications. We're are working on something to make [AQL](https://www.arangodb.org/manuals/2/Aql.html) usable from Guacamole.
+We're well aware this is not sufficient for building sophisticated applications. We're are working on something to make [AQL](https://docs.arangodb.com/Aql/README.html) usable from Guacamole.
 
 ### Mapping
 
@@ -296,6 +297,7 @@ Currently there is no option to change the mapping of attributes. If you want to
 
 #### Associations
 
+**TODO: This needs some work to include relations**
 Besides simple attributes we want to handle associations between models. To add an association between your models you have two options: __embedded__ and __referenced__.
 
 #### Embedded references
@@ -354,67 +356,9 @@ As you can see, from the model perspective there is nothing special about an emb
 
 **Note**: Again this will only work if you stick with the convention. So far there is no support to configure this more fine grained.
 
-#### References
+### Relations
 
-While there are perfect use cases to embed documents into each other there are still plenty of use cases where referencing documents makes perfect sense. In fact this one feature where ArangoDB can really shine: Instead of just getting all referenced documents with dedicated calls to the server and without the possibility to perform any functions like filtering or sorting the data, ArangoDB can perform joins over your data just like a RDBMS.
-
-**Note**: In the current version we're not using this power since we need to support AQL before that. As of now references are realized with dedicated calls to the database.
-
-To define references between models you just add the appropriate attributes to the `Model` classes:
-
-```ruby
-class Author
-  include Guacamole::Model
-
-  attribute :name, String
-  attribute :posts, Array[Post]
-end
-
-class Post
-  include Guacamole::Model
-
-  attribute :title, String
-  attribute :author, Author
-end
-```
-
-As with the embedded models the real work happens in the `Collection` classes:
-
-```ruby
-class AuthorsCollection
-  include Guacamole::Collection
-
-  map do
-    referenced_by :posts
-  end
-end
-
-class PostsCollection
-  include Guacamole::Collection
-
-  map do
-    references :author
-  end
-end
-```
-
-Under the hood we will add an `author_id` to all posts holding the reference to the author. As a user this will be completely transparent for you:
-
-```ruby
-author = AuthorsCollection.by_key "23124"
-author.posts
-# => [#<Post:0x12341 …>, …]
-```
-
-The same goes for saving the data. Just add `Post`s to an `Author` as you would in plain Ruby. Passing one of the models to its `Collection` class will take care of the rest:
-
-```ruby
-author = Author.new(name: "Lauren Faust")
-author.posts << Post.new(title: "This is amazing")
-
-AuthorsCollection.save author
-# => Will save both the author and the post
-```
+**>>>> Insert documentation for relations here!**
 
 ### Callbacks
 
@@ -442,7 +386,7 @@ class User
 end
 ``` 
 
-You can define define callbacks for the following actions:
+You can define callbacks for the following actions:
 
  * `before_validate`
  * `around_validate`
@@ -560,33 +504,29 @@ While there are a lot of open issues we would like to present you a high level o
   * An example Rails application to be used as both an acceptance test suite and a head start for Guacamole and ArangoDB
   * An AQL query builder
 
-### Experimental AQL Support
+### AQL Support
 
-As mentioned before we're working on [something more sophisticated to support AQL](https://github.com/moonglum/brazil/issues/8). But this will not be finished any time soon. Meanwhile you could play with the experimental AQL support:
-
-```ruby
-config.guacamole.experimental_features = [:aql_support]
-```
-
-After that you can perform very basic queries like this one:
+As mentioned before we're working on [something more sophisticated to support AQL](https://github.com/moonglum/brazil/issues/8). But this will not be finished any time soon. That said, there is still a way to to perform AQL queries against ArangoDB. For simple queries you can do something like this:
 
 ```ruby
 PoniesCollection.by_aql('FILTER pony.name == @name', name: 'Rainbow Dash')
 ```
 
-The result of this will a correctly mapped Array of `Pony` models.
-
-**Note**: Please use only this form to pass parameters into a query. Using string interpolation will leave you vulnerable to AQL-injections.
+The result of this will a correctly mapped Array of `Pony` models. If this is not enough thou, don't worry, you can get really fancy with this. Due to this you can deactivate the automatic mapping of the response. In that case you will receive just a raw document you can work with. **Note**: Please use only this form to pass parameters into a query. Using string interpolation will leave you vulnerable to AQL-injections.
 
 For more information about usage please refer to the RDoc and the code.
 
 ## Issues or Questions
 
-If you find a bug in this gem, please report it on [our tracker](https://github.com/triAGENS/guacamole/issues). We use [Waffle.io](https://waffle.io/triagens/guacamole) to manage the tickets – go there to see the current status of the ticket. If you have a question, just contact us via the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/ashikawa) – we are happy to help you :smile:
+If you find a bug in this gem, please report it on [our tracker](https://github.com/triAGENS/guacamole/issues). If you have a question, just contact us via the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/ashikawa) – we are happy to help you :smile:
 
 ## Contributing
 
-If you want to contribute to the project, see CONTRIBUTING.md for details. It contains information on our process and how to set up everything. The following people have contributed to this project:
+If you want to contribute to the project, see [CONTRIBUTING.md](CONTRIBUTING.md) for details. It contains information on our process and how to set up everything. The following people have contributed to this project:
 
 * Lucas Dohmen ([@moonglum](https://github.com/moonglum)): Developer
 * Dirk Breuer ([@railsbros-dirk](https://github.com/railsbros-dirk)): Developer
+
+## Inspiration
+
+The work on Guacamole is heavily inspired by the remarkable work of the [ROM](http://rom-rb.org) team and especially by [Piotr Solnica](http://solnic.eu).

data/guacamole.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.name          = 'guacamole'
   spec.version       = Guacamole::VERSION
   spec.authors       = ['Lucas Dohmen', 'Dirk Breuer']
-  spec.email         = ['moonglum@moonbeamlabs.com', 'dirk.breuer@gmail.com']
+  spec.email         = ['lucas@arangodb.com', 'dirk@arangodb.com']
   spec.description   = %q{ODM for ArangoDB}
   spec.summary       = %q{An ODM for ArangoDB that uses the DataMapper pattern.}
   spec.homepage      = 'http://guacamolegem.org'
@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(spec)/})
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'ashikawa-core', '~> 0.12.0'
+  spec.add_dependency 'ashikawa-core', '~> 0.13.1'
   spec.add_dependency 'virtus', '~> 1.0.1'
   spec.add_dependency 'activesupport', '>= 4.0.0'
   spec.add_dependency 'activemodel', '>= 4.0.0'
@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry', '~> 0.9.12'
   spec.add_development_dependency 'rake', '~> 10.3.2'
   spec.add_development_dependency 'reek', '~> 1.3.7'
-  spec.add_development_dependency 'rspec', '~> 3.0.0'
+  spec.add_development_dependency 'rspec', '~> 3.1.0'
   spec.add_development_dependency 'timecop', '~> 0.7.1'
   spec.add_development_dependency 'yard', '~> 0.8.7.4'
 end

data/lib/guacamole.rb

@@ -5,6 +5,7 @@ require 'guacamole/exceptions'
 require 'guacamole/configuration'
 require 'guacamole/model'
 require 'guacamole/collection'
+require 'guacamole/edge'
 require 'guacamole/callbacks'
 require 'guacamole/document_model_mapper'
 require 'guacamole/identity_map'

data/lib/guacamole/aql_query.rb

@@ -44,7 +44,7 @@ module Guacamole
     #
     # @return [String] An AQL string ready to be send to Arango
     def aql_string
-      aql_string = "FOR #{model_name} IN #{collection_name} #{aql_fragment} #{return_as}"
+      aql_string = "#{for_in} #{aql_fragment} #{return_as}"
       Guacamole.logger.debug "[AQL] #{aql_string} | bind_parameters: #{bind_parameters}"
       aql_string
     end
@@ -56,6 +56,10 @@ module Guacamole
       options[:return_as]
     end
 
+    def for_in
+      options[:for_in]
+    end
+
     # Should the mapping step be perfomed? If set to false we will return the raw document.
     #
     # @return [Boolean] Either if the mapping should be perfomed or not
@@ -69,6 +73,7 @@ module Guacamole
     def default_options
       {
         return_as: "RETURN #{model_name}",
+        for_in:    "FOR #{model_name} IN #{collection_name}",
         mapping:   true
       }
     end

data/lib/guacamole/collection.rb

@@ -2,6 +2,7 @@
 
 require 'guacamole/query'
 require 'guacamole/aql_query'
+require 'guacamole/transaction'
 
 require 'ashikawa-core'
 require 'active_support'
@@ -34,7 +35,7 @@ module Guacamole
       def_delegators :mapper, :model_to_document
       def_delegator :connection, :fetch, :fetch_document
 
-      attr_accessor :connection, :mapper, :database
+      attr_accessor :connection, :mapper, :database, :graph
 
       # The raw `Database` object that was configured
       #
@@ -47,18 +48,33 @@ module Guacamole
         @database ||= Guacamole.configuration.database
       end
 
+      # The application graph to be used
+      #
+      # This is quite important since we're using the Graph module to realize relations
+      # between models. To guarantee consistency of your data all requests must be routed
+      # through the graph module.
+      #
+      # @see http://rubydoc.info/gems/ashikawa-core/Ashikawa/Core/Graph
+      # @return [Ashikawa::Core::Graph]
+      def graph
+        @graph ||= Guacamole.configuration.graph
+      end
+
       # The raw `Collection` object for this collection
       #
       # You can use this method for low level communication with the collection.
       # Details can be found in the Ashikawa::Core documentation.
       #
-      # @note We're well aware that we return a Ashikawa::Core::Collection here
+      # @note We're well aware that we return a Ashikawa::Core::VertecCollection here
       #       but naming it a connection. We think the name `connection` still
       #       fits better in this context.
-      # @see http://rubydoc.info/gems/ashikawa-core/Ashikawa/Core/Collection
-      # @return [Ashikawa::Core::Collection]
+      # @see http://rubydoc.info/gems/ashikawa-core/Ashikawa/Core/VertexCollection
+      # @return [Ashikawa::Core::VertexCollection]
       def connection
-        @connection ||= database[collection_name]
+        # FIXME: This is a workaround for a bug in Ashikawa::Core (https://github.com/triAGENS/ashikawa-core/issues/139)
+        @connection ||= graph.add_vertex_collection(collection_name)
+      rescue
+        @connection ||= graph.vertex_collection(collection_name)
       end
 
       # The DocumentModelMapper for this collection
@@ -231,13 +247,7 @@ module Guacamole
       #
       # Since Simple Queries are quite limited in their possibilities you will need to
       # use AQL for more advanced data retrieval. Currently there is only a very basic
-      # and experimental support for AQL. Eventually we will replace it with an advanced
-      # query builder DSL. Due to this, we deactivated this feature per default. You
-      # need to activate it with {Configuration#aql_support}:
-      #
-      #   Guacamole::Configuration.aql_support = :experimental
-      #
-      # If not activated it we will raise an error.
+      # support for AQL. Nevertheless it will allow to use any arbitrary query you want.
       #
       # @param [String] aql_fragment An AQL string that will will be put between the
       #                 `FOR x IN coll` and the `RETURN x` part.
@@ -246,13 +256,10 @@ module Guacamole
       # @option options [String] :return_as ('RETURN #{model_name}') A custom `RETURN` statement
       # @option options [Boolean] :mapping (true) Should the mapping be performed?
       # @return [Query]
-      # @raise [AQLNotSupportedError] If `aql_support` was not activated
       # @note Please use always bind parameters since they provide at least some form
       #       of protection from AQL injection.
-      # @see https://www.arangodb.org/manuals/2/Aql.html AQL Documentation
+      # @see https://docs.arangodb.com/Aql/README.html AQL Documentation
       def by_aql(aql_fragment, bind_parameters = {}, options = {})
-        raise AQLNotSupportedError unless Guacamole.configuration.experimental_features.include?(:aql_support)
-
         query                 = AqlQuery.new(self, mapper, options)
         query.aql_fragment    = aql_fragment
         query.bind_parameters = bind_parameters
@@ -294,54 +301,12 @@ module Guacamole
       #       persisted. In future versions we should add something like `:autosave`
       #       to always save associated models.
       def create_document_from(model)
-        create_referenced_models_of model
+        result = with_transaction(model)
 
-        document = connection.create_document(model_to_document(model))
+        model.key = result[model.object_id.to_s]['_key']
+        model.rev = result[model.object_id.to_s]['_rev']
 
-        model.key = document.key
-        model.rev = document.revision
-
-        create_referenced_by_models_of model
-
-        document
-      end
-
-      # Creates all not yet persisted referenced models of `model`
-      #
-      # Referenced models needs to be created before the parent model, because it needs their `key`
-      #
-      # @api private
-      # @todo This method should be considered 'work in progress'. We already know we need to change this.
-      # @return [void]
-      def create_referenced_models_of(model)
-        mapper.referenced_models.each do |ref_model_name|
-          ref_collection = mapper.collection_for(ref_model_name)
-
-          ref_model = model.send(ref_model_name)
-          next unless ref_model
-
-          ref_collection.save ref_model unless ref_model.persisted?
-        end
-      end
-
-      # Creates all not yet persisted models which are referenced by `model`
-      #
-      # Referenced by models needs to created after the parent model, because they need its `key`
-      #
-      # @api private
-      # @todo This method should be considered 'work in progress'. We already know we need to change this.
-      # @return [void]
-      def create_referenced_by_models_of(model)
-        mapper.referenced_by_models.each do |ref_model_name|
-          ref_collection = mapper.collection_for(ref_model_name)
-
-          ref_models = model.send(ref_model_name)
-
-          ref_models.each do |ref_model|
-            ref_model.send("#{model.class.name.demodulize.underscore}=", model)
-            ref_collection.save ref_model unless ref_model.persisted?
-          end
-        end
+        model
       end
 
       # Replace a document in the database with this model
@@ -349,12 +314,15 @@ module Guacamole
       # @api private
       # @note This will **not** update associated models (see {#create})
       def replace_document_from(model)
-        document = model_to_document(model)
-        response = connection.replace(model.key, document)
+        result = with_transaction(model)
 
-        model.rev = response['_rev']
+        model.rev = result['_rev']
+
+        model
+      end
 
-        document
+      def with_transaction(model)
+        Transaction.run(collection: self, model: model)
       end
 
       # Gets the callback class for the given model class