Documentation ¶
Overview ¶
Package kin implements a delcarative query manager for PostgreSQL.
Overview ¶
Kin is an opinionated, PostgeSQL-specific query driver that places an emphasis on writing SQL and explicit mappings to query tables. Instead of relying on reflection or other conventions, it gives users the control to write their own SQL queries, uses simple patterns that focus on control.
This means that kin probably isn't for everyone! It's certainly not a full-featured ORM in the mold of Gorm or Ruby's ActiveRecord. Instead, Kin smoothes out the rough edges and gives better error handling to SQL packages already built into Go.
Finally, support for running migrations is built in.
Getting Started ¶
Installing kin is as simple as running:
go get github.com/jmataya/kin
Next, define your models, connect to the query, and you're off to the races!
package main import ( "fmt" "time" "github.com/jmataya/kin" ) // user is a representation of a table called "users" with columns // id (int), name (text), attributes (jsonb), is_active (bool), and // created_at (timestamp). type user struct { ID int Name string Attributes map[string]interface{} IsActive bool CreatedAt time.Time } // Columns defines the mapping between query columns, their type, // and the model. It's used internally by kin to wire everything up. func (u *user) Columns() []FieldBuilder { return []FieldBuilder{ IntField("id", &u.ID), StringField("name", &u.Name), JSONField("attributes", &u.Attributes), BoolField("is_active", &u.IsActive), TimeField("created_at", &u.CreatedAt), } } func main() { // Connect with a raw Postges URL. dbStr := "postgresql://localhost:5432/kin_test?user=kin" db, _ := kin.NewConnection(dbStr) defer db.Close() // For most operations, Kin leverages SQL. queryStr := "SELECT * FROM users WHERE id = $1" id := 1 // Output a single result into the user struct defined above. u := new(user) err := db.Statement(queryStr, id).OneAndExtract(u) if err != nil { panic(err) } // Print the result. fmt.Printf("User: %+v\n", u) }
Index ¶
- type BuildFn
- type DatabaseConnection
- type Migrator
- type Model
- type Query
- type Result
- type RowResult
- func (rr *RowResult) Err() error
- func (rr *RowResult) ExtractBool(column string) bool
- func (rr *RowResult) ExtractDecimal(column string) float64
- func (rr *RowResult) ExtractInt(column string) int
- func (rr *RowResult) ExtractJSON(column string, out interface{})
- func (rr *RowResult) ExtractString(column string) string
- func (rr *RowResult) ExtractTime(column string) time.Time
- type Statement
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator is a structure used for running query migrations.
func NewMigrator ¶
NewMigrator creates a new Migrator around an existing DB connection.
func NewMigratorConnection ¶
NewMigratorConnection initialized a DB connection and uses it to power migrations.
type Model ¶
type Model interface { // TableName returns the name of the table that this model maps to. TableName() string }
Model is a data structure that can be used to construct a query insert or update.
type Query ¶
type Query[T Model] interface { // Get runs a select and returns all results. Get(table string) ([]*T, error) // Insert adds a record and returns the result. Insert(model T) (*T, error) // Raw generates a new statement to be executed at a later time. Raw(stmt string, params ...interface{}) *Statement[T] }
Query is an interface for generating query queries. It supports a few common and simple querying operations and then allows the user to solve more complex problems using SQL.
func NewQuery ¶
func NewQuery[T Model](db DatabaseConnection) Query[T]
NewQuery creates a new wrapper around an existing DB connection.
type RowResult ¶
type RowResult struct { Columns []string Data map[string]interface{} // contains filtered or unexported fields }
RowResult contains the results of a single row in a query result set.
func (*RowResult) ExtractBool ¶
ExtractBool gets the value in the dataset and returns a boolean. If the value can't be extracted, it stores an error on the result and prevents further extraction from occurring.
func (*RowResult) ExtractDecimal ¶
ExtractDecimal gets the value in the dataset and returns an integer. If the value can't be extracted, it stores an error on the result and prevents further extraction from occurring.
func (*RowResult) ExtractInt ¶
ExtractInt gets the value in the dataset and returns an integer. If the value can't be extracted, it stores an error on the result and prevents further extraction from occurring.
func (*RowResult) ExtractJSON ¶
ExtractJSON gets a JSON value from the dataset and unmarshals it into an interface passed by the caller.
func (*RowResult) ExtractString ¶
ExtractString gets the value in the dataset and returns a string. If the value can't be extracted, it stores an error on the result and prevents further extraction from occurring.