pop

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2023 License: MIT Imports: 48 Imported by: 0

README

GoDoc Build Status

POP

A Tasty Treat For All Your Database Needs

So what does Pop do exactly? Well, it wraps the absolutely amazing https://github.com/jmoiron/sqlx library. It cleans up some of the common patterns and work flows usually associated with dealing with databases in Go.

Pop makes it easy to do CRUD operations, run migrations, and build/execute queries.

Pop, by default, follows conventions that were influenced by the ActiveRecord Ruby gem. What does this mean?

  • Tables must have an "id" column and a corresponding "ID" field on the struct being used.
  • If there is a timestamp column named created_at, and a CreatedAt time.Time attribute on the struct, it will be set with the current time when the record is created.
  • If there is a timestamp column named updated_at, and a UpdatedAt time.Time attribute on the struct, it will be set with the current time when the record is updated.
  • Default database table names are lowercase, plural, and underscored versions of the struct name. Examples: User{} is "users", FooBar{} is "foo_bars", etc...

Want to know more? Take a look at the documentation!

Documentation

Please visit http://gobuffalo.io for the latest documentation, examples, and more.

Quick Start

Shoulders of Giants

Pop would not be possible if not for all of the great projects it depends on. Please see SHOULDERS.md to see a list of them.

Contributing

First, thank you so much for wanting to contribute! It means so much that you care enough to want to contribute. We appreciate every PR from the smallest of typos to the be biggest of features.

To contribute, please read the contribution guidelines: CONTRIBUTING

Documentation

Overview

Package pop wraps the absolutely amazing https://github.com/jmoiron/sqlx library. It cleans up some of the common patterns and workflows usually associated with dealing with databases in Go.

Pop makes it easy to do CRUD operations, run migrations, and build/execute queries. Is Pop an ORM? I'll leave that up to you, the reader, to decide.

Pop, by default, follows conventions that were defined by the ActiveRecord Ruby gem, http://www.rubyonrails.org. What does this mean?

* Tables must have an "id" column and a corresponding "ID" field on the `struct` being used. * If there is a timestamp column named "created_at", "CreatedAt" on the `struct`, it will be set with the current time when the record is created. * If there is a timestamp column named "updated_at", "UpdatedAt" on the `struct`, it will be set with the current time when the record is updated. * Default databases are lowercase, underscored versions of the `struct` name. Examples: User{} is "users", FooBar{} is "foo_bars", etc...

Index

Constants

View Source
const (
	Select operation = "SELECT"
	Delete operation = "DELETE"
)

Variables

View Source
var AvailableDialects []string

AvailableDialects lists the available database dialects

View Source
var Color = true

Color mode, to toggle colored logs

View Source
var ConfigName = "database.yml"

ConfigName is the name of the YAML databases config file

View Source
var Connections = map[string]*Connection{}

Connections contains all available connections

View Source
var Debug = false

Debug mode, to toggle verbose log traces

View Source
var ErrConfigFileNotFound = errors.New("unable to find pop config file")

ErrConfigFileNotFound is returned when the pop config file can't be found, after looking for it.

View Source
var PaginatorPageKey = "page"

PaginatorPageKey is the query parameter holding the current page index

View Source
var PaginatorPerPageDefault = 20

PaginatorPerPageDefault is the amount of results per page

View Source
var PaginatorPerPageKey = "per_page"

PaginatorPerPageKey is the query parameter holding the amount of results per page to override the default one

Functions

func AddLookupPaths

func AddLookupPaths(paths ...string) error

AddLookupPaths add paths to the current lookup paths list

func CanonicalDialect

func CanonicalDialect(synonym string) string

CanonicalDialect checks if the given synonym (could be a valid dialect too) is a registered synonym and returns the canonical dialect for the synonym. Otherwise, it returns the lowercase value of the given synonym.

Note that it does not check if the return value is a valid (supported) dialect so you need to check it with `DialectSupported()`.

func CreateDB

func CreateDB(c *Connection) error

CreateDB creates a database, given a connection definition

func CreateSchemaMigrations

func CreateSchemaMigrations(c *Connection) error

CreateSchemaMigrations sets up a table to track migrations. This is an idempotent operation.

func DialectSupported

func DialectSupported(d string) bool

DialectSupported checks support for the given database dialect

func DropDB

func DropDB(c *Connection) error

DropDB drops an existing database, given a connection definition

func IsZeroOfUnderlyingType

func IsZeroOfUnderlyingType(x interface{}) bool

IsZeroOfUnderlyingType will check if the value of anything is the equal to the Zero value of that type.

func LoadConfigFile

func LoadConfigFile() error

LoadConfigFile loads a POP config file from the configured lookup paths

func LoadFrom

func LoadFrom(r io.Reader) error

LoadFrom reads a configuration from the reader and sets up the connections

func LookupPaths

func LookupPaths() []string

LookupPaths returns the current configuration lookup paths

func MigrationContent

func MigrationContent(mf Migration, c *Connection, r io.Reader, usingTemplate bool) (string, error)

MigrationContent returns the content of a migration.

func ParseConfig

func ParseConfig(r io.Reader) (map[string]*ConnectionDetails, error)

ParseConfig reads the pop config from the given io.Reader and returns the parsed ConnectionDetails map.

func SetEagerMode

func SetEagerMode(eagerMode EagerMode)

SetEagerMode changes overall mode when eager loading. this will change the default loading associations strategy for all Eager queries. This will affect all queries when eager loading is used.

func SetLogger

func SetLogger(logger func(level logging.Level, s string, args ...interface{}))

SetLogger overrides the default logger.

func SetNowFunc

func SetNowFunc(f func() time.Time)

SetNowFunc allows an override of time.Now for customizing CreatedAt/UpdatedAt

func SetTxLogger

func SetTxLogger(logger func(level logging.Level, anon interface{}, s string, args ...interface{}))

SetLogger overrides the default logger.

Types

type AfterCreateable

type AfterCreateable interface {
	AfterCreate(*Connection) error
}

AfterCreateable callback will be called after a record is created in the database.

type AfterDestroyable

type AfterDestroyable interface {
	AfterDestroy(*Connection) error
}

AfterDestroyable callback will be called after a record is destroyed in the database.

type AfterEagerFindable

type AfterEagerFindable interface {
	AfterEagerFind(*Connection) error
}

AfterEagerFindable callback will be called after a record, or records, has been retrieved from the database and their associations have been eagerly loaded.

type AfterFindable

type AfterFindable interface {
	AfterFind(*Connection) error
}

AfterFindable callback will be called after a record, or records, has been retrieved from the database.

type AfterSaveable

type AfterSaveable interface {
	AfterSave(*Connection) error
}

AfterSaveable callback will be called after a record is either created or updated in the database.

type AfterUpdateable

type AfterUpdateable interface {
	AfterUpdate(*Connection) error
}

AfterUpdateable callback will be called after a record is updated in the database.

type AssociationMetaInfo

type AssociationMetaInfo struct {
	*reflectx.FieldInfo
	*reflectx.StructMap
}

AssociationMetaInfo a type to abstract all field information regarding to an association. An association is a field that has defined a tag like 'has_many', 'belongs_to', 'many_to_many' and 'has_one'.

func NewAssociationMetaInfo

func NewAssociationMetaInfo(fi *reflectx.FieldInfo) *AssociationMetaInfo

NewAssociationMetaInfo creates the meta info details for the passed association.

type BeforeCreateable

type BeforeCreateable interface {
	BeforeCreate(*Connection) error
}

BeforeCreateable callback will be called before a record is created in the database.

type BeforeDestroyable

type BeforeDestroyable interface {
	BeforeDestroy(*Connection) error
}

BeforeDestroyable callback will be called before a record is destroyed in the database.

type BeforeSaveable

type BeforeSaveable interface {
	BeforeSave(*Connection) error
}

BeforeSaveable callback will be called before a record is either created or updated in the database.

type BeforeUpdateable

type BeforeUpdateable interface {
	BeforeUpdate(*Connection) error
}

BeforeUpdateable callback will be called before a record is updated in the database.

type BeforeValidateable

type BeforeValidateable interface {
	BeforeValidate(*Connection) error
}

BeforeValidateable callback will be called before a record is validated during ValidateAndCreate, ValidateAndUpdate, or ValidateAndSave

type Connection

type Connection struct {
	ID      string
	Store   store
	Dialect dialect
	Elapsed int64
	TX      *Tx
	// contains filtered or unexported fields
}

Connection represents all necessary details to talk with a datastore

func Connect

func Connect(e string) (*Connection, error)

Connect takes the name of a connection, default is "development", and will return that connection from the available `Connections`. If a connection with that name can not be found an error will be returned. If a connection is found, and it has yet to open a connection with its underlying datastore, a connection to that store will be opened.

func NewConnection

func NewConnection(deets *ConnectionDetails) (*Connection, error)

NewConnection creates a new connection, and sets it's `Dialect` appropriately based on the `ConnectionDetails` passed into it.

func (*Connection) All

func (c *Connection) All(models interface{}) error

All retrieves all of the records in the database that match the query.

c.All(&[]User{})

func (*Connection) BelongsTo

func (c *Connection) BelongsTo(model interface{}) *Query

BelongsTo adds a "where" clause based on the "ID" of the "model" passed into it.

func (*Connection) BelongsToAs

func (c *Connection) BelongsToAs(model interface{}, as string) *Query

