Fix DatabaseError: sql: database is closed in Echo

This error occurs when a query is executed on a database connection that has been closed, typically because db.Close() is called prematurely or the connection pool is misconfigured. Fix it by managing the database lifecycle properly with graceful shutdown, passing the db via dependency injection, and ensuring Close is only called when the application exits.

Reading the Stack Trace

Here's what each line means:

• main.ListProducts({0x1029e4f80, 0x14000226000}) /app/handlers/product.go:18 +0x1c4: The ListProducts handler at line 18 attempts a query on a database connection that has already been closed.
• database/sql.(*DB).QueryContext(0x14000118300, {0x1029f0ea0, 0x14000196040}, {0x1028f1e60, 0x17}, {0x0, 0x0, 0x0}): Go's database/sql package detects that the DB handle is closed and returns an error instead of executing the query.
• database/sql.(*DB).query(0x14000118300, {0x1029f0ea0, 0x14000196040}, {0x1028f1e60, 0x17}, {0x0, 0x0, 0x0}): The internal query method checks the closed flag before acquiring a connection from the pool.

Common Causes

func main() {
	db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	defer db.Close() // closes immediately when main returns

	e := echo.New()
	e.GET("/api/products", ListProducts)
	go e.Start(":8080")
	// main returns, db.Close() runs, server still running
}

var db *sql.DB

func resetDB() {
	db.Close()
	db = nil // subsequent queries panic
}

func main() {
	e := echo.New()
	e.Start(":8080") // no signal handling, no graceful shutdown
}

The Fix

Use graceful shutdown with signal handling. Start the server in a goroutine and wait for SIGINT/SIGTERM. On shutdown, call e.Shutdown to finish in-flight requests, then close the database connection. This ensures db.Close() only runs after all handlers complete.

func main() {
	db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	defer db.Close()

	e := echo.New()
	e.GET("/api/products", ListProducts)
	e.Start(":8080")
}

func main() {
	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	if err := db.Ping(); err != nil {
		log.Fatal(err)
	}

	e := echo.New()
	e.GET("/api/products", NewListProducts(db))

	// Graceful shutdown
	go func() {
		if err := e.Start(":8080"); err != nil && err != http.ErrServerClosed {
			log.Fatal(err)
		}
	}()

	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := e.Shutdown(ctx); err != nil {
		log.Fatal(err)
	}
	db.Close()
	log.Println("server stopped gracefully")
}

Testing the Fix

package handlers_test

import (
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/DATA-DOG/go-sqlmock"
	"github.com/labstack/echo/v4"
	"github.com/stretchr/testify/assert"
)

func TestListProducts_Success(t *testing.T) {
	db, mock, _ := sqlmock.New()
	defer db.Close()

	rows := sqlmock.NewRows([]string{"id", "name"}).AddRow(1, "Widget")
	mock.ExpectQuery("SELECT").WillReturnRows(rows)

	e := echo.New()
	req := httptest.NewRequest(http.MethodGet, "/api/products", nil)
	rec := httptest.NewRecorder()
	c := e.NewContext(req, rec)

	handler := NewListProducts(db)
	err := handler(c)
	assert.NoError(t, err)
	assert.Equal(t, http.StatusOK, rec.Code)
}

func TestListProducts_DBClosed(t *testing.T) {
	db, _, _ := sqlmock.New()
	db.Close()

	e := echo.New()
	req := httptest.NewRequest(http.MethodGet, "/api/products", nil)
	rec := httptest.NewRecorder()
	c := e.NewContext(req, rec)

	handler := NewListProducts(db)
	err := handler(c)
	assert.NoError(t, err)
	assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
}

Run your tests:

go test ./handlers/... -v

Pushing Through CI/CD

git checkout -b fix/echo-database-error,git add main.go handlers/product.go,git commit -m "fix: implement graceful shutdown to prevent database closed errors",git push origin fix/echo-database-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm database handling works.
2. Open a pull request with the graceful shutdown changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify graceful shutdown in staging.

Frequently Asked Questions