zzstoatzz.io
+55
docs/backend/database/neon.md
+55
docs/backend/database/neon.md
···
···
1
+
# neon database configuration
2
+
3
+
configuration guide for connecting to neon postgres databases.
4
+
5
+
## overview
6
+
7
+
plyr.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
+
11
+
the connection string must use the **psycopg** driver and include specific ssl parameters.
12
+
13
+
### format
14
+
```bash
15
+
postgresql+psycopg://<user>:<password>@<host>/<dbname>?sslmode=require&channel_binding=require
16
+
```
17
+
18
+
### key components
19
+
20
+
1. **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
+
24
+
2. **ssl mode**: `sslmode=require`
25
+
- forces ssl encryption for the connection.
26
+
27
+
3. **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
+
33
+
set the `DATABASE_URL` in your `.env` file:
34
+
35
+
```bash
36
+
# development (example)
37
+
DATABASE_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)