music on atproto
plyr.fm
zzstoatzz.io
1# neon database configuration
2
3configuration guide for connecting to neon postgres databases.
4
5## overview
6
7plyr.fm uses [neon](https://neon.tech) for all database environments (dev, staging, prod). neon uses a specialized proxy architecture that requires specific connection settings for security and reliability.
8
9## connection string format
10
11the connection string must use the **psycopg** driver and include specific ssl parameters.
12
13### format
14```bash
15postgresql+psycopg://<user>:<password>@<host>/<dbname>?sslmode=require&channel_binding=require
16```
17
18### key components
19
201. **driver**: `postgresql+psycopg://`
21 - **required**: we must use the `psycopg` (v3) driver, not `asyncpg`.
22 - **reason**: `asyncpg` does not support the `channel_binding` parameter, which is required for strict ssl verification with neon.
23
242. **ssl mode**: `sslmode=require`
25 - forces ssl encryption for the connection.
26
273. **channel binding**: `channel_binding=require`
28 - ensures the connection is not intercepted (mitm protection).
29 - uses SCRAM-SHA-256-PLUS authentication.
30
31## environment variables
32
33set the `DATABASE_URL` in your `.env` file:
34
35```bash
36# development (example)
37DATABASE_URL=postgresql+psycopg://<user>:<password>@<host>/<dbname>?sslmode=require&channel_binding=require
38```
39
40## troubleshooting
41
42### typeerror: connect() got an unexpected keyword argument 'channel_binding'
43
44**cause**: using `postgresql+asyncpg://` with `channel_binding=require`.
45**fix**: change the scheme to `postgresql+psycopg://`.
46
47### connection refused / ssl errors
48
49**cause**: missing `sslmode=require` or `channel_binding=require`.
50**fix**: ensure both parameters are present in the query string.
51
52## references
53
54- [neon documentation](https://neon.tech/docs)
55- [sqlalchemy psycopg dialect](https://docs.sqlalchemy.org/en/20/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg)