{"id":18459869,"url":"https://github.com/sayjava/sgraph","last_synced_at":"2025-08-01T04:43:15.392Z","repository":{"id":43457623,"uuid":"455834515","full_name":"sayjava/sgraph","owner":"sayjava","description":"sgraph is a schema first graphql api server powered by the sequelize orm library and envelope plugins compatible","archived":false,"fork":false,"pushed_at":"2022-03-08T18:11:42.000Z","size":15854,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T18:12:54.569Z","etag":null,"topics":["api-server","dgraph","envelope","graphql","hasura","prisma","sequelize","sqlite"],"latest_commit_sha":null,"homepage":"https://sayjava.github.io/sgraph","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sayjava.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-05T10:06:35.000Z","updated_at":"2022-03-12T07:03:20.000Z","dependencies_parsed_at":"2022-08-24T02:00:35.208Z","dependency_job_id":null,"html_url":"https://github.com/sayjava/sgraph","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayjava%2Fsgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayjava%2Fsgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayjava%2Fsgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayjava%2Fsgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sayjava","download_url":"https://codeload.github.com/sayjava/sgraph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250487535,"owners_count":21438612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-server","dgraph","envelope","graphql","hasura","prisma","sequelize","sqlite"],"created_at":"2024-11-06T08:24:44.174Z","updated_at":"2025-04-23T18:13:17.464Z","avatar_url":"https://github.com/sayjava.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003esGraph\u003c/h1\u003e\n  \u003ch3 align=\"center\"\u003eTurn your graphql schema into a full API\u003c/h3\u003e\n  \u003cdiv\u003e\n    \u003ca href=\"https://sayjava.github.io/sgraph/start\"\u003eQuickstart\u003c/a\u003e\n    \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n    \u003ca href=\"https://sayjava.github.io/sgraph\"\u003eWebsite\u003c/a\u003e\n    \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n    \u003ca href=\"https://sayjava.github.io/sgraph/api\"\u003eDocs\u003c/a\u003e\n    \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n    \u003ca href=\"https://github.com/sgraph/examples/\"\u003eExamples\u003c/a\u003e\n    \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n    \u003ca href=\"https://twitter.com/sayhava\"\u003eTwitter\u003c/a\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n\n## What is sGraph?\n\n`sGraph` is a schema driven GraphQL API server powered by the trusted [Sequelize SQL ORM Library](https://sequelize.org).\n\nIt is easy in 3 steps\n\n-   Define a graphql schema\n-   Provide database credentials\n-   Get back an API\n\n**with a simple schema like this (schema.graphql)**\n\n```graphql schema.graphql\ntype Customer @model {\n    Id: ID\n    ContactName: String\n    Orders: [Order] @hasMany\n}\n\ntype Order @model {\n    Id: Int @primaryKey @autoIncrement\n    OrderDate: Date\n    Freight: Float\n    CustomerId: String\n    Customer: Customer @belongsTo\n}\n```\n\nand start the server\n\n```shell\nnpx @sayjava/sgraph --schema schema.graphql --database sqlite::memory:\n```\n\n**you can now create customers and orders like this**\n\n```graphql\nmutation {\n    create_customer(\n        customer: {\n            Id: \"first-customer\"\n            ContactName: \"John Doe\"\n            Orders: [\n                { OrderDate: \"2021-06-01\", Freight: 20 }\n                { OrderDate: \"2021-06-01\", Freight: 10 }\n            ]\n        }\n    ) {\n        Id\n    }\n}\n```\n\n**you can query customers and orders like this**\n\n```graphql\nquery {\n    find_customers(where: { ContactName: { startsWith: \"John\" } }, limit: 10) {\n        count\n        customers {\n            ContactName\n            Orders {\n                Freight\n            }\n            Orders_aggregate {\n                max_Freight\n            }\n        }\n    }\n}\n```\n\nFor a full list of the available APIs see the [full docs](https://sayjava.github.io/sgraph)\n\n## Features\n\n-   Instant CRUD API from a Graphql Schema\n-   Extensive field filtering API. `startsWith`, `gt`, `isNot` e.t.c\n-   Extensive field aggregation API. `max`, `min`, `avg` e.t.c\n-   Builtin field validations with directives. e.g `@validate_max(value: 20)`, `@validate_len(value: [2, 10])` e.t.c\n-   Readable scalar fields with validation e.g `URL`, `Email`, `Date` e.t.c\n-   Powered by [Sequelize ORM](https://sequelize.org). Supports all the databases supported by sequelize. (`MySQL`, `SQLite`, `Postgresql`) e.t.c\n-   Supports [Envelop Plugins](https://www.envelop.dev) Plugins e.g `JWT`, `Performance`, `Caching`\n-   Serverless ready\n-   Programmable via express middleware\n\n## sGraph use cases\n\n-   Quickly spin up a GraphQL API for an existing database\n-   Generate read-only public/client facing APIs\n-   Eliminate redundant CRUD code\n-   Spin up cheap serverless APIs for small to medium sized projects\n-   Seamlessly integrate with your existing project via middleware, or serverless functions\n-   Easily build access restrictions into API with a declarative schema\n\n## Quick Start\n\nStart a sample API with the above schema with an in memory sqlite database\n\n```shell\nnpx @sayjava/sgraph --schema schema.graphql --database sqlite::memory:\n```\n\nRead the [API docs](website/docs/guide/api.md) for the full set of available APIs\n\n## Schema Definition\n\n# Examples \u0026 Playground\n\n-   Northwind Sample Database\n    -   [Code](examples/northwind)\n    -   [Live Playground](https://northwind-kp54hrqc6q-ew.a.run.app/graphql/)\n-   Chinook Sample Database (Coming soon)\n    -   [Code](chinook)\n    -   [Live Playground](https://chinook.sgraph.dev)\n\n## sGraph Architecture\n\nUnderneath, `sGraph` maps each defined GraphQL type to [Sequelize Model](https://sequelize.org/v7/manual/model-basics.html#model-definition) which is turn mapped to a database table. `sGraph` then generates a full API for each defined type and its associations. For example, a simple definition like\n\n```graphql\ntype Order @model {\n    Id: ID\n    Quantity: Float\n}\n```\n\nwill internally generate a GraphQL API like this\n\n```mermaid\nclassDiagram\n  direction RL\n\n\n  class Query {\n      find_order_by_pk(id)\n      find_orders(where, limit, offset, order_by)\n      order_aggregate(where, limit, offset)\n  }\n\n  class Mutations {\n      create_order(order)\n      create_orders(orders)\n\n      update_order_by_pk(id, order)\n      update_orders(orders)\n\n      delete_order_by_pk(id)\n      delete_orders(where, limit)\n  }\n\n  class Order {\n      id: ID\n      Quantity: Float\n  }\n\n  class OrderAggregate {\n      count\n      min_Quantity\n      max_Quantity\n      sum_Quantity\n      total_Quantity\n  }\n\n  class OrderOrderBy {\n      Quantity: OrderBy\n  }\n\n  class OrderFilter {\n      id: IDFilter\n      Quantity: BasicFilter | FloatFilter\n  }\n\n  class BasicFilter {\n      eq: Int\n      ne: Int\n      is: Int\n      not: Int\n      or: Int []\n  }\n\n  class FloatFilter {\n      eq: Int\n      gte: Int\n      lt: Int\n      lte: Int\n      between: Int[]\n      notBetween: Int[]\n  }\n\n  Query o-- Order\n  Mutations o-- Order\n  Order -- OrderAggregate\n  Order -- OrderOrderBy\n  Order -- OrderFilter\n  OrderFilter -- BasicFilter\n  OrderFilter -- FloatFilter\n```\n\n### Integration with envelop plugins\n\n`sGraph` wraps its internal schema with the [Envelop](https://www.envelop.dev) framework. That means the incredible list of available [envelope plugins](https://www.envelop.dev/plugins) can be tacked on to the server to even improve its functionalities with minium code.\n\n`sGraph` itself includes some plugins like [apolloTracing](https://www.envelop.dev/plugins/use-apollo-tracing) and [useDepthLimit](https://www.envelop.dev/plugins/use-depth-limit).\n\n```mermaid\n    classDiagram\n        direction LR\n        EnvelopSchema --* SGraphSchema : wraps\n        EnvelopSchema --o ApolloTracingPlugin : uses\n        EnvelopSchema --o DepthLimitPlugin : uses\n        EnvelopSchema --o OtherPlugins : uses\n        sGraphServer --*  EnvelopSchema : exposes\n```\n\nsee [plugins docs](website/docs/plugins.md) on how to simply integrate new plugins into the server\n\n## Supported Databases\n\nAll databases supported by the [Sequelize ORM](https://sequelize.org/v7/manual/getting-started.html#connecting-to-a-database) are supported by `sGraph`. The server comes bundled with `sqlite`, `postgres` and `mysql` database drivers. a quick start but for a more streamlined server, the `@sayjava/sgraph-slim` server comes just with just the basic server but the driver for the database will have to be installed.\n\n| Database               | Dependencies   | Bundled | Connection                                                                       |\n| ---------------------- | -------------- | ------- | -------------------------------------------------------------------------------- |\n| SQLite                 | `sqlite3`      | Yes     | `sqlite:path-to-file.sqlite`                                                     |\n| Postgres               | `pg pg-hstore` | Yes     | `postgres://user:pass@example.com:5432/dbname`                                   |\n| MySQL                  | `mysql2`       | Yes     | `mysql://user:pass@example.com:3306`                                             |\n| MariaDB                | `mariadb`      | No      | `mariadb://user:pass@example.com:3306`                                           |\n| Microsoft SQL Server   | `tedious`      | No      | [Check the sequelize docs](https://sequelize.org/v6/manual/getting-started.html) |\n| Amazon Redshift        | `ibm_db`       | No      | [Check the sequelize docs](https://sequelize.org/v6/manual/getting-started.html) |\n| Snowflake’s Data Cloud | `odbc`         | No      | [Check the sequelize docs](https://sequelize.org/v6/manual/getting-started.html) |\n\n## Documentation\n\n-   [Server Setup](website/docs/start.md)\n-   [Schema Guide](website/docs/guide/schema.mdx)\n-   [API Documentation](website/docs/guide/api.md)\n-   [Plugin Documentation](website/docs/plugins.md)\n\n## Programmatic Middleware\n\n`sGraph` can be incorporated into an existing application by using it as an express middleware either in a stand alone application or as a serverless function\n\n```js\nconst { createServer } = require('@sayjava/sgraph-core')\nconst express = require('express')\nconst app = express()\n\nconst { handler: middleware } = createServer({\n    database: 'databse:connection',\n    schema: 'path-to-schema',\n    cors: true\n\n    // list of instantiated envelop plugins\n    plugins: [],\n})\n\napp.use(middleware)\napp.listen(8080, () =\u003e console.log('Serer is up'))\n```\n\n## Limitations\n\n-   GraphQL subscriptions are not yet supported\n-   Upsert not yet supported\n-   Composite Index\n-   Schema migration\n\n## Development\n\nInstall dependencies\n\n```shell\nyarn bootstrap\n```\n\nStart the server\n\n```shell\ncd packages/server \u0026\u0026 yarn dev\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayjava%2Fsgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsayjava%2Fsgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayjava%2Fsgraph/lists"}