BelongsToAs adds a "where" clause based on the "ID" of the "model" passed into it using an alias.

func (*Connection) BelongsToThrough

func (c *Connection) BelongsToThrough(bt, thru interface{}) *Query

BelongsToThrough adds a "where" clause that connects the "bt" model through the associated "thru" model.

func (*Connection) Close

func (c *Connection) Close() error

Close destroys an active datasource connection

func (*Connection) Context

func (c *Connection) Context() context.Context

Context returns the connection's context set by "Context()" or context.TODO() if no context is set.

func (*Connection) Count

func (c *Connection) Count(model interface{}) (int, error)

Count the number of records in the database.

c.Count(&User{})

func (*Connection) Create

func (c *Connection) Create(model interface{}, excludeColumns ...string) error

Create add a new given entry to the database, excluding the given columns. It updates `created_at` and `updated_at` columns automatically.

If model is a slice, each item of the slice is created in the database.

Create support two modes: * Flat (default): Associate existing nested objects only. NO creation or update of nested objects. * Eager: Associate existing nested objects and create non-existent objects. NO change to existing objects.

func (*Connection) Destroy

func (c *Connection) Destroy(model interface{}) error

Destroy deletes a given entry from the database.

If model is a slice, each item of the slice is deleted from the database.

func (*Connection) Eager

func (c *Connection) Eager(fields ...string) *Connection

Eager will enable associations loading of the model. by defaults loads all the associations on the model, but can take a variadic list of associations to load.

c.Eager().Find(model, 1) // will load all associations for model.
c.Eager("Books").Find(model, 1) // will load only Book association for model.

Eager also enable nested models creation:

model := Parent{Child: Child{}, Parent: &Parent{}}
c.Eager().Create(&model) // will create all associations for model.
c.Eager("Child").Create(&model) // will only create the Child association for model.

func (*Connection) EagerPreload

func (c *Connection) EagerPreload(fields ...string) *Query

Preload activates preload eager Mode automatically.

func (*Connection) Find

func (c *Connection) Find(model interface{}, id interface{}) error

Find the first record of the model in the database with a particular id.

c.Find(&User{}, 1)

func (*Connection) First

func (c *Connection) First(model interface{}) error

First record of the model in the database that matches the query.

c.First(&User{})

func (*Connection) Last

func (c *Connection) Last(model interface{}) error

Last record of the model in the database that matches the query.

c.Last(&User{})

func (*Connection) Limit

func (c *Connection) Limit(limit int) *Query

Limit will create a query and add a limit clause to it.

c.Limit(10)

func (*Connection) Load

func (c *Connection) Load(model interface{}, fields ...string) error

Load loads all association or the fields specified in params for an already loaded model.

tx.First(&u) tx.Load(&u)

func (*Connection) MigrationTableName

func (c *Connection) MigrationTableName() string

MigrationTableName returns the name of the table to track migrations

func (*Connection) MigrationURL

func (c *Connection) MigrationURL() string

MigrationURL returns the datasource connection string used for running the migrations

func (*Connection) NewTransaction

func (c *Connection) NewTransaction() (*Connection, error)

NewTransaction starts a new transaction on the connection

func (*Connection) NewTransactionContext

func (c *Connection) NewTransactionContext(ctx context.Context) (*Connection, error)

NewTransactionContext starts a new transaction on the connection using the provided context

func (*Connection) NewTransactionContextOptions

func (c *Connection) NewTransactionContextOptions(ctx context.Context, options *sql.TxOptions) (*Connection, error)

NewTransactionContextOptions starts a new transaction on the connection using the provided context and transaction options

func (*Connection) Open

func (c *Connection) Open() error

Open creates a new datasource connection

func (*Connection) Order

func (c *Connection) Order(stmt string, args ...interface{}) *Query

Order will append an order clause to the query.

c.Order("name desc")

func (*Connection) Paginate

func (c *Connection) Paginate(page int, perPage int) *Query

Paginate records returned from the database.

q := c.Paginate(2, 15)
q.All(&[]User{})
q.Paginator

func (*Connection) PaginateFromParams

func (c *Connection) PaginateFromParams(params PaginationParams) *Query

PaginateFromParams paginates records returned from the database.

q := c.PaginateFromParams(req.URL.Query())
q.All(&[]User{})
q.Paginator

func (*Connection) Q

func (c *Connection) Q() *Query

Q creates a new "empty" query for the current connection.

func (*Connection) RawQuery

func (c *Connection) RawQuery(stmt string, args ...interface{}) *Query

RawQuery will override the query building feature of Pop and will use whatever query you want to execute against the `Connection`. You can continue to use the `?` argument syntax.

c.RawQuery("select * from foo where id = ?", 1)

func (*Connection) Reload

func (c *Connection) Reload(model interface{}) error

