PostgreSQL is one of the most popular relational databases for backend applications, and Go works very well with it.

If you are building a REST API, web server, authentication system, SaaS platform, e-commerce backend, or microservice in Go, connecting your application to PostgreSQL is often one of the first important steps.

In this guide, you will learn how to connect PostgreSQL with Go using the standard database/sql package and the pgx driver. You will also learn how to create a database, install the driver, configure a connection string, verify the connection, use environment variables, run basic queries, configure connection pooling, and fix common connection errors.

What Do You Need to Connect Go with PostgreSQL?

You need three main things:

Go application
PostgreSQL database
PostgreSQL driver for Go

The connection flow looks like this:

Go Application
     |
     v
database/sql
     |
     v
pgx Driver
     |
     v
PostgreSQL

Why Use PostgreSQL with Go?

PostgreSQL is a strong choice for Go applications because it provides:

ACID transactions
relational data modeling
joins
indexes
JSON support
constraints
full-text search
strong consistency
advanced SQL features
excellent performance

Go complements PostgreSQL with:

strong concurrency
fast execution
simple deployment
built-in database/sql
context support
connection pooling

Step 1: Install PostgreSQL

First, PostgreSQL must be installed and running on your computer.

After installation, verify it with:

psql --version

You should see output similar to:

psql (PostgreSQL) 17.x

The exact version may be different.

Step 2: Start PostgreSQL

How you start PostgreSQL depends on your operating system.

On macOS with Homebrew, it may look like:

brew services start postgresql

On Linux, you may use:

sudo systemctl start postgresql

On Windows, PostgreSQL usually runs as a Windows service after installation.

Step 3: Create a PostgreSQL Database

Open PostgreSQL:

psql -U postgres

Then create a database:

CREATE DATABASE go_app;

You can confirm available databases with:

\l

Connect to the new database:

\c go_app

Step 4: Create a PostgreSQL User

You can create a dedicated database user for your Go application.

Example:

CREATE USER go_user WITH PASSWORD 'your_password';

Grant access:

GRANT ALL PRIVILEGES ON DATABASE go_app TO go_user;

For production applications, use proper role permissions instead of giving more privileges than necessary.

Step 5: Create a Go Project

Create a new directory:

mkdir go-postgres

Enter it:

cd go-postgres

Initialize the project:

go mod init go-postgres

Create:

main.go

Your project should look like:

go-postgres/
│
├── go.mod
└── main.go

Step 6: Install the PostgreSQL Driver

Go’s database/sql package does not include a PostgreSQL driver by itself.

A popular driver is:

pgx

Install it:

go get github.com/jackc/pgx/v5/stdlib

This lets you use pgx through Go’s standard database/sql package.

Step 7: Import Required Packages

Add:

package main

import (
    "database/sql"
    "fmt"
    "log"

    _ "github.com/jackc/pgx/v5/stdlib"
)

The underscore import:

_ "github.com/jackc/pgx/v5/stdlib"

registers the pgx driver with database/sql.

Step 8: Understand the PostgreSQL Connection String

A PostgreSQL URL usually looks like:

postgres://username:password@host:port/database

Example:

postgres://go_user:your_password@localhost:5432/go_app

Breaking it down:

postgres://     → PostgreSQL protocol
go_user         → database username
your_password   → password
localhost       → database host
5432            → default PostgreSQL port
go_app          → database name

Step 9: Connect PostgreSQL with `sql.Open`

Create the database handle:

db, err := sql.Open(
    "pgx",
    "postgres://go_user:your_password@localhost:5432/go_app",
)

if err != nil {
    log.Fatal(err)
}

Then:

defer db.Close()

Important: `sql.Open()` Does Not Verify the Connection

A common beginner misunderstanding is assuming:

sql.Open()

immediately verifies that PostgreSQL is reachable.

It does not necessarily establish a database connection at that moment.

To verify connectivity, use:

db.Ping()

Step 10: Verify the PostgreSQL Connection

Example:

err = db.Ping()

if err != nil {
    log.Fatal(err)
}

fmt.Println("Connected to PostgreSQL successfully")

Complete Basic Connection Example

package main

import (
    "database/sql"
    "fmt"
    "log"

    _ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    databaseURL :=
        "postgres://go_user:your_password@localhost:5432/go_app"

    db, err := sql.Open(
        "pgx",
        databaseURL,
    )

    if err != nil {
        log.Fatal(err)
    }

    defer db.Close()

    err = db.Ping()

    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(
        "Connected to PostgreSQL successfully",
    )
}

Run:

go run main.go

Expected output:

Connected to PostgreSQL successfully

