{"id":51797,"date":"2025-08-22T06:35:52","date_gmt":"2025-08-22T06:35:52","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=51797"},"modified":"2025-08-22T06:35:52","modified_gmt":"2025-08-22T06:35:52","slug":"complete-guide-for-socket-based-vs-tcp-based-application-connection","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/complete-guide-for-socket-based-vs-tcp-based-application-connection\/","title":{"rendered":"Complete Guide for Socket based vs TCP Based Application Connection"},"content":{"rendered":"\n

Here\u2019s a clear, end-to-end tutorial you can keep handy. It explains what \u201csocket-based\u201d vs \u201cTCP-based\u201d<\/strong> really means, how to tell which one you\u2019re using<\/strong>, and how to configure apps<\/strong> for each\u2014using our Keycloak \u2194 MySQL (XAMPP\/LAMPP)<\/strong> case as the running example.<\/p>\n\n\n\n

\n\n\n\n

Concept: Socket-based vs TCP-based<\/h1>\n\n\n\n

Two different \u201cpipes\u201d your app can use to talk to a service (like MySQL)<\/h2>\n\n\n\n
    \n
  • UNIX domain socket (UDS)<\/strong>\n
      \n
    • A special file<\/strong> on disk (e.g. \/opt\/lampp\/var\/mysql\/mysql.sock<\/code>).<\/li>\n\n\n\n
    • Only works on the same machine<\/strong>.<\/li>\n\n\n\n
    • Low overhead (skips the TCP\/IP stack) \u2192 slightly faster<\/strong> and very common on local servers.<\/li>\n\n\n\n
    • Access control via filesystem permissions<\/strong> + DB auth.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
    • TCP\/IP socket<\/strong>\n
        \n
      • A network endpoint like 127.0.0.1:3306<\/code> or 10.0.0.5:3306<\/code>.<\/li>\n\n\n\n
      • Works locally and remotely<\/strong>.<\/li>\n\n\n\n
      • A tad more overhead but universally supported by drivers and load balancers.<\/li>\n\n\n\n
      • Access control via firewall\/bind address<\/strong> + DB auth.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n

        Mental model<\/h3>\n\n\n
        [ App ] --(UDS file)--> [\/var\/<\/span>run\/...\/mysql.sock]  (local only)\n[ App ] --(TCP port)--> [127.0<\/span>.0<\/span>.1<\/span>:3306<\/span>]          (local\/remote)\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        \n
        Many servers (MySQL\/MariaDB, Nginx, Redis, etc.) can expose both<\/strong> at the same time.<\/p>\n<\/blockquote>\n\n\n\n
        \n\n\n\n
        How clients decide which one they\u2019re using<\/h1>\n\n\n\n
          \n
        • MySQL CLI<\/strong>\n
            \n
          • mysql -h 127.0.0.1 ...<\/code> \u2192 TCP<\/strong><\/li>\n\n\n\n
          • mysql -S \/path\/to\/mysql.sock ...<\/code> \u2192 UNIX socket<\/strong><\/li>\n\n\n\n
          • mysql -h localhost ...<\/code> \u2192 varies by distro\/driver (often socket<\/strong> on Linux)<\/li>\n<\/ul>\n<\/li>\n\n\n\n
          • JDBC (Java)<\/strong>\n
              \n
            • TCP<\/strong>: jdbc:mysql:\/\/127.0.0.1:3306\/db<\/code> (MySQL driver)<\/li>\n\n\n\n
            • Socket<\/strong> (Java): use a driver that supports it (e.g., MariaDB Connector\/J<\/strong>):
              jdbc:mariadb:\/\/localhost:3306\/db?localSocket=\/path\/to\/mysql.sock<\/code><\/li>\n\n\n\n
            • If you pass a UDS parameter the driver doesn\u2019t support, it falls back to TCP<\/strong>.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
            • Other client libs<\/strong> (quick cheatsheet below) often accept socketPath<\/code> \/ unix_socket<\/code> \/ unixSocket<\/code> parameters.<\/li>\n<\/ul>\n\n\n\n
              \n\n\n\n
              How to check which one is actually in use<\/h1>\n\n\n\n
              On the server<\/strong><\/h2>\n\n\n\n
                \n
              1. Is the service listening on TCP 3306<\/strong>?<\/li>\n<\/ol>\n\n\n
                ss -lntp | grep 3306<\/span>   # or: netstat -plnt | grep 3306<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                  \n
                • If you see LISTEN ... 127.0.0.1:3306<\/code> (or 0.0.0.0:3306<\/code>) \u2192 TCP is enabled<\/strong>.<\/li>\n\n\n\n
                • If nothing prints \u2192 likely socket-only<\/strong>.<\/li>\n<\/ul>\n\n\n\n
                    \n
                  1. Does the socket file<\/strong> exist?<\/li>\n<\/ol>\n\n\n
                    ls -l \/opt\/lampp\/var<\/span>\/mysql\/mysql.sock\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                      \n
                    • If present and MySQL is running \u2192 socket is enabled<\/strong>.<\/li>\n<\/ul>\n\n\n\n
                        \n
                      1. Ask MySQL itself:<\/li>\n<\/ol>\n\n\n
                        SHOW VARIABLES LIKE 'socket'<\/span>;\nSHOW VARIABLES LIKE 'port'<\/span>;\nSHOW VARIABLES LIKE 'bind_address'<\/span>;\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                        From the client\/app<\/strong><\/h2>\n\n\n\n
                          \n
                        1. Try both ways explicitly:<\/li>\n<\/ol>\n\n\n
                          # TCP<\/span>\n\/opt\/lampp\/bin\/mysql -h 127.0<\/span>.0<\/span>.1<\/span> -P 3306<\/span> -u USER -p DB -e \"SELECT 1;\"<\/span>\n\n# Socket<\/span>\n\/opt\/lampp\/bin\/mysql -S \/opt\/lampp\/var<\/span>\/mysql\/mysql.sock -u USER -p DB -e \"SELECT 1;\"<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                            \n
                          1. Logs & driver names<\/strong>\n
                              \n
                            • Java stack traces that mention **com.mysql.cj**...<\/code> = MySQL Connector\/J.<\/li>\n\n\n\n
                            • Java stack traces that mention **org.mariadb.jdbc**...<\/code> = MariaDB Connector\/J.<\/li>\n\n\n\n
                            • \u201cDriver does not support provided URL<\/strong>\u201d usually means the driver family doesn\u2019t match your JDBC URL scheme.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                            • See open files\/sockets<\/strong> of a running process:<\/li>\n<\/ol>\n\n\n
                              pid=$(pgrep -f 'org.keycloak.quarkus'<\/span> || true<\/span>)\n[ -n \"$pid\"<\/span> ] && sudo lsof -p \"$pid\"<\/span> | egrep 'mysql-connector-j|mariadb-java-client|mysql.sock|TCP'<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                              \n\n\n\n
                              Configure the server<\/strong> for each mode (MySQL\/MariaDB)<\/h1>\n\n\n\n
                              File: \/opt\/lampp\/etc\/my.cnf<\/code> (XAMPP\/LAMPP), under [mysqld]<\/code>:<\/p>\n\n\n\n
                              Enable \/ tune UNIX socket<\/strong><\/h2>\n\n\n
                              socket=\/opt\/lampp\/var<\/span>\/mysql\/mysql.sock\n# (this is default in XAMPP; usually already set)<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                              Restart:<\/p>\n\n\n
                              sudo \/opt\/lampp\/lampp restartmysql\n<\/code><\/span><\/pre>\n\n\n
                              Enable TCP<\/strong> listening<\/h2>\n\n\n
                              bind-address=127.0<\/span>.0<\/span>.1<\/span>   # or 0.0.0.0 if remote access is needed<\/span>\n# ensure there is NO 'skip-networking'<\/span>\nport=3306<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                              Restart & verify:<\/p>\n\n\n
                              sudo \/opt\/lampp\/lampp restartmysql\nss -lntp | grep 3306\n<\/code><\/span><\/pre>\n\n\n
                              \n\n\n\n
                              Configure applications<\/strong> for each mode<\/h1>\n\n\n\n
                              Below are proven patterns (including the exact ones you used today).<\/p>\n\n\n\n
                              Keycloak (Quarkus 17+)<\/h2>\n\n\n\n
                              A) TCP<\/strong> (production-friendly)<\/h3>\n\n\n
                              # conf\/keycloak.conf<\/span>\ndb=mysql\ndb-url=jdbc:mysql:\/\/127.0.0.1:3306\/keycloak_db?useSSL=false&allowPublicKeyRetrieval=true<\/span>\ndb-username=keycloak\n# put the password in env to avoid parsing issues with '#'<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n
                              export<\/span> KC_DB_PASSWORD='Strong#Passw0rd!'<\/span>\nbin\/kc.sh build\nbin\/kc.sh start --optimized\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                              B) UNIX socket<\/strong> (local same-host; requires driver that supports it)<\/h3>\n\n\n\n
                              Use MariaDB Connector\/J<\/strong> (already present in your install):<\/p>\n\n\n
                              # conf\/keycloak.conf<\/span>\ndb=mariadb\ndb-url=jdbc:mariadb:\/\/localhost:3306\/keycloak_db?localSocket=\/opt\/lampp\/var\/mysql\/mysql.sock<\/span>\ndb-username=root\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n
                              export<\/span> KC_DB_PASSWORD='Hs?gb?S345?3#s'<\/span>\nbin\/kc.sh build\nbin\/kc.sh start-dev\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                              \n
                              Why your earlier fix worked: setting KC_DB=mariadb<\/code> + jdbc:mariadb:\/\/...localSocket=...<\/code> made Keycloak load the MariaDB<\/strong> driver, which does<\/strong> speak UNIX sockets natively.<\/p>\n<\/blockquote>\n\n\n\n
                              \n\n\n\n
                              PHP (PDO)<\/h2>\n\n\n
                              \/\/ TCP<\/span>\n$pdo = new<\/span> PDO('mysql:host=127.0.0.1;port=3306;dbname=keycloak_db'<\/span>, 'user'<\/span>, 'pass'<\/span>);\n\n\/\/ UNIX socket<\/span>\n$pdo = new<\/span> PDO('mysql:unix_socket=\/opt\/lampp\/var\/mysql\/mysql.sock;dbname=keycloak_db'<\/span>, 'user'<\/span>, 'pass'<\/span>);\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                              Node.js (mysql2)<\/h2>\n\n\n
                              \/\/ TCP<\/span>\ncreateConnection({ host<\/span>: '127.0.0.1'<\/span>, port<\/span>: 3306<\/span>, user<\/span>: 'user'<\/span>, password<\/span>: 'pass'<\/span>, database<\/span>: 'keycloak_db'<\/span> });\n\n\/\/ UNIX socket<\/span>\ncreateConnection({ socketPath<\/span>: '\/opt\/lampp\/var\/mysql\/mysql.sock'<\/span>, user<\/span>: 'user'<\/span>, password<\/span>: 'pass'<\/span>, database<\/span>: 'keycloak_db'<\/span> });\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                              Python (PyMySQL \/ mysqlclient)<\/h2>\n\n\n
                              # TCP<\/span>\npymysql.connect(host='127.0.0.1'<\/span>, port=3306<\/span>, user='user'<\/span>, password='pass'<\/span>, db='keycloak_db'<\/span>)\n\n# UNIX socket<\/span>\npymysql.connect(unix_socket='\/opt\/lampp\/var\/mysql\/mysql.sock'<\/span>, user='user'<\/span>, password='pass'<\/span>, db='keycloak_db'<\/span>)\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                              Go (go-sql-driver\/mysql)<\/h2>\n\n\n
                              \/\/ TCP<\/span>\ndsn<\/span> := \"user:pass@tcp(127.0.0.1:3306)\/keycloak_db?parseTime=true\"<\/span>\n\n\/\/ UNIX socket<\/span>\ndsn<\/span> := \"user:pass@unix(\/opt\/lampp\/var\/mysql\/mysql.sock)\/keycloak_db?parseTime=true\"<\/span>\ndb, _<\/span> := sql.Open(\"mysql\"<\/span>, dsn)\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                              \n\n\n\n
                              Decision guide: which should I use?<\/h1>\n\n\n\n
                                \n
                              • Use UNIX socket<\/strong> when:\n
                                  \n
                                • The app and DB are on the same host<\/strong>, and you want simplicity + a tiny perf edge<\/strong>.<\/li>\n\n\n\n
                                • Your driver supports it easily (e.g., MariaDB Connector\/J).<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                                • Use TCP<\/strong> when:\n
                                    \n
                                  • You might run the DB remotely, in containers, or behind a proxy<\/strong>.<\/li>\n\n\n\n
                                  • You need universal compatibility and predictable behavior across drivers.<\/li>\n\n\n\n
                                  • You want to use firewalls<\/strong>, VPCs<\/strong>, or TLS on the wire<\/strong>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n
                                    \n\n\n\n
                                    Common errors \u2192 what they mean \u2192 how to fix<\/h1>\n\n\n\n
                                    Error\/Log text<\/th>Meaning<\/th>Fix<\/th><\/tr><\/thead>
                                    Connection refused<\/code><\/td>App tried TCP<\/strong>, but nothing is listening on that IP:port<\/td>Enable TCP (bind-address<\/code>, port<\/code>), or switch app to socket URL<\/td><\/tr>
                                    Communications link failure<\/code><\/td>Can\u2019t reach server over TCP (firewall\/offline\/bad host)<\/td>Verify ss -lntp<\/code>, network path, host\/port<\/td><\/tr>
                                    Driver does not support provided URL<\/code><\/td>Driver family mismatched with URL (MySQL vs MariaDB)<\/td>Align: db=mysql<\/code> + jdbc:mysql:\/\/...<\/code> or<\/strong> db=mariadb<\/code> + jdbc:mariadb:\/\/...<\/code><\/td><\/tr>
                                    Access denied for user<\/code><\/td>Auth\/host rules don\u2019t match<\/td>Ensure grants match the host: 'user'@'127.0.0.1'<\/code> for TCP; 'user'@'localhost'<\/code> often for socket<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                    \n\n\n\n
                                    One-shot diagnostic script<\/strong> (copy-paste)<\/h1>\n\n\n\n
                                    This tells you, in plain English, which paths are available and which work:<\/p>\n\n\n
                                    #!\/usr\/bin\/env bash<\/span>\nSOCK=\"\/opt\/lampp\/var\/mysql\/mysql.sock\"<\/span>\nDB=\"keycloak_db\"<\/span>; U=\"root\"<\/span>; H=\"127.0.0.1\"<\/span>; P=3306<\/span>\n\necho<\/span> \"=== Server-side checks ===\"<\/span>\nif<\/span> ss -lntp | grep -q \":$P \"<\/span>; then\n  echo<\/span> \"TCP: MySQL is listening on $H:$P\"<\/span>\nelse<\/span>\n  echo<\/span> \"TCP: Nothing listening on port $P\"<\/span>\nfi\n\nif<\/span> [ -S \"$SOCK\"<\/span> ]; then\n  echo<\/span> \"UDS: Socket exists at $SOCK\"<\/span>\nelse<\/span>\n  echo<\/span> \"UDS: Socket file not found at $SOCK\"<\/span>\nfi\n\necho<\/span> \"=== Client connectivity tests ===\"<\/span>\nif<\/span> \/opt\/lampp\/bin\/mysql -h \"$H\"<\/span> -P \"$P\"<\/span> -u \"$U\"<\/span> -e \"SELECT 1;\"<\/span> >\/dev\/null<\/span> 2<\/span>>&1<\/span>; then\n  echo<\/span> \"TCP: Client can connect to $H:$P as $U\"<\/span>\nelse<\/span>\n  echo<\/span> \"TCP: Client CANNOT connect to $H:$P as $U\"<\/span>\nfi\n\nif<\/span> [ -S \"$SOCK\"<\/span> ]; then\n  if<\/span> \/opt\/lampp\/bin\/mysql -S \"$SOCK\"<\/span> -u \"$U\"<\/span> -e \"SELECT 1;\"<\/span> >\/dev\/null<\/span> 2<\/span>>&1<\/span>; then\n    echo<\/span> \"UDS: Client can connect via $SOCK as $U\"<\/span>\n  else<\/span>\n    echo<\/span> \"UDS: Client CANNOT connect via $SOCK as $U\"<\/span>\n  fi\nfi\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                                    \n\n\n\n
                                    Case study (what we fixed today)<\/h1>\n\n\n\n
                                      \n
                                    • Your MySQL (XAMPP) was effectively socket-only<\/strong> \u2192 TCP attempts from Keycloak failed with Connection refused<\/code>.<\/li>\n\n\n\n
                                    • Switching Keycloak to MariaDB Connector\/J<\/strong> and using
                                      jdbc:mariadb:\/\/localhost:3306\/keycloak_db?localSocket=\/opt\/lampp\/var\/mysql\/mysql.sock<\/code>
                                      worked immediately.<\/li>\n\n\n\n
                                    • Key insight: Match the driver family to the URL<\/strong>, and be explicit<\/strong> about socket vs TCP.<\/li>\n<\/ul>\n\n\n\n
                                      \n\n\n\n
                                      Quick reference (cheat sheet)<\/h2>\n\n\n\n
                                        \n
                                      • Check TCP<\/strong>: ss -lntp | grep 3306<\/code><\/li>\n\n\n\n
                                      • Check socket<\/strong>: ls -l \/opt\/lampp\/var\/mysql\/mysql.sock<\/code><\/li>\n\n\n\n
                                      • Force TCP (CLI)<\/strong>: mysql -h 127.0.0.1 -P 3306 ...<\/code><\/li>\n\n\n\n
                                      • Force socket (CLI)<\/strong>: mysql -S \/path\/to\/mysql.sock ...<\/code><\/li>\n\n\n\n
                                      • Keycloak TCP<\/strong>: db=mysql<\/code> + jdbc:mysql:\/\/127.0.0.1:3306\/...<\/code><\/li>\n\n\n\n
                                      • Keycloak socket<\/strong>: db=mariadb<\/code> + jdbc:mariadb:\/\/localhost:3306\/...localSocket=...<\/code><\/li>\n\n\n\n
                                      • Env beats file<\/strong>: CLI > ENV > keycloak.conf<\/code><\/li>\n<\/ul>\n\n\n\n
                                        \n\n\n\n
                                        <\/p>\n","protected":false},"excerpt":{"rendered":"
                                        Here\u2019s a clear, end-to-end tutorial you can keep handy. It explains what \u201csocket-based\u201d vs \u201cTCP-based\u201d really means, how to tell which one you\u2019re using, and how to configure apps for… <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-51797","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51797","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=51797"}],"version-history":[{"count":1,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51797\/revisions"}],"predecessor-version":[{"id":51798,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51797\/revisions\/51798"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=51797"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=51797"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=51797"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}