Quickstart

Requirements

Go 1.24 or later.

Installation

go get github.com/zoobzio/astql
go get github.com/zoobzio/dbml

Basic Usage

package main

import (
    "fmt"
    "github.com/zoobzio/astql"
    "github.com/zoobzio/astql/postgres"
    "github.com/zoobzio/dbml"
)

func main() {
    // 1. Define your schema
    project := dbml.NewProject("myapp")

    users := dbml.NewTable("users")
    users.AddColumn(dbml.NewColumn("id", "bigint"))
    users.AddColumn(dbml.NewColumn("username", "varchar"))
    users.AddColumn(dbml.NewColumn("email", "varchar"))
    users.AddColumn(dbml.NewColumn("active", "boolean"))
    project.AddTable(users)

    // 2. Create an ASTQL instance
    instance, err := astql.NewFromDBML(project)
    if err != nil {
        panic(err)
    }

    // 3. Build a query
    result, err := astql.Select(instance.T("users")).
        Fields(instance.F("username"), instance.F("email")).
        Where(instance.C(instance.F("active"), astql.EQ, instance.P("is_active"))).
        OrderBy(instance.F("username"), astql.ASC).
        Limit(10).
        Render(postgres.New())

    if err != nil {
        panic(err)
    }

    fmt.Println(result.SQL)
    // SELECT "username", "email" FROM "users" WHERE "active" = :is_active ORDER BY "username" ASC LIMIT 10

    fmt.Println(result.RequiredParams)
    // [is_active]
}

What's Happening

1. dbml.NewProject creates a schema definition
2. dbml.NewTable and AddColumn define your table structure
3. astql.NewFromDBML creates a validated instance bound to your schema
4. instance.T, instance.F, instance.P create validated references
5. astql.Select starts a query builder chain
6. .Render(provider) produces SQL and a list of required parameters using the specified provider

Using with sqlx

The output is designed for use with sqlx named queries:

result, _ := astql.Select(instance.T("users")).
    Fields(instance.F("username"), instance.F("email")).
    Where(instance.C(instance.F("active"), astql.EQ, instance.P("is_active"))).
    Render(postgres.New())

// Execute with sqlx
params := map[string]any{"is_active": true}
rows, err := db.NamedQuery(result.SQL, params)