|
1 | 1 | # Environment Variables Reference |
2 | 2 |
|
3 | | -Complete list of environment variables recognized by `@pgpmjs/env` and `@constructive-io/graphql-env`. |
4 | | - |
5 | | -## PostgreSQL Connection (`opts.pg`) |
6 | | - |
7 | | -| Env Var | Config Key | Type | Description | |
8 | | -|---------|-----------|------|-------------| |
9 | | -| `PGHOST` | `pg.host` | string | PostgreSQL server hostname | |
10 | | -| `PGPORT` | `pg.port` | number | PostgreSQL server port | |
11 | | -| `PGUSER` | `pg.user` | string | PostgreSQL username | |
12 | | -| `PGPASSWORD` | `pg.password` | string | PostgreSQL password | |
13 | | -| `PGDATABASE` | `pg.database` | string | Default database name | |
14 | | - |
15 | | -## Database Test/Connection Options (`opts.db`) |
16 | | - |
17 | | -| Env Var | Config Key | Type | Description | |
18 | | -|---------|-----------|------|-------------| |
19 | | -| `PGROOTDATABASE` | `db.rootDb` | string | Root database for admin operations | |
20 | | -| `PGTEMPLATE` | `db.template` | string | Template database for creating test DBs | |
21 | | -| `DB_PREFIX` | `db.prefix` | string | Prefix for generated database names | |
22 | | -| `DB_EXTENSIONS` | `db.extensions` | string[] | Comma-separated list of extensions to install | |
23 | | -| `DB_CWD` | `db.cwd` | string | Working directory for DB operations | |
24 | | -| `DB_CONNECTION_USER` | `db.connection.user` | string | Legacy connection user | |
25 | | -| `DB_CONNECTION_PASSWORD` | `db.connection.password` | string | Legacy connection password | |
26 | | -| `DB_CONNECTION_ROLE` | `db.connection.role` | string | Legacy connection role | |
27 | | -| `DB_CONNECTIONS_APP_USER` | `db.connections.app.user` | string | App-level connection user | |
28 | | -| `DB_CONNECTIONS_APP_PASSWORD` | `db.connections.app.password` | string | App-level connection password | |
29 | | -| `DB_CONNECTIONS_ADMIN_USER` | `db.connections.admin.user` | string | Admin connection user | |
30 | | -| `DB_CONNECTIONS_ADMIN_PASSWORD` | `db.connections.admin.password` | string | Admin connection password | |
31 | | - |
32 | | -## Server Options (`opts.server`) |
33 | | - |
34 | | -| Env Var | Config Key | Type | Description | |
35 | | -|---------|-----------|------|-------------| |
36 | | -| `PORT` | `server.port` | number | HTTP server port | |
37 | | -| `SERVER_HOST` | `server.host` | string | HTTP server host | |
38 | | -| `SERVER_TRUST_PROXY` | `server.trustProxy` | boolean | Trust proxy headers | |
39 | | -| `SERVER_ORIGIN` | `server.origin` | string | Server origin URL | |
40 | | -| `SERVER_STRICT_AUTH` | `server.strictAuth` | boolean | Strict authentication mode | |
41 | | - |
42 | | -## CDN / S3 Storage (`opts.cdn`) |
43 | | - |
44 | | -| Env Var | Config Key | Type | Description | |
45 | | -|---------|-----------|------|-------------| |
46 | | -| `BUCKET_PROVIDER` | `cdn.provider` | `'s3'` \| `'minio'` | Storage provider | |
47 | | -| `BUCKET_NAME` | `cdn.bucketName` | string | S3/MinIO bucket name | |
48 | | -| `AWS_REGION` | `cdn.awsRegion` | string | AWS region | |
49 | | -| `AWS_ACCESS_KEY` or `AWS_ACCESS_KEY_ID` | `cdn.awsAccessKey` | string | AWS access key | |
50 | | -| `AWS_SECRET_KEY` or `AWS_SECRET_ACCESS_KEY` | `cdn.awsSecretKey` | string | AWS secret key | |
51 | | -| `MINIO_ENDPOINT` | `cdn.minioEndpoint` | string | MinIO endpoint URL | |
52 | | - |
53 | | -## Deployment Options (`opts.deployment`) |
54 | | - |
55 | | -| Env Var | Config Key | Type | Description | |
56 | | -|---------|-----------|------|-------------| |
57 | | -| `DEPLOYMENT_USE_TX` | `deployment.useTx` | boolean | Wrap deployment in transaction | |
58 | | -| `DEPLOYMENT_FAST` | `deployment.fast` | boolean | Skip verification after deploy | |
59 | | -| `DEPLOYMENT_USE_PLAN` | `deployment.usePlan` | boolean | Use plan-based deployment | |
60 | | -| `DEPLOYMENT_CACHE` | `deployment.cache` | boolean | Enable deployment caching | |
61 | | -| `DEPLOYMENT_TO_CHANGE` | `deployment.toChange` | string | Deploy up to specific change | |
62 | | - |
63 | | -## Migration Options (`opts.migrations`) |
64 | | - |
65 | | -| Env Var | Config Key | Type | Description | |
66 | | -|---------|-----------|------|-------------| |
67 | | -| `MIGRATIONS_CODEGEN_USE_TX` | `migrations.codegen.useTx` | boolean | Wrap codegen migrations in transaction | |
68 | | - |
69 | | -## Jobs Configuration (`opts.jobs`) |
70 | | - |
71 | | -| Env Var | Config Key | Type | Description | |
72 | | -|---------|-----------|------|-------------| |
73 | | -| `JOBS_SCHEMA` | `jobs.schema.schema` | string | PostgreSQL schema for job tables | |
74 | | -| `JOBS_SUPPORT_ANY` | `jobs.worker.supportAny` / `jobs.scheduler.supportAny` | boolean | Accept any job type | |
75 | | -| `JOBS_SUPPORTED` | `jobs.worker.supported` / `jobs.scheduler.supported` | string[] | Comma-separated supported job types | |
76 | | -| `INTERNAL_GATEWAY_URL` | `jobs.gateway.gatewayUrl` | string | Internal gateway URL for job dispatch | |
77 | | -| `INTERNAL_JOBS_CALLBACK_URL` | `jobs.gateway.callbackUrl` | string | Callback URL for job completion | |
78 | | -| `INTERNAL_JOBS_CALLBACK_PORT` | `jobs.gateway.callbackPort` | number | Callback server port | |
79 | | - |
80 | | -## Error Output Options (`opts.errorOutput`) |
81 | | - |
82 | | -| Env Var | Config Key | Type | Description | |
83 | | -|---------|-----------|------|-------------| |
84 | | -| `PGPM_ERROR_QUERY_HISTORY_LIMIT` | `errorOutput.queryHistoryLimit` | number | Max query history in errors | |
85 | | -| `PGPM_ERROR_MAX_LENGTH` | `errorOutput.maxLength` | number | Max error message length | |
86 | | -| `PGPM_ERROR_VERBOSE` | `errorOutput.verbose` | boolean | Verbose error output | |
87 | | - |
88 | | -## SMTP Configuration (`opts.smtp`) |
89 | | - |
90 | | -| Env Var | Config Key | Type | Description | |
91 | | -|---------|-----------|------|-------------| |
92 | | -| `SMTP_HOST` | `smtp.host` | string | SMTP server hostname | |
93 | | -| `SMTP_PORT` | `smtp.port` | number | SMTP server port | |
94 | | -| `SMTP_SECURE` | `smtp.secure` | boolean | Use TLS | |
95 | | -| `SMTP_USER` | `smtp.user` | string | SMTP username | |
96 | | -| `SMTP_PASS` | `smtp.pass` | string | SMTP password | |
97 | | -| `SMTP_FROM` | `smtp.from` | string | Default from address | |
98 | | -| `SMTP_REPLY_TO` | `smtp.replyTo` | string | Default reply-to address | |
99 | | -| `SMTP_REQUIRE_TLS` | `smtp.requireTLS` | boolean | Require TLS connection | |
100 | | -| `SMTP_TLS_REJECT_UNAUTHORIZED` | `smtp.tlsRejectUnauthorized` | boolean | Reject unauthorized TLS certs | |
101 | | -| `SMTP_POOL` | `smtp.pool` | boolean | Use connection pooling | |
102 | | -| `SMTP_MAX_CONNECTIONS` | `smtp.maxConnections` | number | Max pooled connections | |
103 | | -| `SMTP_MAX_MESSAGES` | `smtp.maxMessages` | number | Max messages per connection | |
104 | | -| `SMTP_NAME` | `smtp.name` | string | SMTP client name | |
105 | | -| `SMTP_LOGGER` | `smtp.logger` | boolean | Enable SMTP logging | |
106 | | -| `SMTP_DEBUG` | `smtp.debug` | boolean | Enable SMTP debug output | |
107 | | - |
108 | | -## GraphQL-Specific Env Vars (from `@constructive-io/graphql-env`) |
109 | | - |
110 | | -These are only available when using `@constructive-io/graphql-env`. |
111 | | - |
112 | | -### Graphile Options (`opts.graphile`) |
113 | | - |
114 | | -| Env Var | Config Key | Type | Description | |
115 | | -|---------|-----------|------|-------------| |
116 | | -| `GRAPHILE_SCHEMA` | `graphile.schema` | string \| string[] | Comma-separated schema names to expose | |
117 | | - |
118 | | -### Feature Flags (`opts.features`) |
119 | | - |
120 | | -| Env Var | Config Key | Type | Default | Description | |
121 | | -|---------|-----------|------|---------|-------------| |
122 | | -| `FEATURES_SIMPLE_INFLECTION` | `features.simpleInflection` | boolean | `true` | Use simple inflection | |
123 | | -| `FEATURES_OPPOSITE_BASE_NAMES` | `features.oppositeBaseNames` | boolean | `true` | Use opposite base names | |
124 | | -| `FEATURES_POSTGIS` | `features.postgis` | boolean | `true` | Enable PostGIS support | |
125 | | - |
126 | | -### API Options (`opts.api`) |
127 | | - |
128 | | -| Env Var | Config Key | Type | Default | Description | |
129 | | -|---------|-----------|------|---------|-------------| |
130 | | -| `API_ENABLE_SERVICES` | `api.enableServicesApi` | boolean | `true` | Enable services API routing | |
131 | | -| `API_IS_PUBLIC` | `api.isPublic` | boolean | `true` | Public API mode (domain routing) | |
132 | | -| `API_EXPOSED_SCHEMAS` | `api.exposedSchemas` | string[] | `[]` | Comma-separated schemas to expose | |
133 | | -| `API_META_SCHEMAS` | `api.metaSchemas` | string[] | `['services_public', ...]` | Comma-separated metadata schemas | |
134 | | -| `API_ANON_ROLE` | `api.anonRole` | string | `'administrator'` | Anonymous role name | |
135 | | -| `API_ROLE_NAME` | `api.roleName` | string | `'administrator'` | Default role name | |
136 | | -| `API_DEFAULT_DATABASE_ID` | `api.defaultDatabaseId` | string | `'hard-coded'` | Default database identifier | |
137 | | - |
138 | | -## Type Parsing Rules |
139 | | - |
140 | | -- **Boolean**: Accepts `'true'`, `'1'`, `'yes'` (case-insensitive) as `true`; everything else is `false` |
141 | | -- **Number**: Uses `Number()` — returns `undefined` if `NaN` |
142 | | -- **String Array**: Splits on comma, trims whitespace, filters empty strings |
143 | | -- **Undefined**: If an env var is not set, that key is omitted from the options object (not set to `undefined`) |
| 3 | +The canonical source of truth for all recognized environment variables lives in the source code. Do not maintain a separate list — always refer to these files directly. |
| 4 | + |
| 5 | +## Source Files |
| 6 | + |
| 7 | +### Core PGPM Env Vars |
| 8 | + |
| 9 | +**File:** `pgpm/env/src/env.ts` in the `constructive` repo |
| 10 | + |
| 11 | +This file defines `getEnvVars()` which maps `process.env` keys to the `PgpmOptions` type. Every env var the system recognizes is defined here via conditional spreads: |
| 12 | + |
| 13 | +```typescript |
| 14 | +// Pattern used throughout env.ts: |
| 15 | +...(process.env.PGHOST && { host: process.env.PGHOST }), |
| 16 | +...(process.env.PGPORT && { port: parseEnvNumber(process.env.PGPORT) }), |
| 17 | +``` |
| 18 | + |
| 19 | +Covers: `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `DB_*`, `SERVER_*`, `PORT`, `BUCKET_*`, `AWS_*`, `MINIO_*`, `DEPLOYMENT_*`, `JOBS_*`, `SMTP_*`, `PGPM_ERROR_*` |
| 20 | + |
| 21 | +### GraphQL-Specific Env Vars |
| 22 | + |
| 23 | +**File:** `graphql/env/src/env.ts` in the `constructive` repo |
| 24 | + |
| 25 | +This file defines `getGraphQLEnvVars()` which adds GraphQL/Constructive-specific env vars on top of the core PGPM set. |
| 26 | + |
| 27 | +Covers: `GRAPHILE_SCHEMA`, `FEATURES_*`, `API_*` |
| 28 | + |
| 29 | +## Type Definitions |
| 30 | + |
| 31 | +The TypeScript interfaces that define the shape of these options: |
| 32 | + |
| 33 | +- **`PgpmOptions`** — `pgpm/types/src/options.ts` |
| 34 | +- **`ConstructiveOptions`** — `graphql/types/src/constructive.ts` |
| 35 | +- **`GraphileOptions`** — `graphql/types/src/graphile.ts` |
| 36 | +- **`PgConfig`** — `pgpm/types/src/pg.ts` |
| 37 | + |
| 38 | +## Type Parsing |
| 39 | + |
| 40 | +The env parsing uses three type-safe parsers (defined in `pgpm/env/src/env.ts`): |
| 41 | + |
| 42 | +- **`parseEnvBoolean(val)`** — Accepts `'true'`, `'1'`, `'yes'` (case-insensitive) as `true` |
| 43 | +- **`parseEnvNumber(val)`** — Uses `Number()`, returns `undefined` if `NaN` |
| 44 | +- **`parseEnvStringArray(val)`** — Splits on comma, trims whitespace, filters empty strings |
| 45 | + |
| 46 | +If an env var is not set, that key is omitted entirely from the options object — it does not get set to `undefined`. This allows the merge hierarchy to fall through to defaults or config file values. |
0 commit comments