Files
coder/docs/tutorials/external-database.md
T
Nick Vigilante 58d19d78c5 feat: enable Coder.Please Vale rule (#30789)
Depends on #30782.

Adds `Coder.Please`, a Vale rule that enforces [Leave out
"please"](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#leave-out-please).

- Flags `\bplease\b`, ignoring case.
- Severity: `warning`. Scope: `docs/**` except
`docs/.style/style-guide/**`.
- Baseline: 31 findings in 24 pages (23 hand-written plus the generated
configuration reference), 0 after cleanup.
- Code spans and fenced code blocks are skipped by Vale, so quoted
product text such as `Please try again later` stays untouched, as the
guide asks.

## Commits

1. `docs: leave "please" out of instructions`: rewrites each use as a
direct imperative and keeps the meaning.
   It also fixes the one generated page that had a finding.
`docs/admin/setup/configuration-reference.md` comes from the telemetry
group description in `codersdk/deployment.go`, so the cleanup edits that
source and the golden files (`cli/testdata/coder_server_--help.golden`,
`cli/testdata/server-config.yaml.golden`,
`enterprise/cli/testdata/coder_server_--help.golden`) regenerated with
`go test -update`.
2. `feat(docs/.style): enable Coder.Please Vale rule`: adds the rule,
flips the footer to enforced, adds the checks-table row, and updates the
coverage counts.

No `.vale.ini` change is needed, and no generated page is excluded.

Linear: DOCS-1281

<details>
<summary>Decision log</summary>

- An `existence` rule with one `\bplease\b` token. Word boundaries keep
`pleasant` and `displeasing` out.
- `warning` rather than `error`, because a quoted product message can
legitimately contain the word outside code font.
- Generated pages: fixed in Go source instead of excluded, because only
one string was affected and the text reads better without it.
- URL query strings such as `body=please+enter+your+request+here` aren't
flagged, because Vale skips link destinations.
- The README sentence about rows, checks, and sections moves from 7, 10,
and 9 to 8, 11, and 10 for the new row.

Test cases (fixtures under `/tmp/please-test/`, not committed), run with
LF and CRLF line endings, 6 findings each:

- Flagged: sentence-initial `Please`, trailing `, please.`, `PLEASE`, a
blockquote, a list item, a heading.
- Not flagged: a code span containing `Please try again later`, a fenced
code block containing `Please install curl`, `pleasant`, `displeasing`.

Checks:

- `vale --output=line docs/` reports 0 `Coder.Please` findings.
- `go run ./scripts/styleclaims` passes.
- The pre-commit hooks pass on both commits (gen, `lint/go`, `lint/ts`,
markdown, emdash, style-claims, typos).
- `go test ./cli -run 'Test(CommandHelp|ServerYAML)'` and `go test
./enterprise/cli -run TestEnterpriseCommandHelp` pass with the updated
golden files.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-10-23 21:18:34 -07:00

2.2 KiB

title
title
Use Coder with an external database

Recommendation

For production deployments, we recommend using an external PostgreSQL database (version 13 or higher).

Basic configuration

Before starting the control plane, prepare the database server by creating a role and a database. Remember that the role must have access to the created database.

With psql:

CREATE ROLE coder LOGIN SUPERUSER PASSWORD 'secret42';

With psql -U coder:

CREATE DATABASE coder;

Coder configuration is defined via environment variables. The database client requires the connection string provided via the CODER_PG_CONNECTION_URL variable.

export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"

Custom schema

For installations with elevated security requirements, it's advised to use a separate schema instead of the public one.

With psql -U coder:

CREATE SCHEMA myschema;

Once the schema is created, you can list all schemas with \dn:

List of schemas
 Name      | Owner
-----------+----------
 myschema  | coder
 public    | postgres
(2 rows)

In this case the database client requires the modified connection string:

export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema"

The search_path parameter determines the order of schemas in which they are visited while looking for a specific table. The first schema named in the search path is called the current schema. By default search_path defines the following schemas:

SHOW search_path;

search_path
--------------
 "$user", public

Using the search_path in the connection string corresponds to the following psql command:

ALTER ROLE coder SET search_path = myschema;

Troubleshooting

coder server fails startup with "current_schema: converting NULL to string is unsupported"

Make sure that the schema selected in the connection string ...&search_path=myschema exists and the role has granted permissions to access it. The schema should be present on this listing:

psql -U coder -c '\dn'