gokv / postgres

gokv/postgres

A reflectionless gokv/store PostgreSQL client.

This package is not ready for production use.

---

The aim of this package is to provide an idiomatic Go API to the SQL persistence. The data is accepted in a key/value format, where the value implements JSON marshaler/unmarshaler, and is persisted as JSONb.

A typical approach to database abstraction is the ORM (Object-Relational Mapper): a piece of software that maps your domain models to some SQL code. In this case, the actual mapping functions are defined by the consumer: the persisted types need to provide an explicit implementation of MarhalJSON and UnmarshalJSON.

Here is how the usage experience was designed:

// Instantiate a new PostgreSQL store
s, _ = postgres.New(db, "table_name")

// store defines the methods required in this function, or in this package.
type store interface {
  Set(ctx context.Context, id string, v json.Marshaler) error
}

// SaveNewBook accepts the postgres.Store as a locally-defined interface.
// Later on, another Store implementation could be passed instead, for example
// using Redis.
//
// The `book` type must explicitly implement `json.Marshaler`
func SaveNewBook(s store, newBook book) error {
  return s.Set(req.Context(), uuid.New(), newBook)
}

Requisites

• Go v1.8 (for context.Context integration in the stdlib)
• Postgres v9.5 (first version to provide upsert via the ON CONFLICT clause)

Use

The New initialisator prepares SQL statements against the given *sql.DB, and exposes methods that act upon those prepared statements.

Here's how to use it:

package main

import (
	"context"
	"database/sql"
	"encoding/json"
	"log"
	"time"

	"github.com/gokv/postgres"
	"github.com/google/uuid"
	_ "github.com/lib/pq"
)

// User is the type to persist
type User struct {
	Firstname string
	Lastname  string
	CreatedAt time.Time
}

// The type has to explicitly implement json.Marshaler
func (u User) MarshalJSON() ([]byte, error) {
	return json.Marshal(struct {
		Firstname string    `json:"firstname"`
		Lastname  string    `json:"lastname"`
		CreatedAt time.Time `json:"created_at"`
	}{
		Firstname: u.Firstname,
		Lastname:  u.Lastname,
		CreatedAt: u.CreatedAt,
	})
}

func main() {
	// Create the connection abstraction
	db, err := sql.Open("postgres", "host=postgres user=username password=secret dbname=store")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// Pass the *sql.DB and the name of the table the Store will be bound to.
	// WithCreateTable is the option for creating the table if it doesn't exist
	// already.
	s, err := postgres.New(db, "users", WithCreateTable)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()

	// Add a new entry
	id, err := s.Add(context.Context(), User{
		Firstname: "Giacomo",
		Lastname:  "Leopardi",
		CreatedAt: time.Now(),
	})
	if err != nil {
		log.Fatal(err)
	}

  fmt.Println("The new user's unique ID is %q", id)
}

Roadmap

• Basic CRUD
• Search