Reload fetch fresh data for a given model, using its ID.

func (*Connection) Rollback

func (c *Connection) Rollback(fn func(tx *Connection)) error

Rollback will open a new transaction and automatically rollback that transaction when the inner function returns, regardless. This can be useful for tests, etc...

func (*Connection) Save

func (c *Connection) Save(model interface{}, excludeColumns ...string) error

Save wraps the Create and Update methods. It executes a Create if no ID is provided with the entry; or issues an Update otherwise.

If model is a slice, each item of the slice is saved in the database.

func (*Connection) Scope

func (c *Connection) Scope(sf ScopeFunc) *Query

Scope the query by using a `ScopeFunc`

func ByName(name string) ScopeFunc {
	return func(q *Query) *Query {
		return q.Where("name = ?", name)
	}
}

func WithDeleted(q *pop.Query) *pop.Query {
	return q.Where("deleted_at is null")
}

c.Scope(ByName("mark)).Scope(WithDeleted).First(&User{})

func (*Connection) Select

func (c *Connection) Select(fields ...string) *Query

Select allows to query only fields passed as parameter. c.Select("field1", "field2").All(&model) => SELECT field1, field2 FROM models

func (*Connection) String

func (c *Connection) String() string

func (*Connection) Transaction

func (c *Connection) Transaction(fn func(tx *Connection) error) error

Transaction will start a new transaction on the connection. If the inner function returns an error then the transaction will be rolled back, otherwise the transaction will automatically commit at the end.

func (*Connection) TruncateAll

func (c *Connection) TruncateAll() error

TruncateAll truncates all data from the datasource

func (*Connection) URL

func (c *Connection) URL() string

URL returns the datasource connection string

func (*Connection) Update

func (c *Connection) Update(model interface{}, excludeColumns ...string) error

Update writes changes from an entry to the database, excluding the given columns. It updates the `updated_at` column automatically.

If model is a slice, each item of the slice is updated in the database.

func (*Connection) UpdateColumns

func (c *Connection) UpdateColumns(model interface{}, columnNames ...string) error

UpdateColumns writes changes from an entry to the database, including only the given columns or all columns if no column names are provided. It updates the `updated_at` column automatically if you include `updated_at` in columnNames.

If model is a slice, each item of the slice is updated in the database.

func (*Connection) ValidateAndCreate

func (c *Connection) ValidateAndCreate(model interface{}, excludeColumns ...string) (*validate.Errors, error)

ValidateAndCreate applies validation rules on the given entry, then creates it if the validation succeed, excluding the given columns.

If model is a slice, each item of the slice is validated then created in the database.

func (*Connection) ValidateAndSave

func (c *Connection) ValidateAndSave(model interface{}, excludeColumns ...string) (*validate.Errors, error)

ValidateAndSave applies validation rules on the given entry, then save it if the validation succeed, excluding the given columns.

If model is a slice, each item of the slice is validated then saved in the database.

func (*Connection) ValidateAndUpdate

func (c *Connection) ValidateAndUpdate(model interface{}, excludeColumns ...string) (*validate.Errors, error)

ValidateAndUpdate applies validation rules on the given entry, then update it if the validation succeed, excluding the given columns.

If model is a slice, each item of the slice is validated then updated in the database.

func (*Connection) Where

func (c *Connection) Where(stmt string, args ...interface{}) *Query

Where will append a where clause to the query. You may use `?` in place of arguments.

c.Where("id = ?", 1)
q.Where("id in (?)", 1, 2, 3)

func (*Connection) WithContext

func (c *Connection) WithContext(ctx context.Context) *Connection

WithContext returns a copy of the connection, wrapped with a context.

type ConnectionDetails

type ConnectionDetails struct {
	// Dialect is the pop dialect to use. Example: "postgres" or "sqlite3" or "mysql"
	Dialect string
	// Driver specifies the database driver to use (optional)
	Driver string
	// The name of your database. Example: "foo_development"
	Database string
	// The host of your database. Example: "127.0.0.1"
	Host string
	// The port of your database. Example: 1234
	// Will default to the "default" port for each dialect.
	Port string
	// The username of the database user. Example: "root"
	User string
	// The password of the database user. Example: "password"
	Password string
	// The encoding to use to create the database and communicate with it.
	Encoding string
	// Instead of specifying each individual piece of the
	// connection you can instead just specify the URL of the
	// database. Example: "postgres://postgres:postgres@localhost:5432/pop_test?sslmode=disable"
	URL string
	// Defaults to 0 "unlimited". See https://golang.org/pkg/database/sql/#DB.SetMaxOpenConns
	Pool int
	// Defaults to 2. See https://golang.org/pkg/database/sql/#DB.SetMaxIdleConns
	IdlePool int
	// Defaults to 0 "unlimited". See https://golang.org/pkg/database/sql/#DB.SetConnMaxLifetime
	ConnMaxLifetime time.Duration
	// Defaults to 0 "unlimited". See https://golang.org/pkg/database/sql/#DB.SetConnMaxIdleTime
	ConnMaxIdleTime time.Duration
	// Defaults to `false`. See https://godoc.org/github.com/jmoiron/sqlx#DB.Unsafe
	Unsafe bool
	// Options stores Connection Details options
	Options map[string]string

	// Query string encoded options from URL. Example: "sslmode=disable"
	RawOptions string
	// UseInstrumentedDriver if set to true uses a wrapper for the underlying driver which exposes tracing
	// information in the Open Tracing, Open Census, Google, and AWS Xray format. This is useful when using
	// tracing with Jaeger, DataDog, Zipkin, or other tracing software.
	UseInstrumentedDriver bool
	// InstrumentedDriverOptions sets the options for the instrumented driver. These options are empty by default meaning
	// that instrumentation is disabled.
	//
	// For more information check out the docs at https://github.com/luna-duclos/instrumentedsql. If you use Open Tracing, these options
	// could looks as follows:
	//
	//		InstrumentedDriverOptions: []instrumentedsql.Opt{instrumentedsql.WithTracer(opentracing.NewTracer(true))}
	//
	// It is also recommended to include `instrumentedsql.WithOmitArgs()` which prevents SQL arguments (e.g. passwords)
	// from being traced or logged.
	InstrumentedDriverOptions []instrumentedsql.Opt
	// contains filtered or unexported fields
}

ConnectionDetails stores the data needed to connect to a datasource

func (*ConnectionDetails) Finalize

func (cd *ConnectionDetails) Finalize() error

Finalize cleans up the connection details by normalizing names, filling in default values, etc...

func (*ConnectionDetails) MigrationTableName

func (cd *ConnectionDetails) MigrationTableName() string

MigrationTableName returns the name of the table to track migrations

func (*ConnectionDetails) OptionsString

func (cd *ConnectionDetails) OptionsString(s string) string

OptionsString returns URL parameter encoded string from options.

func (*ConnectionDetails) RetryLimit

func (cd *ConnectionDetails) RetryLimit() int

RetryLimit returns the maximum number of accepted connection retries

func (*ConnectionDetails) RetrySleep

func (cd *ConnectionDetails) RetrySleep() time.Duration

RetrySleep returns the amount of time to wait between two connection retries

type DownMigrations

type DownMigrations struct {
	Migrations
}

func (DownMigrations) Less

func (mfs DownMigrations) Less(i, j int) bool

type EagerMode

type EagerMode uint8

EagerMode type for all eager modes supported in pop.

const (

	// EagerDefault is the current implementation, the default
	// behavior of pop. This one introduce N+1 problem and will be used as
	// default value for backward compatibility.
	EagerDefault EagerMode

	// EagerPreload mode works similar to Preload mode used in Rails ActiveRecord.
	// Avoid N+1 problem by reducing the number of hits to the database but
	// increase memory use to process and link associations to parent.
	EagerPreload

	// EagerInclude This mode works similar to Include mode used in rails ActiveRecord.
	// Use Left Join clauses to load associations. Not working yet.
	EagerInclude
)

type FileMigrator

type FileMigrator struct {
	Migrator
	Path string
}

FileMigrator is a migrator for SQL and Fizz files on disk at a specified path.

func NewFileMigrator

func NewFileMigrator(path string, c *Connection) (FileMigrator, error)

NewFileMigrator for a path and a Connection

type GroupClause

type GroupClause struct {
	Field string
}

GroupClause holds the field to apply the GROUP clause on

func (GroupClause) String

func (c GroupClause) String() string

type HavingClause

type HavingClause struct {
	Condition string
	Arguments []interface{}
}

HavingClause defines a condition and its arguments for a HAVING clause

func (HavingClause) String

func (c HavingClause) String() string

type Match

type Match struct {
	Version   string
	Name      string
	DBType    string
	Direction string
	Type      string
}

Match holds the information parsed from a migration filename.

func ParseMigrationFilename

func ParseMigrationFilename(filename string) (*Match, error)

ParseMigrationFilename parses a migration filename.

type Migration

type Migration struct {
	// Path to the migration (./migrations/123_create_widgets.up.sql)
	Path string
	// Version of the migration (123)
	Version string
	// Name of the migration (create_widgets)
	Name string
	// Direction of the migration (up)
	Direction string
	// Type of migration (sql)
	Type string
	// DB type (all|postgres|mysql...)
	DBType string
	// Runner function to run/execute the migration
	Runner func(Migration, *Connection) error
}

Migration handles the data for a given database migration

func (Migration) Run

func (mf Migration) Run(c *Connection) error

Run the migration. Returns an error if there is no mf.Runner defined.

type MigrationBox

type MigrationBox struct {
	Migrator
	FS fs.FS
}

MigrationBox is a wrapper around fs.FS and Migrator. This will allow you to run migrations from a fs.FS inside of a compiled binary.

func NewMigrationBox

func NewMigrationBox(fsys fs.FS, c *Connection) (MigrationBox, error)

NewMigrationBox from a fs.FS and a Connection.

type Migrations

type Migrations []Migration

Migrations is a collection of Migration

func (*Migrations) Filter

func (mfs *Migrations) Filter(f func(mf Migration) bool)

func (Migrations) Len

func (mfs Migrations) Len() int

func (Migrations) Swap

func (mfs Migrations) Swap(i, j int)

type Migrator

type Migrator struct {
	Connection     *Connection
	SchemaPath     string
	UpMigrations   UpMigrations
	DownMigrations DownMigrations
}

Migrator forms the basis of all migrations systems. It does the actual heavy lifting of running migrations. When building a new migration system, you should embed this type into your migrator.

func NewMigrator

func NewMigrator(c *Connection) Migrator

NewMigrator returns a new "blank" migrator. It is recommended to use something like MigrationBox or FileMigrator. A "blank" Migrator should only be used as the basis for a new type of migration system.

func (Migrator) CreateSchemaMigrations

func (m Migrator) CreateSchemaMigrations() error

CreateSchemaMigrations sets up a table to track migrations. This is an idempotent operation.

func (Migrator) Down

func (m Migrator) Down(step int) error

Down runs pending "down" migrations and rolls back the database by the specified number of steps.

func (Migrator) DumpMigrationSchema

func (m Migrator) DumpMigrationSchema() error

DumpMigrationSchema will generate a file of the current database schema based on the value of Migrator.SchemaPath

func (Migrator) Reset

func (m Migrator) Reset() error

Reset the database by running the down migrations followed by the up migrations.

func (Migrator) Status

func (m Migrator) Status(out io.Writer) error

Status prints out the status of applied/pending migrations.

func (Migrator) Up

func (m Migrator) Up() error

Up runs pending "up" migrations and applies them to the database.

func (Migrator) UpLogOnly

func (m Migrator) UpLogOnly() error

UpLogOnly insert pending "up" migrations logs only, without applying the patch. It's used when loading the schema dump, instead of the migrations.

func (Migrator) UpTo

func (m Migrator) UpTo(step int) (applied int, err error)

UpTo runs up to step "up" migrations and applies them to the database. If step <= 0 all pending migrations are run.

type Model

type Model struct {
	Value

	As string
	// contains filtered or unexported fields
}

Model is used throughout Pop to wrap the end user interface that is passed in to many functions.

func NewModel

func NewModel(v Value, ctx context.Context) *Model

NewModel returns a new model with the specified value and context.

func (*Model) Alias

func (m *Model) Alias() string

func (*Model) Columns

func (m *Model) Columns() columns.Columns

func (*Model) ID

func (m *Model) ID() interface{}

ID returns the ID of the Model. All models must have an `ID` field this is of type `int`,`int64` or of type `uuid.UUID`.

func (*Model) IDField

func (m *Model) IDField() string

IDField returns the name of the DB field used for the ID. By default, it will return "id".

func (*Model) PrimaryKeyType

func (m *Model) PrimaryKeyType() (string, error)

PrimaryKeyType gives the primary key type of the `Model`.

func (*Model) TableName

func (m *Model) TableName() string

TableName returns the corresponding name of the underlying database table for a given `Model`. See also `TableNameAble` to change the default name of the table.

func (*Model) WhereID

func (m *Model) WhereID() string

func (*Model) WhereNamedID

func (m *Model) WhereNamedID() string

type ModelMetaInfo

type ModelMetaInfo struct {
	*reflectx.StructMap
	Model *Model
	// contains filtered or unexported fields
}

ModelMetaInfo a type to abstract all fields information regarding to a model. A model is representation of a table in the database.

func NewModelMetaInfo

func NewModelMetaInfo(model *Model) *ModelMetaInfo

NewModelMetaInfo creates the meta info details for the model passed as a parameter.

type PaginationParams

type PaginationParams interface {
	Get(key string) string
}

PaginationParams is a parameters provider interface to get the pagination params from

type Paginator

type Paginator struct {
	// Current page you're on
	Page int `json:"page"`
	// Number of results you want per page
	PerPage int `json:"per_page"`
	// Page * PerPage (ex: 2 * 20, Offset == 40)
	Offset int `json:"offset"`
	// Total potential records matching the query
	TotalEntriesSize int `json:"total_entries_size"`
	// Total records returns, will be <= PerPage
	CurrentEntriesSize int `json:"current_entries_size"`
	// Total pages
	TotalPages int `json:"total_pages"`
}

Paginator is a type used to represent the pagination of records from the database.

func NewPaginator

func NewPaginator(page int, perPage int) *Paginator

NewPaginator returns a new `Paginator` value with the appropriate defaults set.

func NewPaginatorFromParams

func NewPaginatorFromParams(params PaginationParams) *Paginator

NewPaginatorFromParams takes an interface of type `PaginationParams`, the `url.Values` type works great with this interface, and returns a new `Paginator` based on the params or `PaginatorPageKey` and `PaginatorPerPageKey`. Defaults are `1` for the page and PaginatorPerPageDefault for the per page value.

func (Paginator) Paginate

func (p Paginator) Paginate() string

Paginate implements the paginable interface.

func (Paginator) String

func (p Paginator) String() string

type Query

type Query struct {
	RawSQL *clause

	Paginator  *Paginator
	Connection *Connection
	Operation  operation
	// contains filtered or unexported fields
}

Query is the main value that is used to build up a query to be executed against the `Connection`.

func Q

func Q(c *Connection) *Query

Q will create a new "empty" query from the current connection.

func (*Query) All

func (q *Query) All(models interface{}) error

All retrieves all of the records in the database that match the query.

q.Where("name = ?", "mark").All(&[]User{})

func (*Query) BelongsTo

func (q *Query) BelongsTo(model interface{}) *Query

BelongsTo adds a "where" clause based on the "ID" of the "model" passed into it.

func (*Query) BelongsToAs

func (q *Query) BelongsToAs(model interface{}, as string) *Query

BelongsToAs adds a "where" clause based on the "ID" of the "model" passed into it, using an alias.

func (*Query) BelongsToThrough

func (q *Query) BelongsToThrough(bt, thru interface{}) *Query

BelongsToThrough adds a "where" clause that connects the "bt" model through the associated "thru" model.

func (*Query) Clone

func (q *Query) Clone(targetQ *Query)

Clone will fill targetQ query with the connection used in q, if targetQ is not empty, Clone will override all the fields.

func (Query) Count

func (q Query) Count(model interface{}) (int, error)

Count the number of records in the database.

q.Where("name = ?", "mark").Count(&User{})

func (Query) CountByField

func (q Query) CountByField(model interface{}, field string) (int, error)

CountByField counts the number of records in the database, for a given field.

q.Where("sex = ?", "f").Count(&User{}, "name")

func (*Query) Delete

func (q *Query) Delete(model interface{}) error

func (*Query) Eager

func (q *Query) Eager(fields ...string) *Query

Eager will enable load associations of the model. by defaults loads all the associations on the model, but can take a variadic list of associations to load.

q.Eager().Find(model, 1) // will load all associations for model.
q.Eager("Books").Find(model, 1) // will load only Book association for model.

func (*Query) EagerPreload

func (q *Query) EagerPreload(fields ...string) *Query

Preload activates preload eager Mode automatically.

func (*Query) Exec

func (q *Query) Exec() error

Exec runs the given query.

func (*Query) ExecWithCount

func (q *Query) ExecWithCount() (int, error)

ExecWithCount runs the given query, and returns the amount of affected rows.

func (*Query) Exists

func (q *Query) Exists(model interface{}) (bool, error)

Exists returns true/false if a record exists in the database that matches the query.

q.Where("name = ?", "mark").Exists(&User{})

func (*Query) Find

func (q *Query) Find(model interface{}, id interface{}) error

Find the first record of the model in the database with a particular id.

q.Find(&User{}, 1)

func (*Query) First

func (q *Query) First(model interface{}) error

First record of the model in the database that matches the query.

q.Where("name = ?", "mark").First(&User{})

func (*Query) GroupBy

func (q *Query) GroupBy(field string, fields ...string) *Query

GroupBy will append a GROUP BY clause to the query

func (*Query) Having

func (q *Query) Having(condition string, args ...interface{}) *Query

Having will append a HAVING clause to the query

func (*Query) InnerJoin

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

InnerJoin will append an INNER JOIN clause to the query

func (*Query) Join

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

Join will append a JOIN clause to the query

func (*Query) Last

func (q *Query) Last(model interface{}) error

Last record of the model in the database that matches the query.

q.Where("name = ?", "mark").Last(&User{})

func (*Query) LeftJoin

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

LeftJoin will append a LEFT JOIN clause to the query

func (*Query) LeftOuterJoin

func (q *Query) LeftOuterJoin(table string, on string, args ...interface{}) *Query

LeftOuterJoin will append a LEFT OUTER JOIN clause to the query

func (*Query) Limit

func (q *Query) Limit(limit int) *Query

Limit will add a limit clause to the query.

q.Limit(10)

func (*Query) Order

func (q *Query) Order(stmt string, args ...interface{}) *Query

Order will append an order clause to the query.

q.Order("name desc")

func (*Query) Paginate

func (q *Query) Paginate(page int, perPage int) *Query

Paginate records returned from the database.

q = q.Paginate(2, 15)
q.All(&[]User{})
q.Paginator

func (*Query) PaginateFromParams

func (q *Query) PaginateFromParams(params PaginationParams) *Query

PaginateFromParams paginates records returned from the database.

q = q.PaginateFromParams(req.URL.Query())
q.All(&[]User{})
q.Paginator

func (*Query) RawQuery

func (q *Query) RawQuery(stmt string, args ...interface{}) *Query

RawQuery will override the query building feature of Pop and will use whatever query you want to execute against the `Connection`. You can continue to use the `?` argument syntax.

q.RawQuery("select * from foo where id = ?", 1)

func (*Query) RightJoin

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

RightJoin will append a RIGHT JOIN clause to the query

func (*Query) RightOuterJoin

func (q *Query) RightOuterJoin(table string, on string, args ...interface{}) *Query

RightOuterJoin will append a RIGHT OUTER JOIN clause to the query

func (*Query) Scope

func (q *Query) Scope(sf ScopeFunc) *Query

Scope the query by using a `ScopeFunc`

func ByName(name string) ScopeFunc {
	return func(q *Query) *Query {
		return q.Where("name = ?", name)
	}
}

func WithDeleted(q *pop.Query) *pop.Query {
	return q.Where("deleted_at is null")
}

c.Scope(ByName("mark)).Scope(WithDeleted).First(&User{})

func (*Query) Select

func (q *Query) Select(fields ...string) *Query

Select allows to query only fields passed as parameter. c.Select("field1", "field2").All(&model) => SELECT field1, field2 FROM models

func (Query) ToSQL

func (q Query) ToSQL(model *Model, addColumns ...string) (string, []interface{})

ToSQL will generate SQL and the appropriate arguments for that SQL from the `Model` passed in.

func (*Query) UpdateQuery

func (q *Query) UpdateQuery(model interface{}, columnNames ...string) (int64, error)

UpdateQuery updates all rows matched by the query. The new values are read from the first argument, which must be a struct. The column names to be updated must be listed explicitly in subsequent arguments. The ID and CreatedAt columns are never updated. The UpdatedAt column is updated automatically.

UpdateQuery does not execute (before|after)(Create|Update|Save) callbacks.

Calling UpdateQuery with no columnNames will result in only the UpdatedAt column being updated.

func (*Query) Where

func (q *Query) Where(stmt string, args ...interface{}) *Query

Where will append a where clause to the query. You may use `?` in place of arguments.

q.Where("id = ?", 1)
q.Where("id in (?)", 1, 2, 3)

type ScopeFunc

type ScopeFunc func(q *Query) *Query

ScopeFunc applies a custom operation on a given `Query`

type TableNameAble

type TableNameAble interface {
	TableName() string
}

TableNameAble interface allows for the customize table mapping between a name and the database. For example the value `User{}` will automatically map to "users". Implementing `TableNameAble` would allow this to change to be changed to whatever you would like.

type TableNameAbleWithContext

type TableNameAbleWithContext interface {
	TableName(ctx context.Context) string
}

TableNameAbleWithContext is equal to TableNameAble but will be passed the queries' context. Useful in cases where the table name depends on e.g.

type Tx

type Tx struct {
	ID int
	*sqlx.Tx
}

Tx stores a transaction with an ID to keep track.

func (*Tx) Close

func (tx *Tx) Close() error

Close does nothing. This is defined so it implements the `Store` interface.

func (*Tx) NamedQueryContext

func (tx *Tx) NamedQueryContext(ctx context.Context, query string, arg interface{}) (*sqlx.Rows, error)

Workaround for https://github.com/jmoiron/sqlx/issues/447

func (*Tx) Transaction

func (tx *Tx) Transaction() (*Tx, error)

Transaction simply returns the current transaction, this is defined so it implements the `Store` interface.

func (*Tx) TransactionContext

func (tx *Tx) TransactionContext(ctx context.Context) (*Tx, error)

TransactionContext simply returns the current transaction, this is defined so it implements the `Store` interface.

func (*Tx) TransactionContextOptions

func (tx *Tx) TransactionContextOptions(_ context.Context, _ *sql.TxOptions) (*Tx, error)

TransactionContextOptions simply returns the current transaction, this is defined so it implements the `Store` interface.

type UpMigrations

type UpMigrations struct {
	Migrations
}

func (UpMigrations) Less

func (mfs UpMigrations) Less(i, j int) bool

type Value

type Value interface{}

Value is the contents of a `Model`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL