dbenv

func ExecQuery ¶

func ExecQuery(ctx context.Context, db *sql.DB, query Query) error

ExecQuery executes a single Query against the database. This function handles both raw SQL strings and query builder objects.

Parameters:

• ctx: Context for cancellation and timeout
• db: Database connection to execute the query against
• query: The Query to execute (string or sqlizer)

Returns:

• error: Non-nil if the query execution fails

func Use ¶

func Use(ctx context.Context, env Environment, opts ...Option) (*sql.DB, error)

Use connects to a database environment and returns the database connection. This is a simple convenience function that calls the environment's Connect method, applies any provided options, and wraps any error with additional context.

This function is suitable for production code where you need to manage the connection lifecycle manually. For testing, consider using UseForTesting which provides automatic cleanup.

Parameters:

• ctx: Context for cancellation and timeout
• env: Database environment to connect to
• opts: Optional configuration functions to apply after connection

Returns:

• *sql.DB: Database connection ready to use
• error: Non-nil if connection or any option fails

Example:

// Connect to environment
db, err := Use(ctx, env)
if err != nil {
	return fmt.Errorf("connect: %w", err)
}
defer db.Close()

// Use database...
rows, err := db.QueryContext(ctx, "SELECT * FROM users")

Example with options:

// Connect with migrations
db, err := Use(ctx, env,
	Queries("CREATE TABLE users (id SERIAL PRIMARY KEY)"),
)
if err != nil {
	return err
}
defer db.Close()

Example with timeout:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

db, err := Use(ctx, env)
if err != nil {
	return err
}
defer db.Close()

func UseForTesting ¶

func UseForTesting(
	t *testing.T,
	env Environment,
	opts ...Option,
) *sql.DB

UseForTesting connects to a database environment for use in tests. This function is designed specifically for testing scenarios and provides automatic connection cleanup.

Key features:

• Calls t.Helper() to improve error reporting
• Automatically closes the database connection when the test completes
• Fails the test immediately if connection fails
• Reports cleanup errors to the test log
• Applies any provided options after connection

Parameters:

• t: Testing context (must not be nil)
• env: Database environment to connect to
• opts: Optional configuration functions to apply after connection

Returns:

• *sql.DB: Database connection ready to use (automatically closed after test)

The function will call t.Fatal if connection fails, which immediately stops the test execution.

Example:

func TestDatabase(t *testing.T) {
	t.Parallel()

	// Create environment
	env := createTestEnvironment()

	// Get database connection - automatically closed after test
	db := UseForTesting(t, env)

	// Use database in test
	var count int
	err := db.QueryRow("SELECT COUNT(*) FROM users").Scan(&count)
	require.NoError(t, err)

	assert.Equal(t, 0, count)
}

Example with options:

func TestWithMigrations(t *testing.T) {
	t.Parallel()

	// Create environment
	env := postgresenv.New(...)

	// Connect with migrations - automatically closed after test
	db := UseForTesting(t, env,
		Queries("CREATE TABLE users (id SERIAL PRIMARY KEY)"),
	)

	// Database now has users table
	_, err := db.Exec("INSERT INTO users DEFAULT VALUES")
	require.NoError(t, err)
}

Note: The database connection is closed using t.Cleanup(), which runs after the test completes. If you need to close the connection earlier, use Use() instead and manage the lifecycle manually.