LightBase
Open Source Backend Platform
A self-hostable, open-source backend platform inspired by Supabase: authentication, database management and REST APIs in a deliberately lightweight package.
0+
Core services
0 images
Container footprint
auto 0+
Endpoints generated
- TypeScript
- PostgreSQL
- REST APIs
- Docker
Problem
Managed backend platforms are excellent until you need to own your data, run inside a private network, or keep costs flat. The self-hosted alternatives tend to be heavy: many services, a large compose file, and a lot of moving parts for a small project. I wanted the ergonomics of a hosted backend with a footprint a student project or an internal tool could realistically operate.
- Vendor-hosted backends make data residency and cost control awkward
- Existing self-hosted options require significant infrastructure to run
- Small teams still need auth, a database API and a way to inspect data
Solution
LightBase exposes a Postgres database through a generated REST layer, adds token-based authentication, and ships a console for inspecting and editing data. It runs from a small set of containers and is designed to be read: the code is deliberately plain TypeScript so contributors can follow a request end to end.
- REST endpoints derived from the database schema rather than hand-written per table
- Token-based auth with password hashing and refresh handling
- A console for schema browsing, row editing and key management
- Single compose file, no orchestration required to self-host
Features
- Authentication — signup, login, token refresh and password hashing
- Database management — schema introspection, table browsing and row editing
- API services — generated REST resources with filtering, ordering and pagination
- Self-hosting — containerised services with environment-driven configuration
- Lightweight architecture — a small number of processes and dependencies
- Extensibility — a plugin seam for custom routes and middleware
- Community contribution support — documented layout and typed boundaries
Architecture
An HTTP gateway fronts three internal concerns: auth, the generated data API, and schema introspection. Everything persists to a single Postgres instance. The console is a client of the same public API, which keeps the API honest.
Swipe sideways to see the full diagram · tapHover or focus a node to trace its outbound calls
Implementation
The interesting work was in the generated data API: turning URL query parameters into SQL without opening an injection hole, and keeping the generated surface predictable as the schema changes.
- Schema is read from the Postgres catalog at boot and cached, then invalidated on migration
- Every generated query is parameterised; identifiers are validated against the introspected catalog rather than interpolated
- Filter grammar is a small, closed set of operators so the query surface stays auditable
- Pagination is keyset-based by default to avoid deep-offset scans
- Auth tokens are short-lived with rotating refresh tokens stored hashed
- Services share typed request/response contracts so the console cannot drift from the API
Challenges
Generating SQL safely
The whole value of a generated API is that clients can express queries, which is also exactly where injection lives. The rule became: values are always bound parameters, and identifiers are only ever looked up from the introspected catalog. If a column name is not in the catalog, the request is rejected before any SQL is built.
API design that stays stable as schemas change
Early versions exposed database details directly, so a column rename was a breaking API change. Adding an explicit exposure layer — which tables and columns are public, under what names — decoupled the API contract from the physical schema.
Keeping the footprint genuinely light
Every convenience wanted its own service. I set a hard budget on process count and dependency weight, which forced choices like doing introspection in-process instead of running a separate metadata service.
Making it contributable
Open source only works if a stranger can find their way around. That meant boring but useful things: one obvious entry point per service, typed boundaries between them, and a request lifecycle short enough to read in one sitting.
Result
LightBase runs as a self-hosted backend: bring a Postgres instance, start the containers, and you have authentication, a generated REST API and a console over your own data. It is the project where I did the most deliberate backend and API design work.
Lessons Learned
Generating an API from a schema is the easy half; deciding what not to expose is the half that determines whether the thing is maintainable. If I rebuilt it, the exposure layer would come first and the generator second. I would also add contract tests against a matrix of Postgres versions, since catalog behaviour is where the surprises live.
Screens
Next project
Air Filter Prediction System
Predictive maintenance service