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.*
88 lines
2.2 KiB
Markdown
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'
|
|
```
|