Step 11: Use `PingContext`

For real backend applications, using context is usually better.

Import:

"context"
"time"

Then:

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

defer cancel()

Verify connection:

err =
    db.PingContext(ctx)

Complete example:

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

defer cancel()

if err :=
    db.PingContext(ctx);
    err != nil {

    log.Fatal(err)
}

This prevents your application from waiting indefinitely if the database is unavailable.

Step 12: Store the Database URL in an Environment Variable

Do not hardcode credentials like this in production:

databaseURL :=
    "postgres://admin:password123@localhost:5432/app"

Instead, use:

databaseURL :=
    os.Getenv("DATABASE_URL")

Import:

"os"

Example:

databaseURL :=
    os.Getenv(
        "DATABASE_URL",
    )

if databaseURL == "" {
    log.Fatal(
        "DATABASE_URL is required",
    )
}

Example Environment Variable

Linux/macOS:

export DATABASE_URL="postgres://go_user:your_password@localhost:5432/go_app"

Then:

go run main.go

Using a `.env` File

During local development, developers often use a .env file.

Example:

DATABASE_URL=postgres://go_user:your_password@localhost:5432/go_app

Do not commit .env files containing real passwords to Git.

Add:

.env

to:

.gitignore

if it contains sensitive configuration.

Step 13: Create a Table

Once connected, create a table in PostgreSQL.

Example:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(150) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Now your Go application can work with this table.

Step 14: Test the Connection with a Query

A simple PostgreSQL query:

SELECT NOW();

In Go:

var currentTime time.Time

err :=
    db.QueryRow(
        "SELECT NOW()",
    ).Scan(
        &currentTime,
    )

if err != nil {
    log.Fatal(err)
}

fmt.Println(
    "Database time:",
    currentTime,
)

This confirms that your application can execute SQL queries successfully.

Step 15: Insert Data into PostgreSQL

Example:

var userID int

err :=
    db.QueryRow(
        `
        INSERT INTO users (
            name,
            email
        )
        VALUES ($1, $2)
        RETURNING id
        `,
        "John",
        "john@example.com",
    ).Scan(
        &userID,
    )

if err != nil {
    log.Fatal(err)
}

fmt.Println(
    "Created user ID:",
    userID,
)

Why PostgreSQL Uses `$1`, `$2`, `$3`

PostgreSQL parameter placeholders look like:

$1
$2
$3

Example:

INSERT INTO users (name, email)
VALUES ($1, $2);

Then Go passes the values separately:

name,
email,

This is safer than building SQL manually.

Never Build Queries with User Input Directly

Avoid:

query :=
    "SELECT * FROM users WHERE email = '" +
        email +
        "'"

This can create SQL injection vulnerabilities.

Use:

db.QueryRow(
    `
    SELECT id, name, email
    FROM users
    WHERE email = $1
    `,
    email,
)

Step 16: Read Data from PostgreSQL

Define:

type User struct {
    ID    int
    Name  string
    Email string
}

Then:

var user User

err :=
    db.QueryRow(
        `
        SELECT id, name, email
        FROM users
        WHERE id = $1
        `,
        1,
    ).Scan(
        &user.ID,
        &user.Name,
        &user.Email,
    )

if err != nil {
    log.Fatal(err)
}

fmt.Println(user)

Handling `sql.ErrNoRows`

If the user does not exist:

if err == sql.ErrNoRows {
    fmt.Println(
        "User not found",
    )
    return
}

Full pattern:

err :=
    db.QueryRow(
        `
        SELECT id, name, email
        FROM users
        WHERE id = $1
        `,
        userID,
    ).Scan(
        &user.ID,
        &user.Name,
        &user.Email,
    )

if err == sql.ErrNoRows {
    fmt.Println("User not found")
    return
}

if err != nil {
    log.Fatal(err)
}

Step 17: Read Multiple Rows

Use:

db.Query()

Example:

rows, err :=
    db.Query(
        `
        SELECT id, name, email
        FROM users
        ORDER BY id
        `,
    )

if err != nil {
    log.Fatal(err)
}

defer rows.Close()

Iterate:

for rows.Next() {
    var user User

    err :=
        rows.Scan(
            &user.ID,
            &user.Name,
            &user.Email,
        )

    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(user)
}

After the loop:

if err :=
    rows.Err();
    err != nil {

    log.Fatal(err)
}

Step 18: Configure the Connection Pool

sql.DB manages a connection pool automatically.

You can configure it.

Example:

db.SetMaxOpenConns(25)

db.SetMaxIdleConns(10)

db.SetConnMaxLifetime(
    30 * time.Minute,
)

