Home

Awesome

Meddler Build Status GoDoc Go Report Card

Meddler is a small toolkit to take some of the tedium out of moving data back and forth between SQL queries and structs.

It is not a complete ORM. Meddler is intended to be a lightweight way to add some of the convenience of an ORM while leaving more control in the hands of the programmer.

Package docs are available at:

The package is housed on GitHub, and the README there has more info:

Meddler is currently configured for SQLite, MySQL, and PostgreSQL, but it can be configured for use with other databases. If you use it successfully with a different database, please contact me and I will add it to the list of pre-configured databases.

DANGER

Meddler is still a work in progress, and additional backward-incompatible changes to the API are likely. The most recent change added support for multiple database types and made it easier to switch between them. This is most likely to affect the way you initialize the library to work with your database (see the install section below).

Another recent update is the change to int64 for primary keys. This matches the convention used in database/sql, and is more portable, but it may require some minor changes to existing code.

Install

The usual go get command will put it in your $GOPATH:

go get github.com/russross/meddler

If you are only using one type of database, you should set Default to match your database type, e.g.:

meddler.Default = meddler.PostgreSQL

The default database is MySQL, so you should change it for anything else. To use multiple databases within a single project, or to use a database other than MySQL, PostgreSQL, or SQLite, see below.

Note: If you are using MySQL with the github.com/go-sql-driver/mysql driver, you must set "parseTime=true" in the sql.Open call or the time conversion meddlers will not work.

Why?

These are the features that set meddler apart from similar libraries:

High-level functions

Meddler does not create or alter tables. It just provides a little glue to make it easier to read and write structs as SQL rows. Start by annotating a struct:

type Person struct {
    ID      int       `meddler:"id,pk"`
    Name    string    `meddler:"name"`
    Age     int
    salary  int
    Created time.Time `meddler:"created,localtime"`
    Closed  time.Time `meddler:",localtimez"`
}

Notes about this example:

Meddler provides a few high-level functions (note: DB is an interface that works with a *sql.DB or a *sql.Tx):

Note: all of these functions can also be used as methods on Database objects. When used as package functions, they use the Default Database object, which is MySQL unless you change it.

Meddlers

A meddler is a handler that gets to meddle with a field before it is saved, or when it is loaded. "localtime" and "localtimez" are examples of built-in meddlers. The full list of built-in meddlers includes:

You can implement custom meddlers as well by implementing the Meddler interface. See the existing implementations in medder.go for examples.

Working with different database types

Meddler can work with multiple database types simultaneously. Database-specific parameters are stored in a Database struct, and structs are pre-defined for MySQL, PostgreSQL, and SQLite.

Instead of relying on the package-level functions, use the method form on the appropriate database type, e.g.:

err = meddler.PostgreSQL.Load(...)

instead of

err = meddler.Load(...)

Or to save typing, define your own abbreviated name for each database:

ms := meddler.MySQL
pg := meddler.PostgreSQL
err = ms.Load(...)
err = pg.QueryAll(...)

If you need a different database, create your own Database instance with the appropriate parameters set. If everything works okay, please contact me with the parameters you used so I can add the new database to the pre-defined list.

Lower-level functions

If you are using more complex queries and just want to reduce the tedium of reading and writing values, there are some lower-level helper functions as well. See the package docs for details, and see the implementations of the higher-level functions to see how they are used.

License

Meddler is distributed under the BSD 2-Clause License. If this license prevents you from using Meddler in your project, please contact me and I will consider adding an additional license that is better suited to your needs.

Copyright © 2013 Russ Ross. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.