Categorygithub.com/gobuffalo/pop/v6
modulepackage
6.1.1
Repository: https://github.com/gobuffalo/pop.git
Documentation: pkg.go.dev
Versions
4
Dependencies
48
Dependents
147
Files
5.4k SLOC

# 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

# Packages

# Functions

AddLookupPaths add paths to the current lookup paths list.
CanonicalDialect checks if the given synonym (could be a valid dialect too) is a registered synonym and returns the canonical dialect for the synonym.
Connect takes the name of a connection, default is "development", and will return that connection from the available `Connections`.
CreateDB creates a database, given a connection definition.
CreateSchemaMigrations sets up a table to track migrations.
DialectSupported checks support for the given database dialect.
DropDB drops an existing database, given a connection definition.
IsZeroOfUnderlyingType will check if the value of anything is the equal to the Zero value of that type.
LoadConfigFile loads a POP config file from the configured lookup paths.
LoadFrom reads a configuration from the reader and sets up the connections.
LookupPaths returns the current configuration lookup paths.
MigrationContent returns the content of a migration.
NewAssociationMetaInfo creates the meta info details for the passed association.
NewConnection creates a new connection, and sets it's `Dialect` appropriately based on the `ConnectionDetails` passed into it.
NewFileMigrator for a path and a Connection.
NewMigrationBox from a fs.FS and a Connection.
NewMigrator returns a new "blank" migrator.
NewModel returns a new model with the specified value and context.
NewModelMetaInfo creates the meta info details for the model passed as a parameter.
NewPaginator returns a new `Paginator` value with the appropriate defaults set.
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`.
ParseConfig reads the pop config from the given io.Reader and returns the parsed ConnectionDetails map.
ParseMigrationFilename parses a migration filename.
Q will create a new "empty" query from the current connection.
SetEagerMode changes overall mode when eager loading.
SetLogger overrides the default logger.
SetNowFunc allows an override of time.Now for customizing CreatedAt/UpdatedAt.
SetLogger overrides the default logger.

# Constants

EagerDefault is the current implementation, the default behavior of pop.
EagerInclude This mode works similar to Include mode used in rails ActiveRecord.
EagerPreload mode works similar to Preload mode used in Rails ActiveRecord.

# Variables

AvailableDialects lists the available database dialects.
Color mode, to toggle colored logs.
ConfigName is the name of the YAML databases config file.
Connections contains all available connections.
Debug mode, to toggle verbose log traces.
ErrConfigFileNotFound is returned when the pop config file can't be found, after looking for it.
PaginatorPageKey is the query parameter holding the current page index.
PaginatorPerPageDefault is the amount of results per page.
PaginatorPerPageKey is the query parameter holding the amount of results per page to override the default one.

# Structs

AssociationMetaInfo a type to abstract all field information regarding to an association.
Connection represents all necessary details to talk with a datastore.
ConnectionDetails stores the data needed to connect to a datasource.
FileMigrator is a migrator for SQL and Fizz files on disk at a specified path.
GroupClause holds the field to apply the GROUP clause on.
HavingClause defines a condition and its arguments for a HAVING clause.
Match holds the information parsed from a migration filename.
Migration handles the data for a given database migration.
MigrationBox is a wrapper around fs.FS and Migrator.
Migrator forms the basis of all migrations systems.
Model is used throughout Pop to wrap the end user interface that is passed in to many functions.
ModelMetaInfo a type to abstract all fields information regarding to a model.
Paginator is a type used to represent the pagination of records from the database.
Query is the main value that is used to build up a query to be executed against the `Connection`.
Tx stores a transaction with an ID to keep track.

# Interfaces

AfterCreateable callback will be called after a record is created in the database.
AfterDestroyable callback will be called after a record is destroyed in the database.
AfterEagerFindable callback will be called after a record, or records, has been retrieved from the database and their associations have been eagerly loaded.
AfterFindable callback will be called after a record, or records, has been retrieved from the database.
AfterSaveable callback will be called after a record is either created or updated in the database.
AfterUpdateable callback will be called after a record is updated in the database.
BeforeCreateable callback will be called before a record is created in the database.
BeforeDestroyable callback will be called before a record is destroyed in the database.
BeforeSaveable callback will be called before a record is either created or updated in the database.
BeforeUpdateable callback will be called before a record is updated in the database.
BeforeValidateable callback will be called before a record is validated during ValidateAndCreate, ValidateAndUpdate, or ValidateAndSave.
PaginationParams is a parameters provider interface to get the pagination params from.
TableNameAble interface allows for the customize table mapping between a name and the database.
TableNameAbleWithContext is equal to TableNameAble but will be passed the queries' context.
Value is the contents of a `Model`.

# Type aliases

EagerMode type for all eager modes supported in pop.
Migrations is a collection of Migration.
ScopeFunc applies a custom operation on a given `Query`.