sql.DB as a Pool

## What `sql.Open` actually is `database/sql` is a thin, driver-agnostic layer. `sql.Open(driverName, dataSourceName)` returns `(*sql.DB, error)`, and the crucial thing to understand is what a `*sql.DB` is: **not a connection**, but a handle to a pool of connections that the package will open, reuse and retire on your behalf. Creating that handle requires no network activity at all, so `sql.Open` performs none. Concretely, `sql.Open` does roughly three things: 1. Looks `driverName` up in the package-level registry that drivers populate by calling `sql.Register(name, driver)` from their `init` function. If nothing registered that name you get an error along the lines of `sql: unknown driver "..."` — the classic symptom of a missing blank import of the driver package. 2. Gives the driver a chance to turn the DSN string into a reusable connector object, so the string is parsed once rather than per connection. Drivers that parse eagerly can report a malformed DSN here; many do not. 3. Allocates the pool bookkeeping and returns. No TCP dial, no TLS handshake, no authentication. The first connection is opened lazily, when something actually needs one. ## Why that surprises people Every other language's `connect()` you have used probably dialled immediately, so the instinct is to write: ```go db, err := sql.Open("mydriver", dsn) if err != nil { log.Fatal(err) // "the database is fine" } ``` and believe the database is fine. It is not: the server can be switched off, the credentials wrong, the DSN pointed at a database that does not exist, and this code prints nothing. The failure then surfaces much later and somewhere less convenient — inside the first request handler, as a query error that looks like an application bug. This is also why a health or readiness endpoint that only checks "did the process start" will happily report success against a dead database. The process genuinely did start; it just never touched the server. ## Proving connectivity The explicit way to force the pool to open a connection is `Ping`: ```go ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err := db.PingContext(ctx); err != nil { return fmt.Errorf("database unreachable: %w", err) } ``` `PingContext` takes a connection from the pool — opening one if there are no idle connections — and asks the driver to verify it is alive, returning the connection afterwards. Prefer it over the context-free `Ping()`: without a deadline, a host that black-holes packets can leave startup hanging until the operating system's TCP timeout, which may be minutes. What a successful ping proves is narrow but real: at this instant, one connection could be established and authenticated against that DSN. It does not prove the schema is what you expect, that the account has the privileges your queries need, or that the next connection will succeed. If you want stronger evidence, run a cheap real query instead — for example a `SELECT` of a constant, or one row from a table you actually depend on. ## Where to put the check - **At startup**, immediately after `sql.Open`, with a bounded deadline. For a short-lived process this is what turns "silently did nothing" into a visible, non-zero exit. - **In a readiness check**, so an orchestrator stops sending traffic while the dependency is down. Give each ping its own short deadline derived from the incoming request's context. - **Not on every query.** Pinging before each statement doubles your round trips and still races: the connection can die between the ping and the query. `database/sql` already retries a query on a fresh connection when a pooled one turns out to be dead, so defensive pinging buys you very little. ## Handling `sql.Open`'s error anyway Because it fires so rarely, `sql.Open`'s error is often ignored or, worse, discarded with `_`. Don't: it is exactly the signal that tells you the binary was built without the driver linked in, which is a build-time mistake worth failing loudly on. The two errors are complementary — `sql.Open`'s error means "this program cannot talk to this kind of database at all", and `PingContext`'s error means "this program cannot reach this particular database right now".