Merge branch 'master' into not-master

Author: zookzook

CHANGELOG.md

@@ -1,3 +1,29 @@
+## 0.7.4
+* Enhancements
+  * added a new option to specify a timeout, when increasing the connction pool is no option
+
+## 0.7.3
+
+* Enhancements
+  * added support for OTP 24
+  * Add support for tls setting in connection string (tschmittni)
+  * Replace deprecated functions (OTP 24) (aenglisc )
+  
+## 0.7.2
+
+* Enhancements
+  * Adds test to cover one of Mongo.find/4 errors (vukanac)
+  * Update specs for Mongo.find/4 with error tuple (vukanac)
+  * Fix build warnings and correct typespec (joeapearson)
+  * Update db_connection version to remove System.stacktrace warnings (vukanac)
+  * Update SCRAM auth procedure (LetThereBeDwight)
+  
+## 0.7.1
+
+* Enhancements
+    * upgraded decimal to 2.0, jason to 1.2
+    * Add proper support for tailable cursors and awaitData (PR #74)
+
 ## 0.7.0
 
 * Enhancements

README.md

@@ -1,4 +1,4 @@
-# An alternative Mongodb driver for Elixir
+# An Alternative Elixir Driver for MongoDB
 [![Build Status](https://travis-ci.org/zookzook/elixir-mongodb-driver.svg?branch=master)](https://travis-ci.org/zookzook/elixir-mongodb-driver)
 [![Coverage Status](https://coveralls.io/repos/github/zookzook/elixir-mongodb-driver/badge.svg?branch=master)](https://coveralls.io/github/zookzook/elixir-mongodb-driver?branch=master)
 [![Hex.pm](https://img.shields.io/hexpm/v/mongodb_driver.svg)](https://hex.pm/packages/mongodb_driver)
@@ -24,7 +24,7 @@
   * support for retryable reads ([See](https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst))
   * support for retryable writes ([See](https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst))
 
-## Data representation
+## Data Representation
 
     BSON                Elixir
     ----------          ------
@@ -50,19 +50,19 @@ BSON symbols can only be decoded.
 
 ## Usage
 
-### Installation:
+### Installation
 
 Add `mongodb_driver` to your mix.exs `deps`.
 
 ```elixir
 defp deps do
-  [{:mongodb_driver, "~> 0.6"}]
+  [{:mongodb_driver, "~> 0.7"}]
 end
 ```
 
 Then run `mix deps.get` to fetch dependencies.
 
-### Simple connection to MongoDB
+### Simple Connection to MongoDB
 
 ```elixir
 # Starts an unpooled connection
@@ -112,7 +112,7 @@ Failing operations return a `{:error, error}` tuple where `error` is a
  }}
 ```
 
-### Connection pooling
+### Connection Pooling
 The driver supports pooling by DBConnection (2.x). By default `mongodb_driver` will start a single 
 connection, but it also supports pooling with the `:pool_size` option. For 3 connections add the `pool_size: 3` option to `Mongo.start_link` and to all 
 function calls in `Mongo` using the pool:
@@ -148,17 +148,31 @@ Due to the mongodb specification, an additional connection is always set up for
 
 ### Replica Sets
 
-To connect to a Mongo cluster that is using replica sets, it is recommended to use the `:seeds` list instead 
-of a `:hostname` and `:port` pair.
+By default, the driver will discover the deployment's topology and will connect
+to the replica set automatically, using either the seed list syntax or the URI
+syntax. Assuming the deployment has nodes at `hostname1.net:27017`,
+`hostname2.net:27017` and `hostname3.net:27017`, either of the following
+invocations will discover the entire deployment:
 
 ```elixir
-{:ok, pid} = Mongo.start_link(database: "test", seeds: ["hostname1.net:27017", "hostname2.net:27017"])
+{:ok, pid} = Mongo.start_link(database: "test", seeds: ["hostname1.net:27017"])
+
+{:ok, pid} = Mongo.start_link(url: "mongodb://hostname1.net:27017/test")
+```
+
+To ensure that the connection succeeds even when some of the nodes are not
+available, it is recommended to list all nodes in both the seed list and the
+URI, as follows:
+
+```elixir
+{:ok, pid} = Mongo.start_link(database: "test", seeds: ["hostname1.net:27017", "hostname2.net:27017", "hostname3.net:27017"])
+
+{:ok, pid} = Mongo.start_link(url: "mongodb://hostname1.net:27017,hostname2.net:27017,hostname3.net:27017/test")
 ```
 
-This will allow for scenarios where the first `"hostname1.net:27017"` is unreachable for any reason 
-and will automatically try to connect to each of the following entries in the list to connect to the cluster.
+Using an SRV URI also discovers all nodes of the deployment automatically.
 
-### Auth mechanisms
+### Auth Mechanisms
 
 For versions of Mongo 3.0 and greater, the auth mechanism defaults to SCRAM. 
 If you'd like to use [MONGODB-X509](https://docs.mongodb.com/manual/tutorial/configure-x509-client-authentication/#authenticate-with-a-x-509-certificate) 
@@ -168,7 +182,7 @@ authentication, you can specify that as a `start_link` option.
 {:ok, pid} = Mongo.start_link(database: "test", auth_mechanism: :x509)
 ```
 
-### AWS, TLS and Erlang SSL ciphers
+### AWS, TLS and Erlang SSL Ciphers
 
 Some MongoDB cloud providers (notably AWS) require a particular TLS cipher that isn't enabled 
 by default in the Erlang SSL module. In order to connect to these services,
@@ -204,14 +218,18 @@ Using `$in`
 Mongo.find(:mongo, "users", %{email: %{"$in" => ["[email protected]", "[email protected]"]}})
 ```
 
-### Change streams
+### Change Streams
+
+Change streams are available in replica set and sharded cluster deployments
+and tell you about changes to documents in collections. They work like endless
+cursors.
+
+The special thing about change streams is that they are resumable: in case of
+a resumable error, no exception is propagated to the application, but instead
+the cursor is re-scheduled at the last successful location. 
 
-Change streams exist in replica set and cluster systems and tell you about changes to collections. 
-They work like endless cursors.
-The special thing about the change streams is that they are resumable. In the case of a resumable error, 
-no exception is made, but the cursor is re-scheduled at the last successful location. 
-The following example will never stop, 
-so it is a good idea to use a process for change streams. 
+The following example will never stop, thus it is a good idea to use a process
+for reading from change streams:
 
 ```elixir
 seeds = ["hostname1.net:27017", "hostname2.net:27017", "hostname3.net:27017"]
@@ -220,7 +238,7 @@ cursor =  Mongo.watch_collection(top, "accounts", [], fn doc -> IO.puts "New Tok
 cursor |> Enum.each(fn doc -> IO.puts inspect doc end)
 ```
 
-An example with a spawned process that sends message to the monitor process: 
+An example with a spawned process that sends messages to the monitor process: 
 
 ```elixir
 def for_ever(top, monitor) do
@@ -231,7 +249,7 @@ end
 spawn(fn -> for_ever(top, self()) end)
 ```
 
-For more information see
+For more information see:
 
 * [Mongo.watch_collection](https://hexdocs.pm/mongodb_driver/Mongo.html#watch_collection/5) 
 
@@ -252,7 +270,22 @@ Mongo.insert_many(top, "users", [
 ])
 ```
 
-### Bulk writes
+### Indexes
+
+To create indexes you can call the function `Mongo.createIndexed/4`:
+
+```elixir
+indexes =  [[key: [files_id: 1, n: 1], name: "files_n_index", unique: true]]
+Mongo.create_indexes(topology_pid, "my_collection", indexes, opts)
+```
+
+You specify the `indexes` parameter as a keyword list with all options described in the documentation of the [createIndex](https://docs.mongodb.com/manual/reference/command/createIndexes/#dbcmd.createIndexes) command.
+
+For more information see:
+* [Mongo.create_indexes](https://hexdocs.pm/mongodb_driver/Mongo.html#create_indexes/4) 
+* [Mongo.drop_index](https://hexdocs.pm/mongodb_driver/Mongo.html#drop_index/4)
+ 
+### Bulk Writes
 
 The motivation for bulk writes lies in the possibility of optimization, the same operations
 to group. Here, a distinction is made between disordered and ordered bulk writes.
@@ -316,10 +349,8 @@ and have a look at the test units as well.
 
 ### GridFS
 
-The driver supports the GridFS specifications. You create a `Mongo.GridFs.Bucket` struct and with this struct you can
-upload and download files.
-
-### Example
+The driver supports the GridFS specifications. You create a `Mongo.GridFs.Bucket`
+struct and with this struct you can upload and download files. For example:
 
 ```elixir
     bucket = Bucket.new(top)
@@ -405,8 +436,6 @@ iex> Mongo.find_one(conn, "test", %{})
 The `travis.yml` file uses only the latest MongoDB. It creates a replica set of three nodes and disables the SSL test case. If you want to
 run the test cases against other MongoDB deployments or older versions, you can use the [mtools](https://github.com/rueckstiess/mtools) for deployment and run the test cases locally:
 
-### Example
-
 ```bash
 pyenv global 3.6
 pip3 install --upgrade pip
@@ -418,11 +447,11 @@ mix test --exclude ssl --exclude socket
 
 The SSL test suite is disabled by default.
 
-### Enable the SSL tests
+### Enable the SSL Tests
 
 `mix test --exclude ssl`
 
-### Enable SSL on your Mongo server
+### Enable SSL on Your MongoDB Server
 
 ```bash
 $ openssl req -newkey rsa:2048 -new -x509 -days 365 -nodes -out mongodb-cert.crt -keyout mongodb-cert.key
@@ -433,21 +462,21 @@ $ mongod --sslMode allowSSL --sslPEMKeyFile /path/to/mongodb.pem
 * For `--sslMode` you can use one of `allowSSL` or `preferSSL`
 * You can enable any other options you want when starting `mongod`
 
-## More examples
+## More Examples
 
 There are some basic examples in the `example` folder. But if you want to see the driver in action 
 take a look at [Vega](https://github.com/zookzook/vega), especially the [Board.ex](https://github.com/zookzook/vega/blob/master/lib/vega/board.ex) module for using the transaction api together with
 bulk operations.
 
-## Special thanks
+## Special Thanks
 
 Special thanks to [JetBrains](https://www.jetbrains.com/?from=elixir-mongodb-driver) for providing a free JetBrains Open Source license for their complete toolbox.
 
 The [Documentation](https://hexdocs.pm/mongodb_driver/readme.html) is online, but currently not up to date. 
 This will be done as soon as possible. In the meantime, look in the source code. Especially 
 for the individual options.  
 
-This driver is based on [original](https://github.com/ankhers/mongodb).
+This driver is based on the [original Elixir driver for MongoDB](https://github.com/ankhers/mongodb).
 
 ## License
 

lib/bson/types.ex

@@ -9,20 +9,32 @@ defmodule BSON.Binary do
   }
   defstruct [binary: nil, subtype: :generic]
 
-  defimpl Inspect do
-    def inspect(%BSON.Binary{binary: value, subtype: :generic}, _opts) do
-      "#BSON.Binary<#{Base.encode16(value, case: :lower)}>"
-    end
-    def inspect(%BSON.Binary{binary: value, subtype: :uuid}, _opts) do
+  defimpl String.Chars, for: BSON.Binary do
+    def to_string(%BSON.Binary{binary: value, subtype: subtype}) when subtype in [:uuid, :uuid_old] do
       p1 = binary_part(value, 0, 4)
       p2 = binary_part(value, 4, 2)
       p3 = binary_part(value, 6, 2)
       p4 = binary_part(value, 8, 2)
       p5 = binary_part(value, 10, 6)
-      "#BSON.UUID<#{Base.encode16(p1, case: :lower)}-#{Base.encode16(p2, case: :lower)}-#{Base.encode16(p3, case: :lower)}-#{Base.encode16(p4, case: :lower)}-#{Base.encode16(p5, case: :lower)}>"
+      "#{Base.encode16(p1, case: :lower)}-#{Base.encode16(p2, case: :lower)}-#{Base.encode16(p3, case: :lower)}-#{Base.encode16(p4, case: :lower)}-#{Base.encode16(p5, case: :lower)}"
+    end
+    def to_string(%BSON.Binary{binary: value}) do
+      Base.encode16(value, case: :lower)
+    end
+  end
+
+  defimpl Inspect do
+    def inspect(%BSON.Binary{subtype: :generic} = binary, _opts) do
+      "#BSON.Binary<#{to_string(binary)}>"
+    end
+    def inspect(%BSON.Binary{subtype: :uuid} = binary, _opts) do
+      "#BSON.UUID<#{to_string(binary)}>"
+    end
+    def inspect(%BSON.Binary{subtype: :uuid_old} = binary, _opts) do
+      "#BSON.LUUID<#{to_string(binary)}>"
     end
-    def inspect(%BSON.Binary{binary: value, subtype: subtype}, _opts) do
-      "#BSON.Binary<#{Base.encode16(value, case: :lower)}, #{subtype}>"
+    def inspect(%BSON.Binary{subtype: subtype} = binary, _opts) do
+      "#BSON.Binary<#{to_string(binary)}, #{subtype}>"
     end
   end
 end

lib/mongo.ex

@@ -10,6 +10,8 @@ defmodule Mongo do
     * `:timeout` - The maximum time that the caller is allowed the to hold the
       connection’s state (ignored when using a run/transaction connection,
       default: `15_000`)
+    * `:checkout_timeout` - The maximum time for checking out a new session and connection (default: `60_000`).
+      When the connection pool exhausted then the function call times out after :checkout_timeout.
     * `:pool` - The pooling behaviour module to use, this option is required
       unless the default `DBConnection.Connection` pool is used
     * `:pool_timeout` - The maximum time to wait for a reply when making a
@@ -636,7 +638,7 @@ defmodule Mongo do
        Mongo.find(top, "jobs", %{}, batch_size: 2)
 
   """
-  @spec find(GenServer.server, collection, BSON.document, Keyword.t) :: cursor
+  @spec find(GenServer.server, collection, BSON.document, Keyword.t) :: cursor | {:error, term()}
   def find(topology_pid, coll, filter, opts \\ []) do
 
     filter = case normalize_doc(filter) do
@@ -657,7 +659,6 @@ defmodule Mongo do
            showRecordId: opts[:show_record_id],
            tailable: opts[:tailable],
            oplogReplay: opts[:oplog_replay],
-           tailable: opts[:tailable],
            noCursorTimeout: opts[:no_cursor_timeout],
            awaitData: opts[:await_data],
            batchSize: opts[:batch_size],
@@ -670,7 +671,7 @@ defmodule Mongo do
 
     cmd = filter_nils(cmd)
 
-    drop = ~w(limit hint single_batch read_concern max min collation return_key show_record_id tailable no_cursor_timeout await_data batch_size projection comment max_time skip sort)a
+    drop = ~w(limit hint single_batch read_concern max min collation return_key show_record_id tailable no_cursor_timeout await_data projection comment skip sort)a
     opts = Keyword.drop(opts, drop)
     try do
       get_stream(topology_pid, cmd, opts)
@@ -1202,9 +1203,14 @@ defmodule Mongo do
   end
 
   @doc """
-  Convenient function to creates new indexes in the collection `coll`.
+  Convenient function to creates new indexes in the collection `coll`. The `indexes` parameter is a
+  list with all options for creating indexes in the MongoDB.
+
+  See
+  [options](https://docs.mongodb.com/manual/reference/command/createIndexes/#dbcmd.createIndexes)
+  about the details of each parameter.
   """
-  @spec create_indexes(GenServer.server, String.t, Keyword.t, Keyword.t) :: :ok | {:error, Mongo.Error.t}
+  @spec create_indexes(GenServer.server, String.t, [Keyword.t], Keyword.t) :: :ok | {:error, Mongo.Error.t}
   def create_indexes(topology_pid, coll, indexes, opts \\ []) do
     cmd = [createIndexes: coll, indexes: indexes]
     with {:ok, _} <- Mongo.issue_command(topology_pid, cmd, :write, opts) do