/ 
DBIx-Class-Schema-GraphQL-v0.0.1
/ DBIx::Class::Schema::GraphQL

NAME

DBIx::Class::Schema::GraphQL - Auto-generate a GraphQL schema from a DBIx::Class schema

VERSION

Version v0.0.1

SYNOPSIS

use DBIx::Class::Schema::GraphQL;
use GraphQL::Execution qw(execute);

my $db     = My::Schema->connect(...);
my $result = DBIx::Class::Schema::GraphQL->to_graphql($db);

# Simple plural query - always include at least one scalar field
# alongside nodes (e.g. total) - see KNOWN BEHAVIOUR below.
execute($result->{schema},
    '{ allBooks { total nodes { title } } }',
    undef, $result->{context});

# Filtered + paginated + ordered
execute($result->{schema}, '
    query {
        allBooks(
            filter:  { title_like: "%Perl%" }
            orderBy: { field: "title", direction: ASC }
            page:    { skip: 0, take: 5 }
        ) {
            total
            hasNextPage
            nodes { id title }
        }
    }', undef, $result->{context});

# Cursor pagination
execute($result->{schema}, '
    query($after: String) {
        allBooks(cursor: { after: $after, first: 5 }) {
            total
            nextCursor
            hasNextPage
            nodes { id title }
        }
    }', undef, $result->{context}, { after => $cursor });

# Mutation
execute($result->{schema},
    'mutation { createBook(title: "Dune", author_id: 4) { id title } }',
    undef, $result->{context});

DESCRIPTION

Introspects every source registered with the supplied DBIx::Class::Schema and builds a complete, executable GraphQL::Schema with:

  • One scalar field per column, typed as Int, Float, Boolean, or String based on the column's declared data_type.

  • One relationship field per DBIC relationship (has_many resolves to a List type; belongs_to / might_have resolve to a single object type).

  • A root Query type with singular lookup and plural all<Source>s queries supporting filtering, ordering, and both offset and cursor pagination.

  • A root Mutation type with createX, updateX, and deleteX entry points for every source.

Composite primary keys are fully supported throughout.

METHODS

to_graphql

my $result = DBIx::Class::Schema::GraphQL->to_graphql($db);

Class method. Accepts a connected DBIx::Class::Schema instance. Returns a hashref:

{
    schema  => $graphql_schema,   # GraphQL::Schema, pass to execute()
    context => $db,               # the original schema, for convenience
}

SCALAR TYPE MAPPING

SQL column types are mapped to GraphQL scalars in the following priority order:

Boolean: bool, boolean, tinyint(1)
Float  : float, double, double precision, real, money, decimal, numeric
Int    : int, integer, bigint, smallint, tinyint, mediumint, serial
String : everything else (safe fallback)

PLURAL QUERIES

Every source X gets an allXs query returning an XConnection:

type XConnection {
    nodes:       [X]
    total:       Int        # total rows matching filter, before pagination
    nextCursor:  String     # opaque cursor; set only during cursor pagination
    hasNextPage: Boolean    # true when more pages follow
}

Always request total or another scalar field alongside nodes in your selection set - see "KNOWN BEHAVIOUR".

Filtering

allBooks(filter: { title_like: "%Perl%", author_id: 3 }) {
    total nodes { title }
}

Per-column operators:

col           exact match
col_not       inequality  (!=)
col_like      LIKE pattern  (String columns only)
col_gt        greater than
col_gte       greater than or equal
col_lt        less than
col_lte       less than or equal

Logical combinators (nest recursively and combine freely):

allBooks(filter: {
    AND: [
        { author_id: 1 }
        { OR: [{ title_like: "%Hobbit%" }, { title_like: "%Ring%" }] }
    ]
}) { total nodes { title } }

Ordering

allBooks(orderBy: { field: "title", direction: ASC }) {
    total nodes { title }
}

direction is the OrderDirection enum: ASC or DESC. When omitted, results are ordered by primary key ascending.

Offset pagination

allBooks(page: { skip: 10, take: 5 }) { total nodes { title } }

skip defaults to 0, take defaults to 10.

Cursor pagination

# First page
allBooks(cursor: { first: 5 }) {
    total nextCursor hasNextPage nodes { title }
}

# Subsequent pages - pass nextCursor from the previous response
allBooks(cursor: { after: "...", first: 5 }) {
    total nextCursor hasNextPage nodes { title }
}

first defaults to 10. Cursor pagination takes precedence over offset pagination if both are supplied in the same query. Cursors are opaque base64-encoded strings derived from the row's primary key and should be treated as implementation details subject to change.

MUTATIONS

For every source X, three mutations are generated:

createX

mutation { createBook(title: "Dune", author_id: 4) { id title } }

Accepts all column values as arguments. Columns that are non-nullable, have no declared default, and are not auto-increment are wrapped in NonNull and must be supplied. On failure, dies - the error appears in the top-level errors array of the response.

updateX

mutation { updateBook(id: 1, title: "Dune Messiah") { id title } }

Identifies the target row by its primary key or by a complete set of columns from any unique constraint declared on the source. All non-key columns must be supplied (full update). dies if the row cannot be found or the update fails.

deleteX

mutation { deleteBook(id: 1) }

Identifies the target row by primary key or unique constraint. Returns true (Boolean) on success, false if the row is not found.

ERROR HANDLING

createX and updateX resolver failures die. GraphQL catches the exception and surfaces it in the top-level errors array; the data field for the failed mutation will be null. deleteX returns false rather than dying when a row is not found.

LIMITATIONS

  • Relationship fields are unfiltered. Relationship fields within a query (e.g. author { books { title } }) return all related rows. They do not accept filter, orderBy, or pagination arguments.

  • No nested input for mutations. createX and updateX accept only scalar column values. Related rows must be created or linked separately using their own mutations and raw foreign-key values.

  • updateX is a full update. All non-primary-key columns must be supplied; partial (sparse) updates are not supported.

  • Cursor pagination assumes primary-key order. The after cursor encodes the primary key of the last returned row and applies a pk > value condition. If you supply a custom orderBy using a non-primary-key column, the cursor will not advance correctly. Use offset pagination (page) when ordering by non-PK columns.

  • No custom scalars. Column types such as date, datetime, json, and uuid all map to String. Custom GraphQL scalars are not generated.

  • No subscriptions. Only Query and Mutation operation types are generated.

  • col_like case sensitivity is database-dependent. SQLite LIKE is case-insensitive for ASCII characters but case-sensitive for Unicode. PostgreSQL LIKE is always case-sensitive. Use col_like accordingly.

KNOWN BEHAVIOUR

When querying a plural allXs field, always include at least one scalar field (total, hasNextPage, or nextCursor) alongside nodes in your selection set:

# Correct
{ allBooks { total nodes { title } } }

# May silently return empty nodes in some GraphQL executor versions
{ allBooks { nodes { title } } }

This is a quirk of how GraphQL::Execution resolves connection object types when the selection set contains only a list field.

DEPENDENCIES

DBIx::Class, GraphQL::Schema, GraphQL::Type::Object, GraphQL::Type::InputObject, GraphQL::Type::List, GraphQL::Type::NonNull, GraphQL::Type::Enum, GraphQL::Type::Scalar, MIME::Base64 (core).

SEE ALSO

GraphQL::Plugin::Convert::DBIC, DBIx::Class::Schema, GraphQL::Schema

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/DBIx-Class-Schema-GraphQL

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/DBIx-Class-Schema-GraphQL/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DBix::Class::Schema::GraphQL

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.