Public API

Nebulo exposes a minimal public API to allow the internals to change freely. The public API is defined as anything documented on this page.

For a complete example see the SQLAlchemy interop example

from databases import Database
from nebulo.gql.sqla_to_gql import sqla_models_to_graphql_schema
from nebulo.server.exception import http_exception
from nebulo.server.routes import GRAPHIQL_STATIC_FILES, get_graphql_route, graphiql_route
from starlette.applications import Starlette
from starlette.exceptions import HTTPException
from starlette.routing import Mount, Route

from myapp.sqla_models import Author, Book
from myapp.config import DATABASE_URI


def create_app(connection_str, sqla_models) -> Starlette:
    """Create the Starlette app"""

    database = Database(connection)

    # Convert sqla models to graphql schema
    gql_schema = sqla_models_to_graphql_schema(sqla_models=sqla_models)

    graphql_path = '/'

    # Build the Starlette GraphQL Route
    graphql_route = get_graphql_route(
        gql_schema=gql_schema,
        database=database,
        jwt_secret=jwt_secret,
        default_role=default_role,
        path=graphql_path,
        name='graphql'
    )

    # Build the Starlette GraphiQL Route and StaticFiles
    graphiql_route = get_graphiql_route(
        graphiql_path='/graphiql',
        graphql_path=graphql_path,
        name='graphiql'
    )

    # Instantiate the Starlette app
    _app = Starlette(
        routes=[graphql_route, graphiql_route],
        exception_handlers={HTTPException: http_exception},
        on_startup=[database.connect],
        on_shutdown=[database.disconnect],
    )

    return _app



# Instantiate the app
APP = create_app(connection_str=DATABASE_URI, sqla_models=[Author, Book])

Reflection

Utilities for reflecting SQL entities as GraphQL entities.

SQLA to GraphQL

nebulo.gql.sqla_to_gql.sqla_models_to_graphql_schema(sqla_models, sql_functions=None, jwt_identifier=None, jwt_secret=None)

Creates a GraphQL Schema from SQLA Models

Parameters

sqla_models: List[Type[SQLAModel]] = List of SQLAlchemy models to include in the GraphQL schema
jwt_identifier: str = qualified path of SQL composite type to use encode as a JWT e.g. 'public.jwt'
jwt_secret: str = Secret key used to encrypt JWT contents
sql_functions = NOT PUBLIC API

Server

Helpers to serve the GraphQL schema.

Routes

nebulo.server.routes.get_graphql_route(gql_schema, database, path='/', jwt_secret=None, default_role=None, name=None)

Create a Starlette Route to serve GraphQL requests

Parameters

schema: Schema = A GraphQL-core schema
database: Database = Database object for communicating with PostgreSQL
path: str = URL path to serve GraphQL from, e.g. '/'
jwt_secret: str = secret key used to encrypt JWT contents
default_role: str = Default SQL role to use when serving unauthenticated requests
name: str = Name of the GraphQL serving Starlette route

nebulo.server.routes.get_graphiql_route(graphiql_path='/graphiql', graphql_path='/', name='graphiql')

Return mountable routes serving GraphiQL interactive API explorer

Parameters

graphiql_path: str = URL path to GraphiQL html page
graphql_path: str = URL path to the GraphQL route
name: str = Name for the mount

Exception Handling

nebulo.server.exception.http_exception(request, exc)

Starlette exception handler converting starlette.exceptions.HTTPException into GraphQL responses