Barebones PostgreSQL TCP Client

A minimal TCP client written in TypeScript that connects directly to a PostgreSQL server over raw sockets.
It demonstrates how to:

• Establish a TCP connection to PostgreSQL
• Send the startup message
• Authenticate using SCRAM-SHA-256
• Accept user input, forward queries to the server, and print responses to STDOUT

⚠️ This project is for educational purposes only.
It does not implement the full PostgreSQL wire protocol and should not be used in production.

---

🚀 Getting Started

1. Download

Clone the repository and install the dependencies:

git clone https://github.com/darshil-2005/TCP_Client_PostgreSQL.git
cd TCP_Client_PostgreSQL
npm install

2. Testing with Docker (Optional)

If you don't have a local PostgreSQL server with SCRAM-SHA-256 password authentication enabled, you can easily spin one up using Docker to test the client:

# Spin up a PostgreSQL 15 instance
docker run --name my-postgres-test -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password -e POSTGRES_DB=database -p 5434:5432 -d postgres:15-alpine

# Wait a few seconds, then create a dummy table and insert test data
docker exec my-postgres-test psql -U user -d database -c "CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(50), age INT); INSERT INTO users (name, age) VALUES ('Alice', 30), ('Bob', 25);"

3. Run the Client

You can run the client using npm start. The client accepts command-line arguments to configure the connection. If none are provided, it falls back to default values.

# Run with default settings (localhost, 5432, user: user, db: database)
npm start

# Or run with custom flags
npm start -- -H localhost -p 5434 -U user -d database

Available Flags:

• -p, --port <number>: Port number (default: 5432)
• -H, --host <string>: Host (default: localhost)
• -U, --username <string>: Username (default: user)
• -d, --database <string>: Database (default: database)

Once connected, you will be greeted by the Darshil's client> prompt where you can execute queries like SELECT * FROM users;.

---

👤 Author

Darshil Gandhi

• GitHub: @darshil-2005

---