README
¶
briefpg
Temporary PostgreSQL Instances for Unit Tests
briefpg makes it easy to create Go tests backed by a live, temporary Postgres database. While mocking a database is helpful in some cases, it's just as often helpful to have a real live database to work against.
This project is based on the concepts from the very nice package ephemeralpg by Eric Radman. Perhaps we should have called it gophemeralpg?
The author also wishes to express gratitude to my employer Brightgate, which allowed its release to Open Source. And to Danek Duvall who helped to review, refine, and fix bugs (unfortunately some of the commit history is lost in the transition to Open Source).
Documentation
¶
Overview ¶
Package briefpg provides an easy way to start and control temporary instances of PostgreSQL servers. The package is designed primarily as an aid to writing test cases. The package does not select or mandate any particular PostgreSQL driver, as it invokes Postgres commands to do its work. The package has been designed to have no dependencies outside of core go packages.
Concepts are drawn from Eric Radmon's EphemeralPG and Python's testing.postgresql.
Index ¶
- Constants
- func NullLogFunction(format string, a ...interface{})
- func PostgresInstalled(path string) error
- type BriefPG
- func (bp *BriefPG) CreateDB(ctx context.Context, dbName, createArgs string) (string, error)
- func (bp *BriefPG) DBUri(dbName string) string
- func (bp *BriefPG) DbDir() string
- func (bp *BriefPG) DumpDB(ctx context.Context, dbName string, w io.Writer) error
- func (bp *BriefPG) Fini(ctx context.Context) error
- func (bp *BriefPG) MustFini(ctx context.Context)
- func (bp *BriefPG) PgVer() string
- func (bp *BriefPG) SetOption(o Option) error
- func (bp *BriefPG) Start(ctx context.Context) error
- type LogFunction
- type Option
Examples ¶
Constants ¶
const ( // DefaultPgConfTemplate is used by briefpg to configure the transient // postgres instance. This is cribbed from // https://github.com/eradman/ephemeralpg // It is provided here for reference. DefaultPgConfTemplate = `` /* 246-byte string literal not displayed */ )
Variables ¶
This section is empty.
Functions ¶
func NullLogFunction ¶
func NullLogFunction(format string, a ...interface{})
NullLogFunction can be used to suppress output from briefpg. (It is the default).
func PostgresInstalled ¶
PostgresInstalled returns an error if the module is unable to operate due to a failure to locate PostgreSQL.
Example ¶
err := PostgresInstalled("")
if err != nil {
log.Fatalf("Can't continue; did not find an installed PostgreSQL instance: %v", err)
}
fmt.Printf("Found Postgres")
Output: Found Postgres
Types ¶
type BriefPG ¶
type BriefPG struct {
// contains filtered or unexported fields
}
BriefPG represents a managed instance of the Postgres database server; the instance and all associated data is disposed when Fini() is called.
func New ¶
New returns an instance of BriefPG; if no PostgresPath option is present, attempt to automatically locate an instance of Postgres by first scanning the user's $PATH environment variable. If that fails, try a series of well-known installation locations. See the documentation for specific Options to understand what they do.
func (*BriefPG) CreateDB ¶
CreateDB is a convenience function to create a named database; you can do this using your database driver instead, at lower cost. This routine uses 'psql' to do the job. The primary use case is to rapidly set up an empty database for test purposes. The URI to access the database is returned.
func (*BriefPG) DbDir ¶
DbDir returns the installation directory of the Postgres database. In general, this should not be needed when writing tests, but it is provided for completeness.
func (*BriefPG) DumpDB ¶
DumpDB writes the named database contents to w using pg_dump. In a test case, this can be used to dump the database in the event of a failure.
func (*BriefPG) MustFini ¶
MustFini stops the database server, if running, and cleans it up; this routine wraps Fini() and will panic if an error is raised.
func (*BriefPG) SetOption ¶
SetOption applies an Option to the BriefPG. The option may fail to apply if invalid, or if the the BriefPG is in a state where applying the option is impossible. Passing Options to New() is preferred.
func (*BriefPG) Start ¶
Start the postgres server, performing necessary initialization along the way
Example ¶
ctx := context.Background()
bpg, err := New()
if err != nil {
log.Fatalf("New failed: %v", err)
}
err = bpg.Start(ctx)
if err != nil {
log.Fatalf("Start failed: %v", err)
}
fmt.Printf("Started")
defer bpg.MustFini(ctx)
// At this point, you might use the pq SQL driver to
// open the database using sql.Open(); you can obtain
// the database URI with bpg.DBUri().
Output: Started
type LogFunction ¶
type LogFunction func(string, ...interface{})
LogFunction describes a basic printf-style function.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option describes a generic interface for options.
func OptLogFunc ¶
func OptLogFunc(logf LogFunction) Option
OptLogFunc returns an Option which sets the logging function for BriefPG. A typical usage is err := bpg.SetOption(briefpg.OptLogFunc(t.Logf)) to connect BriefPG to the test's logging.
func OptPostgresEncoding ¶
OptPostgresEncoding returns an Option which sets the -E argument to the postgres 'initdb' command; this sets the default encoding for new databases. If not set, the default is UNICODE. This option can only be set before calling Start().
func OptPostgresPath ¶
OptPostgresPath returns an Option which sets the location to look for Postgres. If a satisfactory Postgres is not found at that location, returns an error. This option can only be set before calling Start().
func OptTmpDir ¶
OptTmpDir returns an Option which sets the temporary directory where the postgres database will put its files. If no user-specified OptTmpDir is set, ioutil.TempDir is used to create one automatically. The caller is responsible for making the TempDir. This option can only be set before calling Start(). If the TmpDir is specified, and user-created, it will not be cleaned up when calling Fini() or MustFini(). If automatically created, it will be automatically cleaned up.
Source Files