db.SetConnMaxIdleTime(
    5 * time.Minute,
)

What Do These Settings Mean?

SetMaxOpenConns:

db.SetMaxOpenConns(25)

sets the maximum number of open database connections.

SetMaxIdleConns:

db.SetMaxIdleConns(10)

controls how many idle connections can remain available.

SetConnMaxLifetime:

db.SetConnMaxLifetime(
    30 * time.Minute,
)

limits how long a connection can exist.

SetConnMaxIdleTime:

db.SetConnMaxIdleTime(
    5 * time.Minute,
)

controls how long an unused connection can remain idle.

Do Not Copy Pool Values Blindly

The correct settings depend on:

Application traffic
PostgreSQL limits
Number of server instances
Query duration
Database resources
Cloud infrastructure

Start conservatively and monitor the application.

Step 19: Create a Reusable Database Function

Instead of putting connection logic directly in main.go, create a reusable function.

Example:

func openDatabase(
    databaseURL string,
) (*sql.DB, error) {

    db, err :=
        sql.Open(
            "pgx",
            databaseURL,
        )

    if err != nil {
        return nil, err
    }

    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(10)

    db.SetConnMaxLifetime(
        30 * time.Minute,
    )

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

    defer cancel()

    if err :=
        db.PingContext(ctx);
        err != nil {

        db.Close()

        return nil, err
    }

    return db, nil
}

Use:

db, err :=
    openDatabase(
        databaseURL,
    )

if err != nil {
    log.Fatal(err)
}

defer db.Close()

Recommended Project Structure

For a larger Go application:

go-postgres/
│
├── cmd/
│   └── api/
│       └── main.go
│
├── internal/
│   ├── database/
│   │   └── database.go
│   │
│   ├── repositories/
│   │   └── user_repository.go
│   │
│   ├── models/
│   │   └── user.go
│   │
│   ├── services/
│   └── handlers/
│
├── migrations/
│
├── go.mod
└── go.sum

`database/database.go`

Example:

package database

import (
    "context"
    "database/sql"
    "time"

    _ "github.com/jackc/pgx/v5/stdlib"
)

func Open(
    databaseURL string,
) (*sql.DB, error) {

    db, err :=
        sql.Open(
            "pgx",
            databaseURL,
        )

    if err != nil {
        return nil, err
    }

    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(10)

    db.SetConnMaxLifetime(
        30 * time.Minute,
    )

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

    defer cancel()

    if err :=
        db.PingContext(ctx);
        err != nil {

        db.Close()

        return nil, err
    }

    return db, nil
}

Using PostgreSQL in an HTTP Server

Your application might start like:

func main() {
    databaseURL :=
        os.Getenv(
            "DATABASE_URL",
        )

    db, err :=
        database.Open(
            databaseURL,
        )

    if err != nil {
        log.Fatal(err)
    }

    defer db.Close()

    mux :=
        http.NewServeMux()

    // Register handlers using db

    log.Fatal(
        http.ListenAndServe(
            ":8080",
            mux,
        ),
    )
}

Passing the Database to a Handler

Example:

func getUsersHandler(
    db *sql.DB,
) http.HandlerFunc {

    return func(
        w http.ResponseWriter,
        r *http.Request,
    ) {

        rows, err :=
            db.QueryContext(
                r.Context(),
                `
                SELECT
                    id,
                    name,
                    email
                FROM users
                ORDER BY id
                `,
            )

        if err != nil {
            http.Error(
                w,
                "Database error",
                http.StatusInternalServerError,
            )
            return
        }

        defer rows.Close()

        fmt.Fprintln(
            w,
            "Database query successful",
        )
    }
}

mux.HandleFunc(
    "/users",
    getUsersHandler(db),
)

Should You Use `database/sql` or Native pgx?

You can use PostgreSQL in Go in two common ways.

First:

database/sql + pgx driver

Second:

native pgx API

Using database/sql gives you a standard database interface.

Using native pgx can give you deeper access to PostgreSQL-specific capabilities.

For beginners, understanding database/sql is very useful because the concepts apply across many SQL databases.

Common PostgreSQL Connection Errors

Error: Connection Refused

You may see something similar to:

connect: connection refused

Possible reasons:

PostgreSQL is not running
Wrong port
Wrong host
Firewall issue

Check whether PostgreSQL is running and confirm the port.

Default PostgreSQL port:

Error: Password Authentication Failed

Example:

password authentication failed for user

Check:

Username
Password
Connection string
PostgreSQL role

Make sure the credentials are correct.

Error: Database Does Not Exist

Example:

