Appendix 1: Command Line Options

CQL has a variety of command line options but many of them are only interesting for cql development. Nonetheless this is a comprehensive list:

With No Options

• CQL reads its input and echos it back as normalized SQL
• this only validates that the input can be parsed
• note CQL is often used after the c pre-processor is run so this kind of invocation is typical:

cc -E -x c foo.sql | cql [args]

--in file

• reads the given file for the input instead of stdin
• the input should probably have already been run through the C pre-processor as above
• returns non-zero if the file fails to parse

Example:

cql --in test.sql

--sem

• performs semantic analysis on the input file ONLY
• the return code is zero if there are no errors

Example:

cql --in sem_test.sql --sem

--print

• may be combined with --sem (semantic info will be included)
• prints the internal AST to stdout instead of echoing the inputs Example

cql --in sem_test.sql --sem --print >sem_ast.out

--dot

• prints the internal AST to stdout in DOT format for graph visualization
• this is really only interesting for small graphs for discussion as it rapidly gets insane

Example:

cql --dot --in dottest.sql

--cg output1 output2 ...

• any number of output files may be needed for a particular result type, two is common
• the return code is zero if there are no errors
• any --cg option implies --sem

Example:

cql --in foo.sql --cg foo.h foo.c

--global_proc name

• any loose SQL statements not in a stored proc are gathered and put into a procedure of the given name
• when generating a schema migrate script the global proc name is used as a prefix on all of the artifacts so that there can be several independent migrations linked into a single executable

--compress

• for use with the C result type, (or any similar types added to the runtime array in your compiler)
• string literals for the SQL are broken into "fragments" the DML is then represented by an array of fragments
• since DML is often very similar there is a lot of token sharing possible
• the original string is recreated at runtime from the fragments and then executed
• comments show the original string inline for easier debugging and searching

NOTE: different result types require a different number of output files with different meanings

--test

• some of the output types can include extra diagnostics if --test is included
• that often makes the outputs badly formed so this is generally good for humans only

--java_package_name

• used by java code generators when they output a class. Allows to specify the name of package the class will be a part of

--c_include_namespace

• for the C codegen runtimes, it determines the header namespace (as in #include <namespace/file.h) that the headers will have to be referred when included from other sources.

--objc_c_include_path

• for ObjC codegen runtimes that need to refer to the generated C code, this represents the header of the C generated code that will be used during inclusion from the ObjC file

Result Types (--rt *)

These are the various outputs the compiler can produce.

--rt c

• requires two output files (foo.h and foo.c)
• this is the standard C compilation of the sql file

--rt objc

• objective C wrappers for result sets produced by the stored procedures in the input
• these depend on the output of a standard codegen run so this is additive
• requires one output file (foo.h)

--rt java

• java wrappers for result sets produced by the stored procedures in the input
• these depend on the output of a standard codegen run so this is additive
• requires one output file (foo.java)

--rt schema

• produces the canonical schema for the given input files
• stored procedures etc. are removed
• whitespace etc. is removed
• suitable for use to create the next or first "previous" schema for schema validation
• requires one output file

--rt schema_upgrade

• produces a CQL schema upgrade script (one file) which can then be compiled with CQL itself
• see the section on schema upgrade/migration
• requires one output file (foo.sql)

--include_regions a b c

• the indicated regions will be declared
• used with --rt schema_upgrade or --rt schema
• in the upgrade case excluded regions will not be themselves upgraded, but may be referred, to by things that are being upgraded

--exclude_regions x y z

• the indicated regions will still be declared but the upgrade code will be suppressed, the presumption being that a different script already upgrades x y z
• used with --rt schema_upgrade

--rt json_schema

• produces JSON output suitable for consumption by downstream codegen like the android mlite system
• the JSON includes a definition of the various entities in the input
• see the section on JSON output for details