Phrag

GraphQL from a RDBMS Connection

Overview

Instantly Operational: Phrag creates a GraphQL simply from a RDBMS connection, using schema data such as tables, columns, and primary / foreign keys. All needed is a database.

CRUD / SQL Features: all tables become queryable as root objects containing nested objects of relationships. Mutations (create, update and delete) are also created per tables. Additionally, aggregation, filter, sorting and pagination are supported for query operations.

Customization: Phrag comes with an interceptor capability to customize behaviors of GraphQL. Custom functions can be configured before & after database accesses per tables and operation types, which can make GraphQL more practical with access control, event firing and more.

Performance in Mind: Phrag's query resolver implements a batched SQL query per nest level to avoid N+1 problem. Load tests have also been performed to verify it scales linear with resources without obvious bottlenecks.

Documentation

• Mechanism

• Configuration

• Interceptors

• SQL Features

• Performance

• Development

Example projects:

• SNS: a situated project to verify Phrag's concept and practicality. It has authentication, access control and custom logics through Phrag's interceptors.

Requirements

Here's a quick view of database constructs which are important for Phrag. Detailed mechanism is explained here.

• Primary keys: Phrag uses primary keys as identifiers of GraphQL mutations. Composite primary key is supported.

• Foreign keys: Phrag translates foreign keys to nested properties in GraphQL objects.

• Indices on foreign key columns: Phrag queries a database by origin and destination columns of foreign keys for nested objects. It should be noted that creating a foreign key does not index those columns.

Notes

• Supported databases are SQLite and PostgreSQL.

• If PostgreSQL is used, Phrag queries tables such as key_column_usage and constraint_column_usage to retrieve PK / FK info, therefore the database user provided to Phrag needs to be identical to the one that created those keys.

• Not all database column types are mapped to Phrag's GraphQL fields yet. Any help would be appreciated through issues and PRs.

Usage

Phrag's GraphQL can be invoked as a function, reitit route or Bidi route. Database (:db) is the only required parameter in config, but there are many more configurable options. Please refer to config doc for details.

Function:

(let [schema (phrag/schema config)]
  (phrag/exec config schema query vars req))

Reitit route in an Integrant config map:

{:phrag.route/reitit {:db (ig/ref :sql/datasource)} }

Copyright © 2021 Yohei Kusakabe