q

Documentation

Overview

Package q provides a simple way to interact with a DataBase and craft queryes using gaum through the Q struct and its helpers you can use most of gaum feature in a simple and intuitive way that somehow is reminiscent of some go ORMs. This package API might change overtime given that is being created from ux feedback from our users.

Index

• func NewDB(connectionString string, driver Driver, logger logging.Logger, ...) (connection.DB, error)
• func RawExec(db connection.DB, query string, args ...interface{}) error
• func RawQuery(db connection.DB, recipientSlice interface{}, query string, ...) error
• func RawQueryOne(db connection.DB, recipient interface{}, query string, args ...interface{}) error
• type Driver
• type Q
  • func New(connectionString string, driver Driver, logger logging.Logger, ...) (*Q, error)
  • func NewFromDB(dbConnection connection.DB) (*Q, error)
  • func (q *Q) AndWhere(expr string, args ...interface{}) *Q
  • func (q *Q) DB() connection.DB
  • func (q *Q) Delete() *Q
  • func (q *Q) Exec() error
  • func (q *Q) From(table string) *Q
  • func (q *Q) GroupBy(expr string) *Q
  • func (q *Q) InnerJoin(table string, on string, args ...interface{}) *Q
  • func (q *Q) Insert(insertPairs map[string]interface{}) *Q
  • func (q *Q) Join(table string, on string, args ...interface{}) *Q
  • func (q *Q) LeftJoin(table string, on string, args ...interface{}) *Q
  • func (q *Q) Limit(limit int64) *Q
  • func (q *Q) Offset(offset int64) *Q
  • func (q *Q) OnConflict(clause func(*c.OnConflict)) *Q
  • func (q *Q) OrWhere(expr string, args ...interface{}) *Q
  • func (q *Q) OrderBy(order *c.OrderByOperator) *Q
  • func (q *Q) QueryMany(receiverSlice interface{}) error
  • func (q *Q) QueryOne(receiver interface{}) error
  • func (q *Q) Returning(args ...string) *Q
  • func (q *Q) RightJoin(table string, on string, args ...interface{}) *Q
  • func (q *Q) Select(query string, args ...interface{}) *Q
  • func (q *Q) Update(exprMap map[string]interface{}) *Q

Functions

func NewDB

func NewDB(connectionString string, driver Driver,
	logger logging.Logger, logLevel connection.LogLevel) (connection.DB, error)

NewDB crafts a new `connection.DB` from the passed connection string, using the passed in <driver> and with the passed in <logger> and <logLevel> set. If you want more customization into your DB connection please refer to the documentation for `connection.DB` and `connection.Information` and the respective drivers:

* github.com/ShiftLeftSecurity/gaum/db/postgres

* github.com/ShiftLeftSecurity/gaum/db/postgrespq

func RawExec

func RawExec(db connection.DB, query string, args ...interface{}) error

RawExec runs the passed in <query> with the safely inserted <args> through <db>, no values are returned except for success/error.

func RawQuery

func RawQuery(db connection.DB, recipientSlice interface{}, query string, args ...interface{}) error

RawQuery runs the passed in <query> with the safely inserted <args> through <db> and fetches the values into <recipientSlice> that must be a slice of a type that supports de-serialization of all columns into it.

func RawQueryOne

func RawQueryOne(db connection.DB, recipient interface{}, query string, args ...interface{}) error

RawQueryOne runs the passed in <query> with the safely inserted <args> through <db> and fetches the first value into <recipient>.RawQueryOne <receiver> must be of a type that supports de-serialization of all columns into it.

Types

type Driver

type Driver int

Driver represent the possible db connection drivers.

const (
	// PGX is Jackc [pgx driver](github.com/jackc/pgx) (binary)
	PGX Driver = iota
	// PQ is Postgres default driver (text)
	PQ
)

type Q

type Q struct {
	// contains filtered or unexported fields
}

Q is the intended struct for interaction with SQL Queries.

func New

func New(connectionString string, driver Driver,
	logger logging.Logger, logLevel connection.LogLevel) (*Q, error)

New crafts a new Q query containing a db connection to the db specified by connectionString and the selected driver and logging settings.

func NewFromDB

func NewFromDB(dbConnection connection.DB) (*Q, error)

NewFromDB crafts a new Q query containing the passed db connection.

func (*Q) AndWhere

func (q *Q) AndWhere(expr string, args ...interface{}) *Q

AndWhere adds a `WHERE` condition section that can be:

* The first one (decided in arbitrary way among all `AndWhere` expressions)

* One of many that will be pre-pend by `AND` if it's not the first

* The only condition.

you might pass anything that is valid within a `WHERE` condition as expression, even a group of conditions separated by AND/OR in plain text. You can use `?` as a placeholder for values to be safely passed as variadic arguments after the expression.

func (*Q) DB

func (q *Q) DB() connection.DB

DB returns the `connection.DB` being used for this Q query execution.

func (*Q) Delete

func (q *Q) Delete() *Q

Delete converts the existing Q query into an `DELETE FROM ...` SQL statement, be very mindful when using this since it can easily create a WHERE-less DELETE if you forget to invoke proper `AndWhere`/`OrWhere` statement before executing it.

func (*Q) Exec

func (q *Q) Exec() error

Exec executes the query in Q not expecting nor returning any results other than success/error This works with any statement not returning values and potentially the ones returning values too but values are ignored (untested claim)

