Schema Types
Document, Managed, and Unmanaged schemas offer different levels of abstraction and control for your data.
Nuvix Database provides three schema types optimized for different use cases. Use this guide to choose the right approach for your application.
Document Schema
A NoSQL-style abstraction over PostgreSQL designed for rapid development. Document schemas expose JSON document APIs and do not require SQL knowledge.
Key features
- NoSQL interface: JSON-based document CRUD operations
- Collection-based: Data organized into collections with user-defined attributes
- Chainable Builder: Fluent API syntax (
.equal('status', 'active').find()) - ACL permissions: Custom access control at collection and document levels
API structure
- Endpoint:
/v1/schemas/:schemaId/collections/:collectionId/documents - Query Style: Fluent Chainable Builder
- Response: JSON documents with system fields (
$id,$createdAt)
When to use
- Rapid prototyping without SQL
- Dynamic, flexible data models
- NoSQL-style applications
- Mobile and web app backends
Document schemas provide read-only SQL access. All data modifications must go through the API layer.
Managed Schema
A PostgreSQL schema with Nuvix automation. Managed schemas generate metadata, permission tables, and Row Level Security policies automatically.
Key features
- Full SQL support: Complete PostgreSQL querying capabilities
- Fluent API: Type-safe SQL query builder (
nx.db.schema(...).from(...).select()) - Automatic RLS: Row Level Security policies generated for every table
- Permission automation: Automatic creation of permission tracking tables
- Nuvix governance: Simplified management with built-in security
Built-in automation
When you create a table in a Managed schema, Nuvix automatically:
- Adds an
_idcolumn (auto-incrementing primary key) - Creates a
{table}_permstable for permission tracking - Enables Row Level Security with CRUD policies
- Sets up DDL triggers for policy generation
API structure
- Endpoint:
/v1/schemas/:schemaId/tables/:tableId - Query Style: Fluent SQL API or REST parameters
- Response: Flat JSON records (table rows)
When to use
- Production-grade relational applications
- Multi-tenant systems
- Enterprise apps requiring data governance
- Applications needing both SQL and API access
Managed schemas provide PostgreSQL power with Nuvix automation. You get full SQL access with security handled automatically.
Unmanaged Schema
A raw PostgreSQL schema exposed through the Nuvix API without automation. You have complete control over schema design, SQL queries, and access policies.
Key features
- Full PostgreSQL control: Complete schema and permission management
- No automation: No automatic RLS or permission tables
- Fluent API: Same powerful SQL builder as Managed schemas
- Manual governance: User-defined access controls and policies
- Maximum flexibility: Custom constraints, indexes, and relationships
API structure
- Endpoint:
/v1/schemas/:schemaId/tables/:tableId - Query Style: Fluent SQL API
- Response: Flat JSON records (table rows)
When to use
- Advanced SQL workloads
- Legacy database migrations
- Custom governance systems
- Complex relational designs
Unmanaged schemas require manual setup of permissions and RLS policies. Choose this option only if you need complete control and are comfortable managing PostgreSQL security.
Comparison
| Feature | Document | Managed | Unmanaged |
|---|---|---|---|
| SQL access | Read-only | Full | Full |
| API access | Full CRUD | Full CRUD | Full CRUD |
| Query Style | Chainable Builder | Fluent SQL API | Fluent SQL API |
| Automatic RLS | N/A | Yes | No |
| Permission tables | N/A | Auto-generated | Manual |
| Schema management | API-only | SQL + API | SQL + API |
| Learning curve | Low | Medium | High |
Access Pattern Summary
| Schema Type | SDK Access Pattern |
|---|---|
| Document | nx.db.schema('my_doc').collection('users').find() |
| Managed | nx.db.schema('app_data').from('orders').select() |
| Unmanaged | nx.db.schema('legacy').from('logs').select() |
| Public | nx.db.from('users').select() (Shortcut for public schema) |
How is this guide?
Last update: