šŸ“˜ Technical Journey: How I Connected Go to Oracle XE in Docker and Debugged It in VSCode (Apple Silicon)

May 9, 2025 45 min

šŸ›¤ļø Introduction

Sometimes what seems like a simple ā€œconnect your app to the databaseā€ turns into an epic story of errors, frustration, coffee, and real technical learning. In this journey, Iā€™ll walk you step by step through how I connected a Go application to an Oracle XE database inside a Docker container and how I finally debugged it from VSCodeā€¦ on an M1 Mac.

šŸš§ The challenge

My goal was simple:

  • Connect Go to Oracle XE
  • Use Docker to avoid local installations
  • Debug the Go application with Delve from VSCode

But if youā€™re using a Mac with an M1 chip, you already know things arenā€™t always straightforwardā€¦

šŸ§± First steps

I started by pulling the official image gvenzl/oracle-xe:21-slim. I knew Oracle XE doesnā€™t have native ARM64 support for Docker, so I had to run it as AMD64 using Rosetta or Colima.

Here was my first docker-compose.yml:

services:
  oracle-xe:
    image: gvenzl/oracle-xe:21-slim
    ports:
      - "1521:1521"
    environment:
      ORACLE_PASSWORD: test123

Everything seemed fineā€¦ until it wasnā€™t.

šŸ”„ First errors

ORA-12547: TNS:lost contact
DPI-1047: Cannot locate a 64-bit Oracle Client library

I found out that Go needs the Oracle Instant Client installed and linked at runtime to connect to Oracle databases.

So, I had to write a Dockerfile that included Instant Client:

COPY instantclient-basiclite-linux.x64-19.27.0.0.0dbru.zip /opt/oracle/instantclient.zip
...
ENV LD_LIBRARY_PATH=/opt/oracle/instantclient

But wait! The ZIP file couldnā€™t be downloaded directly with curl. Oracle requires login to access it.

šŸ”§ Tuning, tweaking, fixingā€¦

I added Delve to debug:

RUN go install github.com/go-delve/delve/cmd/dlv@latest

Then I configured VSCodeā€™s launch.json for remote attach:

{
  "type": "go",
  "request": "attach",
  "remotePath": "/app",
  "port": 40000,
  "host": "localhost"
}

And it worked!ā€¦ theoretically. When I launched the app with:

CMD ["dlv", "exec", "./app", "--headless", "--listen=:40000"]

I got the dreaded:

could not launch process: open /app/app: no such file or directory

The reason? I forgot to build the binary. I added go build -o app . in the Dockerfile and it finally worked.

šŸ§Ŗ Testing the connection

My Go code included the following connection string:

dsn := "system/test123@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=oracle-xe)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XE)))"

Using localhost didnā€™t work inside the container, but oracle-xe (the Docker service name) did.

My test query:

db.Query("SELECT 1 FROM DUAL")

šŸŽ‰ And it worked!

šŸ’” Key takeaways

  • On Apple Silicon, always use --platform linux/amd64
  • You canā€™t download Oracle Instant Client ZIPs with curl ā€” do it manually
  • Your binary must exist at /app/app for Delve to debug
  • Use service names like oracle-xe instead of localhost in Docker

āœ… Final result

My Go app connected successfully to Oracle XE in Docker and I was able to debug it line by line in VSCode with Delve.

It took way longer than expected. I faced obscure errors. But now, I can reproduce this setup in minutesā€¦ and so can you.

šŸ§  Want the full working repo?

Reach out or check out the packaged version of this project with Docker Compose + Oracle XE + Go + Delve + VSCode Debugging.

~devjaime