cql

README

CQL: Compiled Query Language

Originally part of BaDaaS, CQL allows easy and safe persistence and querying of objects.

It's built on top of gorm, a library that actually provides the functionality of an ORM: mapping objects to tables in the SQL database. While gorm does this job well with its automatic migration then performing queries on these objects is somewhat limited, forcing us to write SQL queries directly when they are complex. CQL seeks to address these limitations with a query system that:

• Is compile-time safe: its query system is validated at compile time to avoid errors such as comparing attributes that are of different types, trying to use attributes or navigate relationships that do not exist, using information from tables that are not included in the query, etc.
• Is easy to use: the use of this system does not require knowledge of databases, SQL languages or complex concepts. Writing queries only requires programming in go and the result is easy to read.
• Is designed for real applications: the query system is designed to work well in real-world cases where queries are complex, require navigating multiple relationships, performing multiple comparisons, etc.
• Is designed so that developers can focus on the business model: its queries allow easy retrieval of model relationships to apply business logic to the model and it provides mechanisms to avoid errors in the business logic due to mistakes in loading information from the database.
• It is designed for high performance: the query system avoids as much as possible the use of reflection and aims that all the necessary model data can be retrieved in a single query to the database.

Language	Query
SQL	SELECT cities.* FROM cities INNER JOIN countries ON    countries.id = cities.country_id AND    countries.name = "France" WHERE cities.name = "Paris"
GORM	db.Where(  "cities.name = ?",  "Paris", ).Joins(  "Country",  db.Where(    "Country.name = ?",    "France",   ), ).Find(&cities)
CQL	cql.Query[models.City](   db,   conditions.City.Name.Is().Eq("Paris"),   conditions.City.Country(    conditions.Country.Name.Is().Eq("France"),   ), ).FindOne()

Documentation

https://compiledquerylenguage.readthedocs.io/en/latest/

Contributing

See this section to view the cql contribution guidelines.

License

CQL is Licensed under the Mozilla Public License Version 2.0.

Documentation

Index

• Variables
• func And[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]
• func Delete[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Delete[T]
• func Not[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]
• func Open(dialector gorm.Dialector, opts ...gorm.Option) (*gorm.DB, error)
• func Or[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]
• func Query[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Query[T]
• func Transaction[RT any](db *gorm.DB, toExec func(*gorm.DB) (RT, error), opts ...*sql.TxOptions) (RT, error)
• func Update[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Update[T]

Variables

var (
	// query
	ErrFieldModelNotConcerned = condition.ErrFieldModelNotConcerned
	ErrJoinMustBeSelected     = condition.ErrJoinMustBeSelected

	// conditions
	ErrEmptyConditions     = condition.ErrEmptyConditions
	ErrOnlyPreloadsAllowed = condition.ErrOnlyPreloadsAllowed

	// crud
	ErrMoreThanOneObjectFound = condition.ErrMoreThanOneObjectFound
	ErrObjectNotFound         = condition.ErrObjectNotFound

	// database
	ErrUnsupportedByDatabase = condition.ErrUnsupportedByDatabase
	ErrOrderByMustBeCalled   = condition.ErrOrderByMustBeCalled

	// preload
	ErrRelationNotLoaded = preload.ErrRelationNotLoaded
)

Functions

func And

func And[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]

And allows the connection of multiple conditions by the AND logical connector.

Its use is optional as it is the default connector.

Example:

cql.And(conditions.City.Name.Is().Eq("Paris"), conditions.City.ZipCode.Is().Eq("75000"))

func Delete

func Delete[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Delete[T]

Create a Delete to which the conditions are applied inside transaction tx

For details see https://compiledquerylenguage.readthedocs.io/en/latest/cql/delete.html

func Not

func Not[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]

Not allows the negation of the conditions within it. Multiple conditions are connected by an AND by default.

Example:

cql.Not(conditions.City.Name.Is().Eq("Paris"), conditions.City.Name.Is().Eq("Buenos Aires"))

translates as

NOT (name = "Paris" AND name = "Buenos Aires")

func Open

func Open(dialector gorm.Dialector, opts ...gorm.Option) (*gorm.DB, error)

Open initialize db session based on dialector

For details see https://compiledquerylenguage.readthedocs.io/en/latest/cql/connecting_to_a_database.html

func Or

func Or[T model.Model](conditions ...condition.WhereCondition[T]) condition.WhereCondition[T]

Or allows the connection of multiple conditions by the OR logical connector.

Example:

cql.Or(conditions.City.Name.Is().Eq("Paris"), conditions.City.Name.Is().Eq("Buenos Aires"))

func Query

func Query[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Query[T]

Create a Query to which the conditions are applied inside transaction tx

For details see https://compiledquerylenguage.readthedocs.io/en/latest/cql/query.html

func Transaction

func Transaction[RT any](
	db *gorm.DB,
	toExec func(*gorm.DB) (RT, error),
	opts ...*sql.TxOptions,
) (RT, error)

Executes the function "toExec" inside a transaction The transaction is automatically rolled back in case "toExec" returns an error opts can be used to pass arguments to the transaction

func Update

func Update[T model.Model](tx *gorm.DB, conditions ...condition.Condition[T]) *condition.Update[T]

Create a Update to which the conditions are applied inside transaction tx

For details see https://compiledquerylenguage.readthedocs.io/en/latest/cql/update.html