hasura / hasura/graphql-engine
feat(c/v3-engine) add possibility for namespacing when adding multiple data sources. Add possibility for permissions on namespaces and prefixes.
- Dominant language
- TypeScript
- Stars
- 32.1k
- Forks
- 3k
- PR merge metrics
- PR metrics pending
Description
**Feature Request for Hasura v3: Namespacing for Multiple Data Sources**
**_Current Behavior (Hasura v2)_**
In Hasura v2, when multiple databases are added as data sources, a namespace can be defined for each database. This enables GraphQL queries to group all tables and models from a database under a single, hierarchical namespace. Example:
```
query {
customer1 { # Namespace for Database 1
tableA
tableB
}
customer2 { # Namespace for Database 2
tableA
tableB
}
sharedLogic { # Namespace for shared logic
...
}
}
```
Limitation in Hasura v3
In Hasura v3, the namespacing feature has been replaced with prefixes at the root level. While prefixes serve a similar purpose, they do not provide the hierarchical structure or flexibility that namespaces offered. Instead of:
```
query {
customer1 {
tableA
}
}
```
You get:
```
query {
customer1_tableA
}
```
This flat structure can be harder to manage and less intuitive, especially when working with a large number of data sources that share the same schema.
### _Proposed Feature: Reintroduce Namespaces for Data Sources in Hasura v3_
**1. Namespace Support**
Allow users to define a namespace for each data source. All tables and models from the data source would be grouped under the namespace in the GraphQL schema.
Example configuration in metadata.yaml:
```
databases:
- name: customer1_db
namespace: customer1
- name: customer2_db
namespace: customer2
```
Resulting GraphQL structure:
```
query {
customer1 {
tableA
tableB
}
customer2 {
tableA
tableB
}
}
```
**2. Namespace-Specific Permissions**
To enhance the security and usability of namespaces, introduce namespace-level permissions that can restrict access to certain namespaces based on headers or JWT claims.
Example Permission Definition
In the metadata.yaml file, permissions could be defined for namespaces similarly to table-level permissions. For instance:
```
namespaces:
- name: customer1
permissions:
- role: user
condition:
headers:
X-Hasura-Allowed-Namespace: customer1
- role: admin
condition:
headers:
X-Hasura-Allowed-Namespaces:
- customer1
- customer2
- sharedLogic
- name: sharedLogic
permissions:
- role: user
condition:
headers:
X-Hasura-Allowed-Namespace: sharedLogic
```
**Behavior in Queries**
If a request contains the header X-Hasura-Allowed-Namespace: customer1, the user would only be able to query the customer1 namespace:
graphql
```
query {
customer1 {
tableA
}
}
```
Any attempt to query other namespaces (e.g., customer2) would be denied.
_Wildcard or Multi-Namespace Support_
If the header contains multiple allowed namespaces (e.g., X-Hasura-Allowed-Namespaces: customer1,customer2), users can query any of the specified namespaces.
```
query {
customer1 {
tableA
}
customer2 {
tableB
}
}
```
**3. Optional Namespace Filtering Based on Dynamic Conditions**
Enhance flexibility by allowing permissions to reference dynamic conditions like JWT claims or external data sources. For example:
_JWT Claim-Based Filtering_
Namespace access could be determined by a claim in the JWT token, such as allowed_namespaces.
```
namespaces/prefixes:
- name: customer1
permissions:
- role: user
condition:
jwt_claims:
allowed_namespaces:
contains: customer1
```
_Header-Based Filtering_
```
namespaces/prefixes:
- name: customer1
permissions:
- role: user
condition:
headers:
X-Hasura-Allowed-Namespaces:
contains: customer1
```
**Benefits of This Feature**
_Improved Organization_
Namespaces keep the GraphQL schema structured, making it easier to manage large projects with multiple data sources.
_Enhanced Security_
Namespace-level permissions allow granular control over access, ensuring that users or roles can only access the data sources they are authorized for.
_Compatibility with Multi-Tenant Systems_
This feature is especially useful for multi-tenant applications where each tenant has its own database but a shared schema.
_Backward Compatibility_
By reintroducing namespaces, developers familiar with Hasura v2 can seamlessly migrate to v3 without losing the benefits of hierarchical grouping.
_Scalability_
Supports large-scale applications with dozens or hundreds of customers, databases, or shared logic layers.
Contributor guide
Research direction
The issue names metadata.yaml, root-level prefixes, and GraphQL queries but no source files or tests. Start by locating v3 data-source metadata handling and the schema entry points that expose prefixes, then compare them with the described namespace behavior. Done would require an agreed namespace model, permission semantics, and coverage for single- and multi-namespace queries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql
- Domain
- api, authorization, backend-api-design, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100