|
| 1 | +## Recommendation |
| 2 | + |
| 3 | +For production deployments, we recommend using an external [PostgreSQL](https://www.postgresql.org/) database (version 13 or higher). |
| 4 | + |
| 5 | +## Basic configuration |
| 6 | + |
| 7 | +Before starting the Coder server, prepare the database server. Create a role and a database. |
| 8 | +Remember that the role must have access to the created database. |
| 9 | + |
| 10 | +With `psql`: |
| 11 | + |
| 12 | +```sql |
| 13 | +CREATE ROLE coder LOGIN SUPERUSER PASSWORD 'secret42'; |
| 14 | +``` |
| 15 | + |
| 16 | +With `psql -U coder`: |
| 17 | + |
| 18 | +```sql |
| 19 | +CREATE DATABASE coder; |
| 20 | +``` |
| 21 | + |
| 22 | +Coder configuration is defined via [environment variables](../admin/configure.md). |
| 23 | +The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable. |
| 24 | + |
| 25 | +```sh |
| 26 | +export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable" |
| 27 | +``` |
| 28 | + |
| 29 | +## Custom schema |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +With `psql -U coder`: |
| 34 | + |
| 35 | +```sql |
| 36 | +CREATE SCHEMA myschema; |
| 37 | +``` |
| 38 | + |
| 39 | +Once the schema is created, you can list all schemas with `\dn`: |
| 40 | + |
| 41 | +``` |
| 42 | + List of schemas |
| 43 | + Name | Owner |
| 44 | +-----------+---------- |
| 45 | + myschema | coder |
| 46 | + public | postgres |
| 47 | +(2 rows) |
| 48 | +``` |
| 49 | + |
| 50 | +In this case the database client requires the modified connection string: |
| 51 | + |
| 52 | +```sh |
| 53 | +export CODER_PG_CONNECTION_URL="postgres://coder@localhost/coder?password=secret42&sslmode=disable&search_path=myschema" |
| 54 | +``` |
| 55 | + |
| 56 | +The `search_path` parameter determines the order of schemas in which they are visited while looking for a specific table. |
| 57 | +The first schema named in the search path is called the current schema. By default `search_path` defines the following schemas: |
| 58 | + |
| 59 | +```sql |
| 60 | +SHOW search_path; |
| 61 | + |
| 62 | +search_path |
| 63 | +-------------- |
| 64 | + "$user", public |
| 65 | +``` |
| 66 | + |
| 67 | +Using the `search_path` in the connection string corresponds to the following `psql` command: |
| 68 | + |
| 69 | +```sql |
| 70 | +SET search_path TO myschema; |
| 71 | +``` |
| 72 | + |
| 73 | +## Troubleshooting |
| 74 | + |
| 75 | +### Coder server fails startup with "current_schema: converting NULL to string is unsupported" |
| 76 | + |
| 77 | +Please make sure that the schema selected in the connection string `...&search_path=myschema` exists |
| 78 | +and the role has granted permissions to access it. The schema should be present on this listing: |
| 79 | + |
| 80 | +```sh |
| 81 | +psql -U coder -c '\dn' |
| 82 | +``` |
| 83 | + |
| 84 | +## Next steps |
| 85 | + |
| 86 | +- [Quickstart](../quickstart.md) |
| 87 | +- [Configuring Coder](../admin/configure.md) |
| 88 | +- [Templates](../templates.md) |
0 commit comments