[ANN] mgo MongoDB driver for Go - r2012.06.22

[Gustavo Niemeyer]

Greetings all,

A major new release of the mgo MongoDB driver for Go has just been
tagged. This release introduces unfortunate but necessary and
previously announced incompatibilities in the API. The motivation
for the API breakage is that several of the methods that modify
existing documents do not provide any way to access useful information
that may be retrieved from the database via a follow up getLastError
command, such as the number of documents affected. The availability of
such information wasn't obvious at the time that the API was designed,
and has been repeatedly requested by developers. Please accept my
apologies for the trouble that the migration will cause. Given such pain
is necessary, a few minor additional changes that were being held back
are also being included to bump quality up.

Project details are available at:

http://labix.org/mgo

Summary of the changes made in this release:

- New *ChangeInfo result for several updating methods.
- NotFound renamed ErrNotFound
- UpdateAll never returns ErrNotFound (as RemoveAll)
- Remove may return ErrNotFound (as Update)
- Query.Modify renamed Apply, takes *Change as a pointer,
and returns *ChangeInfo.
- Signature of EnsureIndexKey, DropIndex, and Hint simplified.
- Added Collection.Create and FindId methods.
- FindRef returns *Query.
- Removed time.Now from fast path.

1
More details about these changes:

- ChangeInfo type introduced:

http://godoc.labix.org/mgo#ChangeInfo

- Collection.Upsert now returns a *ChangeInfo rather than an id:

http://godoc.labix.org/mgo#Collection.Upsert

- Collection.UpdateAll now returns a *ChangeInfo, and does not
return an ErrNotFound in case of errors anymore. Use the
change info to determine how many, and whether any,
documents were affected:

http://godoc.labix.org/mgo#Collection.UpdateAll

- Collection.RemoveAll now returns a *ChangeInfo:

http://godoc.labix.org/mgo#Collection.RemoveAll

- Remove now returns ErrNotFound if the document it's looking
for is not found:

http://godoc.labix.org/mgo#Collection.Remove

- NotFound was renamed ErrNotFound for comformance with the
standard library conventions.

- Query.Modify was renamed Apply and got a new *ChangeInfo
result as well. The change argument is also a pointer now:

http://godoc.labix.org/mgo#Query.Apply

- Query.MapReduce receives the job as a pointer now:

http://godoc.labix.org/mgo#Query.MapReduce

- The Change.New field was renamed ReturnNew, to clarify and
avoid the ambiguity with the Upsert field:

http://godoc.labix.org/mgo#Change

- The EnsureIndexKey, DropIndex, and Hint methods now take
a set of field names rather than a slice with a set of
field names. For example, this statement:

err := collection.EnsureIndexKey([]string{"a", "b"})

may now be more easily spelled as:

err := collection.EnsureIndexKey("a", "b")

More details about the methods:

http://godoc.labix.org/mgo#Collection.EnsureIndexKey
http://godoc.labix.org/mgo#Collection.DropIndex
http://godoc.labix.org/mgo#Query.Hint

- The deprecated form of Sort parameters has been dropped. Use:

query.Sort("lastname", "firstname")

More details:

http://godoc.labix.org/mgo#Query.Sort

- New FindId method that may be used with the common operation
of obtaining objects by the default _id field primary key.

The statement

query := collection.FindId(id)

is equivalent to

query := collection.Find(bson.M{"_id": id})

Documentation:

http://godoc.labix.org/mgo#Collection.FindId

- FindRef now takes only a *DBRef, and returns the *Query.
That makes it look even with Find and FindId, and allows
selecting specific fields, etc. More details:

http://godoc.labix.org/mgo#Collection.FindRef

- The time.Now call has been taken out of the fast path
that leads onto the execution of queries. Thanks to
Felix Sun for providing the call graph identifying the
issue.

- New Collection.Create method for explicit collection
creation:

http://godoc.labix.org/mgo#Collection.Create
http://godoc.labix.org/mgo#CollectionInfo



gustavo @ http://niemeyer.net

[Sankar P]

Will there be a stable version of the API anytime soon ? I was about to release a project that I wrote to production today and that uses some of these changed APIs. Now, I don't want to do it as I know the next update of mgo will break things and so I have to fix it now and it has caused me a slippage.

I am very thankful to your work and not complaining, but it will be good if there is a proper versioning for your library which will be easier to remember. Like, "My application works with mgo driver v1.0 and is not migrated to 2.0 yet" etc.

Thank you a lot for your nice work. The FindById is something that will be very useful to me.

[Gustavo Niemeyer]

Hi Sankar,

On Fri, Jun 22, 2012 at 6:56 AM, Sankar P <sankar.c...@gmail.com> wrote:
> Will there be a stable version of the API anytime soon ? I was about to
> release a project that I wrote to production today and that uses some of
> these changed APIs. Now, I don't want to do it as I know the next update of
> mgo will break things and so I have to fix it now and it has caused me a
> slippage.

The short answer, which is a lie, is that the last version was stable.
I didn't anticipate the need to modify the update functions so
dramatically to implement necessary functionality.

Now, I do see your point, and it's to understand that kind of pain
that I mailed the mgo-users ahead of time to ask people about how they
would take such a hit. I don't recall any issues being brought up
there.

That said, I can definitely do better, and in fact will do right now.
Please expect an email sorting the situation out in a moment.

> I am very thankful to your work and not complaining, but it will be good if
> there is a proper versioning for your library which will be easier to
> remember. Like, "My application works with mgo driver v1.0 and is not
> migrated to 2.0 yet" etc.

Yes, sorry.

> Thank you a lot for your nice work. The FindById is something that will be
> very useful to me.

I'm glad to hear it. I'm considering having equivalent functionality
as UpdateId, RemoveId, and UpsertId.


gustavo @ http://niemeyer.net

[Sankar P]

>
> I'm glad to hear it. I'm considering having equivalent functionality
> as UpdateId, RemoveId, and UpsertId.

Nice. That will be very cool :)

I should also be blamed that I have not followed up the mgo-users list
as sincerely I should've :)

Thank you.

--
Sankar P
http://psankar.blogspot.com

[Gustavo Niemeyer]

On Fri, Jun 22, 2012 at 10:19 AM, Gustavo Niemeyer <gus...@niemeyer.net> wrote:
> The short answer, which is a lie, is that the last version was stable.
> I didn't anticipate the need to modify the update functions so
> dramatically to implement necessary functionality.

(...)

> That said, I can definitely do better, and in fact will do right now.
> Please expect an email sorting the situation out in a moment.

As informed in the other email, that's done:

https://groups.google.com/d/msg/mgo-users/I6vSlr_iz50/612Jb79VPcUJ


gustavo @ http://niemeyer.net