database "go_app" does not exist

Create it:

CREATE DATABASE go_app;

Error: Driver Unknown

If you use:

sql.Open(
    "pgx",
    databaseURL,
)

but forget:

_ "github.com/jackc/pgx/v5/stdlib"

you may get a driver-related error.

Make sure the driver is installed and imported.

Error: SSL Required or SSL Configuration Problem

Local PostgreSQL often works differently from cloud-hosted PostgreSQL.

Some cloud providers require SSL.

A connection URL might include options such as:

?sslmode=require

Local development may use a different SSL mode depending on configuration.

Always follow your PostgreSQL provider’s connection requirements.

Example Local Connection String

postgres://go_user:your_password@localhost:5432/go_app

A cloud provider may provide a URL that already contains the correct host, credentials, port, database, and SSL options.

Special Characters in Passwords

If your PostgreSQL password contains characters such as:

@
:
/
?
#

a plain URL can break if those characters are not properly encoded.

Use a correctly encoded connection URL or a structured configuration approach.

Check PostgreSQL from the Terminal

Before blaming Go, verify that you can connect directly.

Example:

psql "postgres://go_user:your_password@localhost:5432/go_app"

If this fails, the issue is probably PostgreSQL configuration or credentials rather than your Go code.

PostgreSQL Connection Security

For production:

never hardcode passwords
use environment variables
use secure secret storage
use TLS/SSL when required
create dedicated database roles
follow least-privilege access
do not expose PostgreSQL directly to the public internet unnecessarily
rotate credentials when needed
monitor failed connection attempts

Do Not Open the Database for Every Request

Avoid:

Request
   ↓
sql.Open()
   ↓
Query
   ↓
db.Close()

for every HTTP request.

Instead:

Application starts
   ↓
Open sql.DB once
   ↓
Reuse pool
   ↓
Serve many requests
   ↓
Close during shutdown

This is more efficient.

Connection Flow in a Real Go Backend

A typical architecture may look like:

Client
   |
   v
Go HTTP Handler
   |
   v
Service
   |
   v
Repository
   |
   v
sql.DB
   |
   v
pgx Driver
   |
   v
PostgreSQL

Complete Practical Example

package main

import (
    "context"
    "database/sql"
    "fmt"
    "log"
    "os"
    "time"

    _ "github.com/jackc/pgx/v5/stdlib"
)

type User struct {
    ID    int
    Name  string
    Email string
}

func main() {
    databaseURL :=
        os.Getenv(
            "DATABASE_URL",
        )

    if databaseURL == "" {
        log.Fatal(
            "DATABASE_URL is required",
        )
    }

    db, err :=
        sql.Open(
            "pgx",
            databaseURL,
        )

    if err != nil {
        log.Fatal(
            "Failed to open database:",
            err,
        )
    }

    defer db.Close()

    db.SetMaxOpenConns(20)
    db.SetMaxIdleConns(10)

    db.SetConnMaxLifetime(
        30 * time.Minute,
    )

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

    defer cancel()

    if err :=
        db.PingContext(ctx);
        err != nil {

        log.Fatal(
            "Failed to connect to PostgreSQL:",
            err,
        )
    }

    fmt.Println(
        "Connected to PostgreSQL",
    )

    var currentTime time.Time

    err =
        db.QueryRowContext(
            ctx,
            "SELECT NOW()",
        ).Scan(
            &currentTime,
        )

    if err != nil {
        log.Fatal(
            "Query failed:",
            err,
        )
    }

    fmt.Println(
        "PostgreSQL time:",
        currentTime,
    )
}

Set:

export DATABASE_URL="postgres://go_user:your_password@localhost:5432/go_app"

Run:

go run main.go

Expected output:

Connected to PostgreSQL
PostgreSQL time: ...

What Should You Learn After Connecting PostgreSQL?

Once the connection works, continue with:

INSERT queries
SELECT queries
UPDATE queries
DELETE queries
Transactions
Prepared statements
Context
Pagination
JOINs
Indexes
Migrations
Repository pattern
REST API integration
Testing

Frequently Asked Questions

How do I connect PostgreSQL with Go?

Use Go’s database/sql package with a PostgreSQL driver such as pgx.

Example:

db, err :=
    sql.Open(
        "pgx",
        databaseURL,
    )

Then verify:

db.Ping()

Which PostgreSQL driver should I use with Go?

pgx is a popular choice and can be used both through database/sql and through its native API.

What is the default PostgreSQL port?

The default PostgreSQL port is:

Does `sql.Open()` connect immediately?

Not necessarily.

It creates a database handle and connection pool.

