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

88 lines
2.2 KiB
Markdown

---
title: Use Coder with an external database
---
## Recommendation
For production deployments, we recommend using an external [PostgreSQL](https://www.postgresql.org/) 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`:
```sql
CREATE ROLE coder LOGIN SUPERUSER PASSWORD 'secret42';
```
With `psql -U coder`:
```sql
CREATE DATABASE coder;
```
Coder configuration is defined via [environment variables](../admin/setup/index.md).
The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable.
```sh
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](https://www.postgresql.org/docs/current/ddl-schemas.html) instead of the public one.
With `psql -U coder`:
```sql
CREATE SCHEMA myschema;
```
Once the schema is created, you can list all schemas with `\dn`:
```txt
List of schemas
Name | Owner
-----------+----------
myschema | coder
public | postgres
(2 rows)
```
In this case the database client requires the modified connection string:
```sh
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:
```sql
SHOW search_path;
search_path
--------------
"$user", public
```
Using the `search_path` in the connection string corresponds to the following `psql` command:
```sql
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:
```sh
psql -U coder -c '\dn'
```