5-minute quickstart

This instance is for local learning only. A password on the command line and a host-published port are not production configuration.

Start the instance

docker run --name pg-guide \
  -e POSTGRES_PASSWORD=dev-only-password \
  -e POSTGRES_DB=playground \
  -p 5432:5432 \
  -v pg-guide-data:/var/lib/postgresql/data \
  -d postgres:18

Wait and check

docker exec pg-guide pg_isready -U postgres -d playground
docker logs pg-guide --tail 20

Continue after accepting connections appears.

Open psql

docker exec -it pg-guide psql -U postgres -d playground

CREATE TABLE notes (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  body text NOT NULL CHECK (length(body) > 0),
  created_at timestamptz NOT NULL DEFAULT now()
);

INSERT INTO notes (body) VALUES ('hello, PostgreSQL');
SELECT id, body, created_at FROM notes;

Verify persistence

docker restart pg-guide
docker exec pg-guide psql -U postgres -d playground \
  -c "SELECT id, body, created_at FROM notes;"

If the row survives the restart, the named volume is working.

Connection string

Applications on the host can use:

postgresql://postgres:dev-only-password@127.0.0.1:5432/playground

Never commit real credentials. Production systems need a secret manager, a least-privilege application role, and TLS.

Clean up

docker rm -f pg-guide
docker volume rm pg-guide-data

The second command permanently deletes the practice data. Run it only when that is intentional.

Continue with Start here, or jump to Data modeling.