Use:

db.Ping()

or:

db.PingContext()

to verify the connection.

What is `sql.DB`?

sql.DB is a concurrency-safe database handle that manages a pool of database connections.

Should I create one `sql.DB` per request?

No.

Create a long-lived database handle when your application starts and reuse it.

Where should I store my PostgreSQL password?

Use environment variables or a proper secrets-management system.

Do not commit passwords to source control.

How do I prevent SQL injection?

Use parameterized SQL queries.

Example:

db.QueryRow(
    `
    SELECT id
    FROM users
    WHERE email = $1
    `,
    email,
)

Can Go connect to cloud PostgreSQL?

Yes.

Go can connect to hosted PostgreSQL services as long as you have the correct connection string, credentials, networking access, and SSL configuration.

Is PostgreSQL good for Go REST APIs?

Yes.

PostgreSQL and Go are a strong combination for REST APIs, SaaS platforms, web applications, microservices, and other backend systems.

Conclusion

Connecting PostgreSQL with Go is straightforward once you understand the basic pieces.

You need:

PostgreSQL
database/sql
PostgreSQL driver
Connection URL

The essential connection code is:

db, err :=
    sql.Open(
        "pgx",
        databaseURL,
    )

Then verify it using:

db.Ping()

For production applications, improve this setup with:

Environment variables
PingContext
Connection timeouts
Connection pooling
Secure credentials
SSL
Graceful shutdown
Repository architecture
Monitoring

Once PostgreSQL is connected successfully, you can move on to creating tables, inserting data, reading rows, updating records, deleting data, using transactions, and building complete Go REST APIs backed by PostgreSQL.

How to Connect PostgreSQL with Go: Complete Guide

What Do You Need to Connect Go with PostgreSQL?

Why Use PostgreSQL with Go?

Step 1: Install PostgreSQL

Step 2: Start PostgreSQL

Step 3: Create a PostgreSQL Database

Step 4: Create a PostgreSQL User

Step 5: Create a Go Project

Step 6: Install the PostgreSQL Driver

Step 7: Import Required Packages

Step 8: Understand the PostgreSQL Connection String

Step 9: Connect PostgreSQL with sql.Open

Important: sql.Open() Does Not Verify the Connection

Step 10: Verify the PostgreSQL Connection

Complete Basic Connection Example

Step 11: Use PingContext

Step 12: Store the Database URL in an Environment Variable

Example Environment Variable

Using a .env File

Step 13: Create a Table

Step 14: Test the Connection with a Query

Step 15: Insert Data into PostgreSQL

Why PostgreSQL Uses $1, $2, $3

Never Build Queries with User Input Directly

Step 16: Read Data from PostgreSQL

Handling sql.ErrNoRows

Step 17: Read Multiple Rows

Step 18: Configure the Connection Pool

What Do These Settings Mean?

Do Not Copy Pool Values Blindly

Step 19: Create a Reusable Database Function

Recommended Project Structure

database/database.go

Using PostgreSQL in an HTTP Server

Passing the Database to a Handler

Should You Use database/sql or Native pgx?

Common PostgreSQL Connection Errors

Error: Connection Refused

Error: Password Authentication Failed

Error: Database Does Not Exist

Error: Driver Unknown

Error: SSL Required or SSL Configuration Problem

Example Local Connection String

Special Characters in Passwords

Check PostgreSQL from the Terminal

PostgreSQL Connection Security

Do Not Open the Database for Every Request

Connection Flow in a Real Go Backend

Complete Practical Example

What Should You Learn After Connecting PostgreSQL?

Frequently Asked Questions

How do I connect PostgreSQL with Go?

Which PostgreSQL driver should I use with Go?

What is the default PostgreSQL port?

Does sql.Open() connect immediately?

What is sql.DB?

Should I create one sql.DB per request?

Where should I store my PostgreSQL password?

How do I prevent SQL injection?

Can Go connect to cloud PostgreSQL?

Is PostgreSQL good for Go REST APIs?

Conclusion

Related Articles

How to Schedule Automated Jobs in Node.js

Building a Task Automation Tool With Node.js

How to Become an API Developer: Complete Roadmap

Step 9: Connect PostgreSQL with `sql.Open`

Important: `sql.Open()` Does Not Verify the Connection

Step 11: Use `PingContext`

Using a `.env` File

Why PostgreSQL Uses `$1`, `$2`, `$3`

Handling `sql.ErrNoRows`

`database/database.go`

Should You Use `database/sql` or Native pgx?

Does `sql.Open()` connect immediately?

What is `sql.DB`?

Should I create one `sql.DB` per request?