Docs / Packages / query

query

Kindkit
Categoriesdatabase
Keywordsquery sql database orm builder

Fluent SQL query builder for Kit

Files

FileDescription
.editorconfigEditor formatting configuration
.gitignoreGit ignore rules for build artifacts and dependencies
.tool-versionsasdf tool versions (Zig, Kit)
LICENSEMIT license file
README.mdThis file
examples/postgres-basic.kitExample: postgres basic
examples/sqlite-basic.kitExample: sqlite basic
kit.tomlPackage manifest with metadata and dependencies
src/main.kitQuery Builder for Kit
tests/query.test.kitTests for query

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-query.git

Usage

import Kit.Query as Query
import Kit.Sqlite as SQLite

# Connect to a database
db = SQLite.connect ":memory:"
defer SQLite.close db

# Setup
db.execute "CREATE TABLE posts (id INTEGER, title TEXT, status TEXT, views INTEGER)"
db.execute "INSERT INTO posts VALUES (1, 'Hello World', 'published', 100)"
db.execute "INSERT INTO posts VALUES (2, 'Draft Post', 'draft', 0)"
db.execute "INSERT INTO posts VALUES (3, 'Another Post', 'published', 50)"

# Build a query with fluent chaining using |>> (data-last pipe)
q = Query.create "posts"
  |>> Query.filter "status" "=" "published"
  |>> Query.filter "views" ">" "10"
  |>> Query.order-by "views" Query.Desc
  |>> Query.limit 10

# Generate raw SQL
println "SQL: ${Query.to-sql q}"
# => SQL: SELECT * FROM posts WHERE status = 'published' AND views > '10' ORDER BY views DESC LIMIT 10

# Generate parameterized SQL (driver-specific placeholders)
(sql, params) = Query.to-sql-params "sqlite" q
println "SQL: ${sql}"
# => SQL: SELECT * FROM posts WHERE status = ?1 AND views > ?2 ORDER BY views DESC LIMIT 10
println "Params: ${params}"
# => Params: [published, 10]

# Execute against a database connection
match Query.exec db q
  | Ok rows -> println "Found ${List.length rows} rows"
  | Err e -> println "Error: ${e}"

Development

Running Examples

Run examples with the interpreter:

kit run examples/sqlite-basic.kit
kit run examples/postgres-basic.kit

Compile examples to a native binary:

kit build examples/sqlite-basic.kit -o sqlite-basic && ./sqlite-basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

  1. Format and check source files in src/
  2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/query/, making it available for import as Kit.Query in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

create

NonEmptyString -> QueryState

columns

List String -> QueryState -> QueryState

filter

String -> String -> a -> QueryState -> QueryState

order-by

String -> Direction -> QueryState -> QueryState

limit

NonNegativeInt -> QueryState -> QueryState

offset

NonNegativeInt -> QueryState -> QueryState

typed

NonEmptyString -> QueryState -> QueryState

to-sql

QueryState -> String

to-sql-params

String -> QueryState -> (String, List a)

exec

Ptr -> QueryState -> Result (List a) String

Asc

Ascending sort direction for ORDER BY clauses

Direction

Desc

Descending sort direction for ORDER BY clauses

Direction