Skip to content
HeliosDB Nano

Unix Domain Sockets Quickstart

Unix Domain Sockets Quickstart

Available since: v3.14.0 (2026-04-20) — first shipped alongside the Drizzle compat milestone 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

Terminal window
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:

FlagEffect
--pg-socket-dir /tmpBind 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.sockBind 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

Terminal window
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:

import psycopg2
conn = psycopg2.connect(host="/tmp", dbname="postgres", user="postgres")
Terminal window
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

Terminal window
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):

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

…and then mysql with no flags works.

4. PHP mysqli (Same-Host Apps)

<?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:

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

See WORDPRESS_DROP_IN.

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:

Terminal window
# 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

SymptomCauseFix
psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directoryServer not started with --pg-socket-dirAdd the flag and restart
mysqli::__construct: No such file or directoryWrong path in $socket argumentVerify with ls -l /tmp/heliosdb-mysql.sock
Permission denied on connectCustom umask narrowed the socket modeConfirm with ls -l; chmod to 0660 + chown to your app user as needed
Socket file persists after crashServer didn’t exit cleanlyManually rm /tmp/heliosdb-mysql.sock (or rely on the next start to clear it)
Windows: --pg-socket-dir is silently ignoredUnix sockets unavailable on WindowsUse TCP on Windows

Where Next