Documentation
¶
Overview ¶
Package grecho is a tool to mock your Postgres database in your automated tests.
Same concept as https://github.com/cockroachdb/copyist, but: - grecho mocks the server, not the driver, which means you can use any driver you want (eg. pgx) - grecho does not have a global state, which means you can start one server for each test and run them in parallel (though if you overdo it your computer might run out of resources) - grecho supports concurrent queries to the same server (though it does cheat a bit by stalling out-of-order queries)
grecho is recommended when: - you want to test your SQL queries but you don't want to spin up a Postgresql Server in your CI nor when you make a non-SQL related change
grecho is not recommended when: - testing performances (the proxy adds a non-constant overhead in recording mode, and the original query latency is not replicated in replaying mode) - testing database race conditions (unless you enable the strict mode, which forces you to always run your queries in the same order, effectively eliminating database race conditions by forbidding concurrency)
Index ¶
- func ForceRecording(_ context.Context, _ Config) (bool, error)
- func ForceReplaying(_ context.Context, _ Config) (bool, error)
- func NewPgxTestingServer(t *testing.T, options ...func(config *Config)) *pgxpool.Pool
- func PostgresBuilderFallback(builders ...func(context.Context, Config) (ConnectionString, error)) func(context.Context, Config) (ConnectionString, error)
- func PostgresBuilderViaEnvVar(envKey string) func(_ context.Context, _ Config) (ConnectionString, error)
- func ReplayIfRecordExists(_ context.Context, cfg Config) (bool, error)
- type Config
- type ConnectionString
- type QueryOrderValidationStrategy
- type Server
- type StartedServer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewPgxTestingServer ¶ added in v0.2.0
func PostgresBuilderFallback ¶
func PostgresBuilderFallback(builders ...func(context.Context, Config) (ConnectionString, error)) func( context.Context, Config, ) (ConnectionString, error)
Types ¶
type Config ¶
type Config struct {
// EchoFilePath should be a path to a file we can read and write to store the mocking data.
// Default value is "testdata/grecho.jsonl"
EchoFilePath string
// RealPostgresBuilder is a function returning the network address (host:port) of a real postgres database.
// It will only be used when recording.
// Default value uses "github.com/testcontainers/testcontainers-go/modules/postgres" to start a postgres in Docker.
// Unused in replaying mode.
RealPostgresBuilder func(ctx context.Context, cfg Config) (ConnectionString, error)
// MustRecord is a function telling the server if it must write to the record or read it.
// Default value decides to record if the file does not exist yet, and to replay if it does.
IsRecording func(ctx context.Context, cfg Config) (bool, error)
// Logger will be used by the server for all its logging.
// It is meant to be an *slog.Logger.
// Default value is a no-op logger.
Logger *slog.Logger
// QueryOrderValidationStrategy determines how to handle out-of-order queries in replay mode.
// Default is QueryOrderValidationStrategyStalling
QueryOrderValidationStrategy QueryOrderValidationStrategy
// Listener
// Default value listens on tcp://127.0.0.1: (random port)
Listener net.Listener
}
type ConnectionString ¶
type ConnectionString = string
func PostgresBuilderViaTestContainers ¶
func PostgresBuilderViaTestContainers(ctx context.Context, cfg Config) (ConnectionString, error)
type QueryOrderValidationStrategy ¶
type QueryOrderValidationStrategy string
const ( // QueryOrderValidationStrategyStrict forbids out-of-order queries. // Probably won't work if you have concurrent queries, but provides more security if you don't. QueryOrderValidationStrategyStrict QueryOrderValidationStrategy = "strict" // QueryOrderValidationStrategyStalling handles out-of-order queries by stalling them until it is their turn. // This allows concurrent queries as long as your queries don't end up waiting on each other (when you have maxed out your connection pool for example). // A 3 seconds timeout is configured so that it doesn't hang forever. QueryOrderValidationStrategyStalling QueryOrderValidationStrategy = "stalling" )
type StartedServer ¶
type StartedServer interface {
Wait() error
Stop() error
ConnectionString() ConnectionString
}
Source Files
Directories