---
title: "Unix Domain Sockets Quickstart"
---

# Unix Domain Sockets Quickstart

**Build:** Unix only (Linux / macOS) — Windows builds are TCP-only
**Endpoints:** `--pg-socket-dir <DIR>` (PostgreSQL), `--mysql-socket <PATH>` (MySQL)

---

## UVP

When your client lives on the same host as the database, the TCP loopback round-trip is paid overhead. HeliosDB Nano can listen on Unix domain sockets for both the PostgreSQL and MySQL wire protocols — `psql -h /tmp` connects via the libpq default, and PHP `mysqli` / WordPress with `DB_HOST=':/tmp/heliosdb-mysql.sock'` works without any TCP. **Lower latency, no port conflicts, file-permission ACLs instead of firewall rules.** Perfect for embedded same-host deployments.

---

## 1. Start with Both Sockets

```bash
heliosdb-nano start --memory \
  --pg-socket-dir /tmp \
  --mysql --mysql-socket /tmp/heliosdb-mysql.sock
```

The output prints the connection one-liners you'll use:

```
    psql (UDS):  psql -h /tmp -p 5432
    mysql (UDS): mysql --socket=/tmp/heliosdb-mysql.sock
```

What the flags do:

| Flag | Effect |
|------|--------|
| `--pg-socket-dir /tmp` | Bind a Unix listener at `/tmp/.s.PGSQL.5432` (libpq's standard path: `<dir>/.s.PGSQL.<port>`). The directory is created if missing. |
| `--mysql --mysql-socket /tmp/heliosdb-mysql.sock` | Bind a Unix listener at the exact path you specify. The MySQL TCP listener (`--mysql`) is independent — pass `--mysql-socket` alone if you want UDS-only. |

Both sockets get permissive `0o777` mode at startup so any local user can connect (file permissions are the access-control layer, not the wire protocol).

Stale socket files from a previous run are removed before bind. On clean shutdown (Ctrl-C) the files are unlinked again.

---

## 2. Connect with `psql`

```bash
psql -h /tmp
```

libpq treats any host that starts with `/` as a directory containing the socket file. The default port is `5432`, so `psql -h /tmp` resolves to `/tmp/.s.PGSQL.5432`. Override with `-p 5433` for a non-default port.

Same connection from a libpq app:

```python
import psycopg2
conn = psycopg2.connect(host="/tmp", dbname="postgres", user="postgres")
```

```bash
PGHOST=/tmp psql
PGHOST=/tmp PGUSER=postgres python myapp.py
```

The `PGHOST` env var is libpq's official knob — most ORMs honour it.

---

## 3. Connect with `mysql`

```bash
mysql --socket=/tmp/heliosdb-mysql.sock
```

```
Welcome to the MySQL monitor.
Server version: 8.0.35-HeliosDB-Nano
mysql>
```

Or from a config file (`~/.my.cnf`):

```ini
[client]
socket = /tmp/heliosdb-mysql.sock
user   = root
```

…and then `mysql` with no flags works.

---

## 4. PHP `mysqli` (Same-Host Apps)

```php
<?php
// The leading colon tells mysqli the value is a socket path.
$db = new mysqli("localhost:/tmp/heliosdb-mysql.sock", "root", "", "mydb");

// Or pass the path explicitly as the socket argument:
$db = new mysqli(null, "root", "", "mydb", 0, "/tmp/heliosdb-mysql.sock");

$result = $db->query("SELECT VERSION()");
print_r($result->fetch_row());
```

For WordPress, set `DB_HOST` in `wp-config.php`:

```php
define('DB_HOST', 'localhost:/tmp/heliosdb-mysql.sock');
```

See [WORDPRESS_DROP_IN](https://www.heliosdb.com/docs/nano/guides/tutorials/wordpress_drop_in_tutorial/).

---

## 5. Why Use Unix Sockets

- **Latency.** No TCP three-way handshake, no Nagle's algorithm, no loopback IP stack — just a kernel pipe.
- **No port conflicts.** Run two HeliosDB instances on the same host with different socket paths.
- **File-system ACLs.** Restrict access by chmod / chown on the socket file. The 0o777 default is permissive; chmod to `0o660` and chown to your app user for production.
- **No `bind: address already in use` flakes** during fast restart cycles in CI.
- **Container-friendly** when you mount a tmpfs or hostPath shared between containers in the same pod / compose project.

---

## 6. Coexistence with TCP

The Unix listeners are **additional** to TCP, not a replacement:

```bash
# Start with both TCP and UDS:
heliosdb-nano start --memory \
  --port 5432 --pg-socket-dir /tmp \
  --mysql --mysql-listen 127.0.0.1:3306 --mysql-socket /tmp/heliosdb-mysql.sock
```

Now any of the four addresses work:

- `psql -h 127.0.0.1 -p 5432` (PG TCP)
- `psql -h /tmp -p 5432` (PG UDS)
- `mysql -h 127.0.0.1 -P 3306` (MySQL TCP)
- `mysql --socket=/tmp/heliosdb-mysql.sock` (MySQL UDS)

All four read and write the same data.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory` | Server not started with `--pg-socket-dir` | Add the flag and restart |
| `mysqli::__construct: No such file or directory` | Wrong path in `$socket` argument | Verify with `ls -l /tmp/heliosdb-mysql.sock` |
| `Permission denied` on connect | Custom umask narrowed the socket mode | Confirm with `ls -l`; chmod to 0660 + chown to your app user as needed |
| Socket file persists after crash | Server didn't exit cleanly | Manually `rm /tmp/heliosdb-mysql.sock` (or rely on the next `start` to clear it) |
| Windows: `--pg-socket-dir` is silently ignored | Unix sockets unavailable on Windows | Use TCP on Windows |

---

## Where Next

- [WORDPRESS_DROP_IN](https://www.heliosdb.com/docs/nano/guides/tutorials/wordpress_drop_in_tutorial/) — same-host PHP / WordPress over MySQL UDS.
- [MYSQL_WIRE](https://www.heliosdb.com/docs/nano/guides/tutorials/mysql_wire_tutorial/) — full MySQL protocol coverage.
- [DRIZZLE_PRISMA_COMPAT](https://www.heliosdb.com/docs/nano/guides/tutorials/drizzle_prisma_compat/) — TypeScript ORMs over the PostgreSQL wire (TCP or UDS).