Skip to content
Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

bbc

bbc is a command line application that compiles an annotated GraphQL schema into files required to run the basebox backend.

Generated Files

bbc generates three files from the GraphQL schema file provided:

  • Data Model (file name format: <prefix>-datamodel.sql)

    The data model file is an SQL database creation script. You use this in PostgreSQL to create your backend database.

  • Resolver (file name format: <prefix>-resolver.toml)

    The resolver file contains a compiled version of the operation resolvers defined in the schema file. You do not need to do anything with this file except point the dbproxy to its location (specified in the dbproxy configuration file (see the dbproxy guide for more information on how to do this))

  • Type Map (file name format: <prefix>-typemap.json)

    The type map file contains type mapping between GraphQL and the SQL database. It allows the dbproxy to map types quickly when a request is received. Like with the resolver file, you do not need to do anything with this file except point the dbproxy to its location (see the dbproxy guide for more information on this)

Command Line Parameters

To see bbc's command line arguments, call it with --help:

❯ ./bbc --help
bbc, the basebox compiler, compiles a GraphQL schema into database specific schema and template files.

Usage: bbc [OPTIONS] <FILENAME>

Arguments:
  <FILENAME>
          Path and filename of GraphQL schema to compile

Options:
  -q, --quiet
          quiet operation

  -o, --output-directory <OUTPUT_DIRECTORY>
          Output directory for generated files; default is current

  -p, --prefix <PREFIX>
          Prefix for file name generation; defaults to the base name of the input file

  -f, --force-overwrite
          Overwrite existing output files?

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

As per the help, bbc takes one argument, the path and filename of the schema file, like in this example: 

❯ ./bbc ./bbc-files/myschema.graphql

basebox compiler (bbc) version 1.0.0
Writing output files to '/bbc'
  Data model: myschema-with-annotations-datamodel.sql
  Resolver:   myschema-with-annotations-resolver.toml
  Type map:   myschema-with-annotations-typemap.json

Output files successfully generated.
Running bbc like this will dump the output files directly in the current folder. The files generated will use the GraphQL schema filename as a prefix. Using the options provided by bbc, you can make some changes, like so:

❯ ./bbc ./bbc-files/myschema.graphql -o ./bbc-files/ -p schema -f

basebox compiler (bbc) version 1.0.0
Writing output files to '/bbc/bbc-files'
  Data model: schema-datamodel.sql
  Resolver:   schema-resolver.toml
  Type map:   schema-typemap.json

Output files successfully generated.
This will tell the compiler to output the files to bbc-files folder (where the schema is located), to change the file prefix to schema and to force overwrite files if these three files already exist in the output folder (use with caution of course).

Errors

bbc might of course generate errors if it finds some issue with the schema provided. In that case, it will not generated new files and would require that you correct the issue/s in the schema before the files are generated.

For example, we introduced a typing error into our schema file: 

❯ ./bbc ./bbc-files/myschema.graphql -o ./bbc-files/ -p schema -f

basebox compiler (bbc) version 1.0.0
Compilation error: Resolver for operation 'addAppointment' at Pos(219:3): Error 
validating arguments in fields object for operation 'addAppointment': The 
argument '$scheduledA1t' was not found in the operation's argument list.
bbc picks up and highlights the error. This needs to be fixed before proceeding.

Next steps

Once bbc is run successfully, you can generate your database, point dbproxy to the database and the files generated and you now have a functioning backend. The broker also needs to reference the GraphQL schema file, this is specified in the broker configuration file.