> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install a server for this tutorial

> Every lesson in this tutorial needs a running MySQL or VillageSQL server. Pick 1 of 3 ways to get one, then check that you can connect.

<Card title="VillageSQL is a drop-in replacement for MySQL with extensions." icon="database" href="/docs/mysql-8.4/stable/quickstart">
  All examples on this page work on VillageSQL. Install Now →
</Card>

You need a running server and a client that can talk to it. Any MySQL 8.4 or
later server works, and so does VillageSQL, which is MySQL with an extension
framework added. No lesson here uses an extension, so either one will do.

## Pick a way to run a server

| Way | Suits | Where to go |
| - | - | - |
| Docker | Trying it out and throwing it away | [MySQL on Docker](/docs/guides/mysql-on-docker) |
| The VillageSQL installer | A server you keep on your own machine | [Quickstart](/docs/mysql-8.4/stable/quickstart) |
| A server you already run | Anyone with MySQL 8.4 or later installed | Nothing to do |

Each of those pages ends with a running server. Come back here once you have
one.

## Get a client

This tutorial drives the server with `mysql`, the command line client. Where it
comes from depends on which way you went:

* **The installer or an existing server.** The client came with the server, so
  you already have it.
* **Docker.** The client lives inside the container, not on your machine. Reach
  it with `docker exec -it CONTAINER_NAME mysql -u root -p`, or install a client
  locally and connect over the port the container publishes.

## Check that you can connect

Run this, and press Return at the password prompt if `root` has no password:

```bash theme={null}
mysql -u root -p -e "SELECT VERSION();"
```

```text theme={null}
Enter password:
+-----------------------------------------+
| VERSION()                               |
+-----------------------------------------+
| 8.4.11-villagesql-0.0.7-dev-c857bdf32ce |
+-----------------------------------------+
```

Your version string will differ. What matters is that a version came back,
because that means the client reached the server and logged in.

## When it does not connect

Both of the errors below mean the client never reached a server, so neither is
about your password. You can reproduce either one on a working setup by
pointing the client somewhere wrong.

A socket path with nothing behind it:

```bash theme={null}
mysql -S /tmp/mysql.sock.missing -u root -p -e "SELECT VERSION();"
```

```text theme={null}
Enter password:
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock.missing' (2)
```

A port with nothing listening on it:

```bash theme={null}
mysql -h 127.0.0.1 -P 3999 -u root -p -e "SELECT VERSION();"
```

```text theme={null}
Enter password:
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3999' (61)
```

The number in the trailing brackets is the operating system's own error number,
so it can differ between macOS and Linux. The missing-socket number is 2 on
both; the refused-connection number is 61 on macOS and 111 on Linux. The part to read is the socket path or
the host and port, because that tells you where the client looked. If that
location is wrong, correct it. If it is right, the server is not running.

## See also

* [Quickstart](/docs/mysql-8.4/stable/quickstart) — install VillageSQL and connect to it
* [MySQL on Docker](/docs/guides/mysql-on-docker) — run a server in a container
* [Common MySQL errors](/docs/guides/common-mysql-errors) — what the other connection errors mean