Connections

SeeKi connects to PostgreSQL. You give it a single connection string, and it does the rest — pooling, schema introspection, reading rows on demand. This page covers the shape of that string, how to break it apart when a URL is awkward, and how to size the pool.

The simplest case

A database running on your laptop, one user, default port:

[database]
kind = "postgres"
url = "postgres://user:password@localhost:5432/mydb"
max_connections = 5

Paste that into seeki.toml, run ./seeki, and the grid should render within a second or two.

The pieces of a connection string

PostgreSQL URLs follow a fixed shape. SeeKi accepts the standard form used by psql, every PostgreSQL driver, and most other tools.

postgres://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require

Piece	What to put	Example
`USER`	Database login name. Prefer a read-only user.	`reporting`
`PASSWORD`	That user’s password. URL-encode any special characters.	`s3cret%21`
`HOST`	Hostname or IP of the database server.	`db.internal`
`PORT`	TCP port. PostgreSQL defaults to `5432`.	`5432`
`DATABASE`	Name of the database (not the server, the database inside it).	`autoconnect`
`sslmode`	Optional query parameter. Use `require` for most cloud providers.	`require`

Cloud providers

Most hosted PostgreSQL services hand you a ready-made URL. Drop it in verbatim.

AWS RDS — copy the endpoint from the RDS console, prepend postgres://user:pass@, append /dbname?sslmode=require.
Supabase — Project settings → Database → Connection string. Use the Session pooler URL for SeeKi.
Neon — copy the pooled connection string from the dashboard.
Google Cloud SQL / Azure — same shape; enable SSL in the URL with ?sslmode=require.

When the URL won’t paste cleanly

Sometimes the password contains a @ or your ops team hands you each piece separately. In practice the fix is URL-encoding, not a different config shape — SeeKi takes exactly one field, database.url.

Character in password	Encode as
`@`	`%40`
`:`	`%3A`
`/`	`%2F`
`#`	`%23`
(space)	`%20`

If the database lives behind a bastion host you can’t reach directly, skip ahead to SSH tunneling.

Pool size

max_connections controls how many database connections SeeKi may open at once. The default of 5 is right for a single person browsing, and close to right for a small shared instance.

Who is using this SeeKi?	Suggested `max_connections`
One person, local laptop	`5` (the default)
A small team sharing one instance	`10` – `20`
Dozens of concurrent readers	`30`+, and check your database’s own connection limit first

Test the connection

Start SeeKi and watch the terminal. A healthy startup looks like this:

INFO seeki: Loaded config from ./seeki.toml
INFO seeki: Connecting to database...
INFO seeki: Connected to database
INFO seeki: SeeKi listening on http://127.0.0.1:3141

If the connection fails, SeeKi prints the underlying error and stops. Common culprits: wrong password, wrong database name, the host is not reachable from this machine, or the database requires SSL and the URL doesn’t ask for it.

What’s next

SSH tunneling — reach a database that only a bastion can see.
Config reference — every field in seeki.toml.
Troubleshooting — what to try when the connection won’t land.