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
- 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
--nolines ...
- Suppress the # directives for lines. Useful if you need to debug the C code.
Example:
cql --in test.sql --nolines --cg foo.h foo.c
--generate_copy ...
- Generate a C copy function for the resultset. Most of the stored procedures don't need to generate this thats why is optional.
Example:
cql --in test.sql --cg foo.h foo.c --generate_copy
--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
--java_assembly_query_classname
- Fully qualified name of the parent class for the Java assembly. Used by java code generators when they output an extension fragment class.
--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