sql

Documentation

Overview

SQL datasource and commands for Gococ. This provides basic SQL support for Gococ.

Index

• func Close(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)
• func Execute(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)
• func GetDb(cxt gococ.Context, dbname string) (*sql.DB, error)
• func NewDbDatasource(driverName, datasourceName string) (*dbsql.DB, error)
• func Ping(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)
• type StmtCache
  • func NewStmtCache(dbHandle *dbsql.DB, initialCapacity int) StmtCache
• type StmtCacheMap
  • func (c *StmtCacheMap) Clear() error
  • func (c *StmtCacheMap) Prepare(statement string) (*dbsql.Stmt, error)

Functions

func Close

func Close(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)

A command that can be used during a shutdown chain.

Params: - dbname (required): the name of the db datasource.

func Execute

func Execute(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)

This is a utility function for executing statements.

While we don't wrap all SQL statements, this particular command is here to facilitate creating databases. In other situations, it is assumed that the commands will handle SQL internally, and not use high-level commands to run each query.

Params: - "statement": The statement to execute (as a string) - "dbname": The name of the datasource that references the DB.

Returns: - database.sql.Result (core Go API)

Example:

req.Route("install", "Create DB").
	Does(sql.Execute, "exec").
	Using("dbname").WithDefault("db").
	Using("statement").WithDefault("CREATE TABLE IF NOT EXISTS names (id INT, varchar NAME)")

func GetDb

func GetDb(cxt gococ.Context, dbname string) (*sql.DB, error)

Utility function to get the database from a datasource.

func NewDbDatasource

func NewDbDatasource(driverName, datasourceName string) (*dbsql.DB, error)

NewDbDatasource creates a new SQL datasource.

Currently, this returns an actual *"database/sql".Db instance. Note that you do not *need* to use this function in order to create a new database datasource. You can simply place a database handle into the context as a datasource.

Example:

ds, err := sql.NewDatasource("mysql", "root@/mpbtest")
if err != nil {
	panic("Could not create a database connection.")
	return
}

cxt.AddDatasource("db", ds)

In the example above, we create a new datasource and then add it to the context. This should be done at server init, before web.Serve or router.HandleRequest().

func Ping

func Ping(cxt gococ.Context, params *gococ.Params) (interface{}, gococ.Interrupt)

Ping a database.

If the Ping fails, this will return an error.

Params - dbname: (required) the name of the database datasource.

Returns: - boolean flag set to true if the Ping was successful.

Types

type StmtCache

type StmtCache interface {
	Prepare(statement string) (*dbsql.Stmt, error)
	Clear() error
}

A StmtCache caches SQL prepared statements.

It's intended use is as a datsource for a long-running SQL-backed application. Prepared statements can exist across requests and be shared by separate goroutines. For frequently executed statements, this is both more performant and more secure (at least for some drivers).

IMPORTANT: Statments are cached by string key, so it is important that to get the most out of the cache, you re-use the same strings. Otherwise, 'SELECT surname, name FROM names' will generate a different cache entry than 'SELECT name, surname FROM names'.

The cache is driver-agnostic.

func NewStmtCache

func NewStmtCache(dbHandle *dbsql.DB, initialCapacity int) StmtCache

NewStmtCache creates a new cache for prepared statements.

Initial capacity determines how big the cache will be.

Warning: The implementation of the caching layer will likely change from relatively static to an LRU. To avoid memory leaks, the statement cache will automatically clear itself each time it hits 1000 distinct statements.

type StmtCacheMap

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

func (*StmtCacheMap) Clear

func (c *StmtCacheMap) Clear() error

Clear clears the cache.

Right now, it is suggested that the

func (*StmtCacheMap) Prepare

func (c *StmtCacheMap) Prepare(statement string) (*dbsql.Stmt, error)

Prepare gets a prepared statement from a SQL string.

This will return a cached statement if one exists, otherwise this will generate one, insert it into the cache, and return the new statement.

It is assumed that the underlying database layer can handle parallelism with prepared statements, and we make no effort to deal with locking or synchronization. For compatibility with database/sql.DB.Prepare