Skip to content

Commit 0c20bc5

Browse files
ZetazzzZetazzz
authored
Merge pull request #472 from constructive-io/doc/graphql-server-readme
Doc/graphql server readme
2 parents e20f013 + db6e1e0 commit 0c20bc5

File tree

2 files changed

+115
-3
lines changed

2 files changed

+115
-3
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ cd my-app
4141
pgpm init
4242
cd packages/your-module
4343

44-
# 3. Install a package
44+
# 3. Install a package
4545
pgpm install @pgpm/faker
4646

4747
# 4. Deploy everything
@@ -292,7 +292,7 @@ This architecture eliminates the traditional ORM layer and API boilerplate, lett
292292

293293
### 🚀 GraphQL API & Server
294294

295-
- **[@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server)** - Express-based API server powered by PostGraphile with RLS integration and JWT authentication
295+
- **[@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server)** - Express-based API server powered by PostGraphile with RLS integration, JWT auth, and meta API routing
296296
- **[@constructive-io/graphql-explorer](https://github.com/constructive-io/constructive/tree/main/graphql/explorer)** - GraphiQL interface for exploring your auto-generated GraphQL API
297297
- **[graphile-settings](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-settings)** - Centralized PostGraphile plugin configuration with connection filters, PostGIS, and full-text search
298298

‎graphql/server/README.md‎

Lines changed: 113 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,118 @@
99
<img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
1010
</a>
1111
<a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
12-
<a href="https://www.npmjs.com/package/@constructive-io/graphql-server"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fserver%2Fpackage.json"/></a>
12+
<a href="https://www.npmjs.com/package/@constructive-io/graphql-server"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphql%2Fserver%2Fpackage.json"/></a>
1313
</p>
1414

15+
**Constructive GraphQL Server** is an Express-based server built on PostGraphile. It reads Constructive metadata to select API schemas, applies RLS-aware auth, and exposes a production-ready GraphQL API.
16+
17+
## 🚀 Quick Start
18+
19+
### Use as SDK
20+
21+
Install the package:
22+
23+
```bash
24+
pnpm add @constructive-io/graphql-server @constructive-io/graphql-env
25+
```
26+
27+
Start a server:
28+
29+
```ts
30+
import { getEnvOptions } from '@constructive-io/graphql-env';
31+
import { GraphQLServer } from '@constructive-io/graphql-server';
32+
33+
GraphQLServer(
34+
getEnvOptions({
35+
pg: { database: 'constructive_db' },
36+
server: { host: '0.0.0.0', port: 3000 }
37+
})
38+
);
39+
```
40+
41+
> **Tip:** Set `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` to control DB connectivity.
42+
See [Configuration](#configuration) for the full list of supported env vars and defaults.
43+
44+
### Local Development (this repo)
45+
46+
```bash
47+
pnpm install
48+
cd graphql/server
49+
pnpm dev
50+
```
51+
52+
This starts the server with env defaults from `@constructive-io/graphql-env`.
53+
> **Tip:** Set `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` to control DB connectivity.
54+
See [Configuration](#configuration) for the full list of supported env vars and defaults.
55+
56+
57+
## What it does
58+
59+
Runs an Express server that wires CORS, uploads, domain parsing, auth, and PostGraphile into a single GraphQL endpoint. It serves `/graphql` and `/graphiql`, injects per-request `pgSettings`, and flushes cached schemas on demand or via database notifications. When meta API is enabled, it resolves API config (schemas, roles, modules) from the meta schema using the request host and enforces `api.isPublic`, with optional header overrides in private mode; when meta API is disabled, it serves the fixed schemas and roles from `api.exposedSchemas`, `api.anonRole`, `api.roleName`, and `api.defaultDatabaseId`.
60+
61+
## Key Features
62+
63+
- Automatic GraphQL API generation from PostgreSQL schemas
64+
- RLS-aware authentication and per-request `pgSettings`
65+
- Meta-schema routing by domain + subdomain
66+
- File uploads via `graphql-upload`
67+
- GraphiQL and health check endpoints
68+
- Schema cache flush via `/flush` or database notifications
69+
70+
## Routes
71+
72+
- `GET /healthz` -> health check
73+
- `GET /graphiql` -> GraphiQL UI
74+
- `GET /graphql` / `POST /graphql` -> GraphQL endpoint
75+
- `POST /graphql` (multipart) -> file uploads
76+
- `POST /flush` -> clears cached Graphile schema for the current API
77+
78+
## Meta API routing
79+
80+
When `API_ENABLE_META=true` (default):
81+
82+
- The server resolves APIs from `meta_public.domains` using the request host.
83+
- Only APIs where `api.is_public` matches `API_IS_PUBLIC` are served.
84+
- In private mode (`API_IS_PUBLIC=false`), you can override with headers:
85+
- `X-Api-Name` + `X-Database-Id`
86+
- `X-Schemata` + `X-Database-Id`
87+
- `X-Meta-Schema` + `X-Database-Id`
88+
89+
When `API_ENABLE_META=false`:
90+
91+
- The server skips meta lookups and serves the fixed schemas in `API_EXPOSED_SCHEMAS`.
92+
- Roles and database IDs come from `API_ANON_ROLE`, `API_ROLE_NAME`, and `API_DEFAULT_DATABASE_ID`.
93+
94+
## Configuration
95+
96+
Configuration is merged from defaults, config files, and env vars via `@constructive-io/graphql-env`. See `graphql/env/README.md` for the full list and examples.
97+
98+
| Env var | Purpose | Default |
99+
| --- | --- | --- |
100+
| `PGHOST` | Postgres host | `localhost` |
101+
| `PGPORT` | Postgres port | `5432` |
102+
| `PGUSER` | Postgres user | `postgres` |
103+
| `PGPASSWORD` | Postgres password | `password` |
104+
| `PGDATABASE` | Postgres database | `postgres` |
105+
| `GRAPHILE_SCHEMA` | Comma-separated schemas to expose | empty |
106+
| `FEATURES_SIMPLE_INFLECTION` | Enable simple inflection | `true` |
107+
| `FEATURES_OPPOSITE_BASE_NAMES` | Enable opposite base names | `true` |
108+
| `FEATURES_POSTGIS` | Enable PostGIS support | `true` |
109+
| `API_ENABLE_META` | Enable meta API routing | `true` |
110+
| `API_IS_PUBLIC` | Serve public APIs only | `true` |
111+
| `API_EXPOSED_SCHEMAS` | Schemas when meta routing is disabled | empty |
112+
| `API_META_SCHEMAS` | Meta schemas to query | `collections_public,meta_public` |
113+
| `API_ANON_ROLE` | Anonymous role name | `administrator` |
114+
| `API_ROLE_NAME` | Authenticated role name | `administrator` |
115+
| `API_DEFAULT_DATABASE_ID` | Default database ID | `hard-coded` |
116+
117+
## Testing
118+
119+
Use `supertest` or your HTTP client of choice against `/graphql`. For RLS-aware tests, provide a `Bearer` token and ensure the API's auth function is available.
120+
121+
## Related Packages
122+
123+
- `@constructive-io/graphql-env` - env parsing + defaults for GraphQL
124+
- `@constructive-io/graphql-types` - shared types and defaults
125+
- `graphile-settings` - PostGraphile configuration
126+
- `graphile-meta-schema` - meta schema support

0 commit comments

Comments
 (0)