Unable to use psql through PGAdapter + Emulator image

[cdco-busunkim]

Hello!

I am following the instructions for running the PGAdapter + Emulator image in the README, but can't seem to connect to it through psql. I can see the container is running and it doesn't have any error logs.

is there a step I'm missing?

➜  ~ docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run \
  -d -p 5432:5432 \
  gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
sleep 2
psql -h localhost -p 5432 -d test-database
Using default tag: latest
latest: Pulling from cloud-spanner-pg-adapter/pgadapter-emulator
Digest: sha256:f78f4a39218bf7b0236189a78523bbd20097ed8a768a252ad80e3ad1aa781ec2
Status: Image is up to date for gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator:latest
gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator:latest
a0a1b0eabd900852dee2bbcf843f792f5f02715d0ce2201df930bf8c066f56fb
psql: error: connection to server at "localhost" (::1), port 5432 failed: FATAL:  database "test-database" does not exist

Container Logs

java -jar pgadapter.jar -p emulator-project -i test-instance -r autoConfigEmulator=true -c "" -x

WARNING: All log messages before absl::InitializeLog() is called are written to STDERR

I0000 00:00:1783374891.297170      16 emulator_main.cc:39] Cloud Spanner Emulator running.

I0000 00:00:1783374891.297184      16 emulator_main.cc:40] Server address: 0.0.0.0:9010

-- Starting PGAdapter version 0.55.1 --

-- PostgreSQL version: 14.1 -- 

WARNING: A restricted method in java.lang.System has been called

WARNING: java.lang.System::loadLibrary has been called by org.newsclub.net.unix.NativeLibraryLoader$StandardLibraryCandidate in an unnamed module (file:/home/pgadapter/lib/junixsocket-common-2.10.1.jar)

WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module

WARNING: Restricted methods will be blocked in a future release unless native access is enabled


[2026-07-06 21:54:51.425] [INFO] (com.google.cloud.spanner.pgadapter.ProxyServer startServer): Server started on port 5432

2026/07/06 21:54:52 gateway.go:163: Cloud Spanner emulator running.

2026/07/06 21:54:52 gateway.go:164: REST server listening at 0.0.0.0:9020

2026/07/06 21:54:52 gateway.go:165: gRPC server listening at 0.0.0.0:9010

[rayudu3745]

Hi @cdco-busunkim,

The error you are seeing (FATAL: database "test-database" does not exist) is coming from a local PostgreSQL server already running on your machine on port 5432, not from the PGAdapter Docker container.

Because port 5432 is already in use by your local PostgreSQL instance, your psql command is connecting to that server instead of the Docker container.

You can resolve this using either of the following options:

1. Map the Docker container to a different port (Recommended)

Start the container on port 5433 to avoid conflicting with your local PostgreSQL server:

docker run -d -p 5433:5432 gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
psql -h localhost -p 5433 -d test-database

2. Stop your local PostgreSQL service

If you don't need your local PostgreSQL server running, stop the service (e.g., brew services stop postgresql or sudo service postgresql stop) and try your original commands again.

[cdco-busunkim]

Ahh that makes sense, thank you!