func (*Q) From

func (q *Q) From(table string) *Q

From sets the table or tables in which the SQL statement defined by the Q query will operate this method receives a free form string so you might as well pass a list of columns comma separated or actually anything that is valid input for a SQL `FROM` statement.

func (*Q) GroupBy

func (q *Q) GroupBy(expr string) *Q

GroupBy adds a grouping criteria to the Q query, you may pass any valid column that SQL accepts as an ordering criteria.

func (*Q) InnerJoin

func (q *Q) InnerJoin(table string, on string, args ...interface{}) *Q

InnerJoin adds a `INNER JOIN <table> ON <expression>` SQL statement to your Q query, the <on> argument can contain any valid SQL expression for the `ON` section of a JOIN you can use `?` as a placeholder for values to be safely passed as variadic arguments after the <on> argument

func (*Q) Insert

func (q *Q) Insert(insertPairs map[string]interface{}) *Q

Insert converts the existing Q query into an `INSERT INTO ...` SQL statement, the passed map comprises the fields, represented by the keys of the map and values, represented by the values of the map to be inserted, Order in which the pair will appear is not guaranteed given go's map implementation (of course key/value will always be in the possition corresponding with each other within the query)

func (*Q) Join

func (q *Q) Join(table string, on string, args ...interface{}) *Q

Join adds a `JOIN <table> ON <expression>` SQL statement to your Q query, the <on> argument can contain any valid SQL expression for the `ON` section of a JOIN you can use `?` as a placeholder for values to be safely passed as variadic arguments after the <on> argument

func (*Q) LeftJoin

func (q *Q) LeftJoin(table string, on string, args ...interface{}) *Q

LeftJoin adds a `LEFT JOIN <table> ON <expression>` SQL statement to your Q query, the <on> argument can contain any valid SQL expression for the `ON` section of a JOIN you can use `?` as a placeholder for values to be safely passed as variadic arguments after the <on> argument

func (*Q) Limit

func (q *Q) Limit(limit int64) *Q

Limit sets a result returning limit to the Q query, calling `Limit` multiple times overrides previous calls.

func (*Q) Offset

func (q *Q) Offset(offset int64) *Q

Offset sets a result returning offset to the Q query, calling `Offset` multiple times overrides previous calls

func (*Q) OnConflict

func (q *Q) OnConflict(clause func(*c.OnConflict)) *Q

OnConflict allows to set behavior for the RDBMS to act upon a conflict triggered, please go to `chain.OnConflict` doc for references on all possible options.

func (*Q) OrWhere

func (q *Q) OrWhere(expr string, args ...interface{}) *Q

OrWhere adds a `WHERE` condition section that can be:

* The first one if no `AndWhere` was invoked

* One of many that will be pre-pend by `OR` if it's not the first

* The only condition (although convention dictates that you use `AndWhere` in this case).

you might pass anything that is valid within a `WHERE` condition as expression, even a group of conditions separated by AND/OR in plain text. You can use `?` as a placeholder for values to be safely passed as variadic arguments after the expression.

func (*Q) OrderBy

func (q *Q) OrderBy(order *c.OrderByOperator) *Q

OrderBy adds an ordering criteria to the Q query, you can either create an ordering operator by chaining all fields in it or invoke multiple times OrderBy, please refer to the documentation of `chain.OrderByOperator`.

func (*Q) QueryMany

func (q *Q) QueryMany(receiverSlice interface{}) error

QueryMany executes and fetches all results from a query into <receiverSlice> which is expected to be a slice of a type that supports de-serialization of all columns into it.

This works with `SELECT` and `INSERT INTO ... RETURNING ...`

func (*Q) QueryOne

func (q *Q) QueryOne(receiver interface{}) error

QueryOne executes and fetches one row of the result into <receiver>, ideally use this in conjunction with `.Limit(1)` or in queries that are not expected to return more than one value since the underlying query Will be executed infull but just one result will be retrieved before dropping the result set.

<receiver> must be of a type that supports de-serialization of all columns into it. This works with `SELECT` and `INSERT INTO ... RETURNING ...`

func (*Q) Returning

func (q *Q) Returning(args ...string) *Q

Returning will add an "RETURNING" clause at the end of the query if the main operation is an INSERT, if you do this bear in mind that you will need to execute the Q query with `QueryOne` instead of `Exec`

func (*Q) RightJoin

func (q *Q) RightJoin(table string, on string, args ...interface{}) *Q

RightJoin adds a `RIGHT JOIN <table> ON <expression>` SQL statement to your Q query, the <on> argument can contain any valid SQL expression for the `ON` section of a JOIN you can use `?` as a placeholder for values to be safely passed as variadic arguments after the <on> argument

func (*Q) Select

func (q *Q) Select(query string, args ...interface{}) *Q

Select converts the existing Q query into a `SELECT ...` SQL statement, query is the actual body of the statement for example`column1, column2, expression, column4 AS alias` you can use `?` as a placeholder for values to be safely passed as variadic arguments after the expression

func (*Q) Update

func (q *Q) Update(exprMap map[string]interface{}) *Q

Update converts the existing Q query into an `UPDATE ...` SQL statement, the passed map will be used to set column names (from map keys) and new values (from map values) the order of the assignements within the query is not guaranteed given go's map implementation so even if the resulting query of multiple calls might differ in the `SET` section it will be equivalent.