SearchLight ORM

SearchLight is a concise, secure, and cross-platform query builder and ORM designed for Julia. It provides a high-level interface for interacting with relational databases, including features for data modeling, query generation, validation, schema migrations, managing relationships, and data serialization.

Supported Databases:

• SQLite
• MySQL/MariaDB
• Postgres

SearchLight configuration is managed through the Configuration module. You can control the behavior of the framework using several key components:

• Settings: The primary object for defining configuration parameters.
• load: A function used to initialize or reload settings.
• read_db_connection_data: A utility to retrieve database connection information required for SearchLight operations.
• env: Accesses configuration via environment variables.

The most robust way to handle transactions is using the with_transaction function. This function automatically handles the lifecycle of a transaction: it begins the transaction, executes your provided code block, and then automatically calls commit_transaction if the block completes successfully. If an error occurs within the block, it automatically calls rollback_transaction to revert any changes made during that block.

using SearchLight.Transactions

with_transaction(db) do
    # Perform multiple database operations here
    # If any operation fails, the entire block is rolled back
    update_record(db, id, data)
    insert_log(db, "Record updated")
end

Once a query is constructed, you can use SearchLight utility functions to execute it and retrieve specific types of results directly.

# Execute and get specific results
results = SearchLight.find(query)    # Find matching records
first_row = SearchLight.first(query) # Get the first record
last_row = SearchLight.last(query)   # Get the last record
count = SearchLight.count(query)     # Get the total number of matches
sql_string = SearchLight.sql(query)  # Get the raw SQL representation

The Serializer module provides functions to convert data between in-memory representations and serialized formats (such as JSON or other supported formats). It is the primary interface for handling data persistence and transmission within SearchLight.

Key functions include:

• serialize(data): Converts a data structure into a serialized format.
• deserialize(data, type): Converts serialized data back into a specific Julia type.
• serializables(): Returns a list of types that are currently supported for serialization.

using SearchLight.Serializer

# Example usage
# data = serialize(my_object)
# restored_object = deserialize(data, MyType)
# supported_types = serializables()

The QueryBuilder module provides a fluent interface for constructing structured queries. You can chain methods to define the shape and constraints of your data retrieval. Common operations include selecting fields, filtering results, and managing pagination or ordering.

# Example of chaining QueryBuilder methods
query = select(:field1, :field2) |
        where(:field1 == "value") |
        order(:field1, direction=:desc) |
        limit(10)

For complex logic where a single block is insufficient, you can manually control the transaction lifecycle using the following functions:

• begin_transaction(db): Starts a new transaction on the provided database connection.
• commit_transaction(db): Permanently saves all changes made during the current transaction.
• rollback_transaction(db): Reverts all changes made since the transaction began.

using SearchLight.Transactions

begin_transaction(db)
try
    # Perform operations
    commit_transaction(db)
catch e
    rollback_transaction(db)
    rethrow(e)
end

The JsonSerializer module provides functions to convert data structures to JSON strings and back. Use serialize to transform a Julia object into a JSON string, and deserialize to reconstruct a Julia object from a JSON string.

Available functions:

• SearchLight.Serializer.serialize(data): Converts the input data into a JSON-formatted string.
• SearchLight.Serializer.deserialize(json_string): Parses a JSON string and returns the corresponding Julia data structure.

using SearchLight.Serializer

# Example usage
data = Dict("key" => "value", "number" => 42)
json_str = SearchLight.Serializer.serialize(data)

reconstructed_data = SearchLight.Serializer.deserialize(json_str)

The SearchLight module provides a set of types used to construct and represent SQL queries and model structures. These types allow for programmatic construction of SQL logic, including joins, where clauses, ordering, and raw SQL strings, ensuring type safety when building complex queries within the framework.

# Available types in the SearchLight module:
DbId
SQLType
AbstractModel
SQLInput
SQLColumn
SQLColumns
SQLLogicOperator
SQLWhere
SQLWhereExpression
SQLWhereEntity
SQLLimit
SQLOrder
SQLQuery
SQLRaw
SQLJoin
SQLOn
SQLJoinType
SQLHaving
@sql_str

The following methods are available in the QueryBuilder module for constructing queries:

# Core Query Construction
select(...)      # Specify columns to retrieve
from(...)        # Specify the source table/model
where(...)       # Apply filtering logic
order(...)       # Specify sorting (e.g., order(:col, direction=:asc))
group(...)       # Group results by specific columns
having(...)      # Apply filters to grouped results
limit(n)         # Restrict the number of returned rows
offset(n)        # Skip the first n rows

# Execution and Transformation
prepare(...)     # Prepare the query for execution
+
DataFrames.DataFrame # Convert query results to a DataFrame