Quick Start

Get up and running with genaql in 5 minutes. Write your first query and connect to a database.

1. Import genaql

Start by importing the template literal function:

app.ts

import { cook } from 'genaql';

// That's it! You're ready to write queries

2. Write Your First Query

Use the cook template literal to write a query:

query.ts

const users = cook`main:users slay:id,name,email sus:active=true bet:10`;

// Get the SQL string
console.log(users.toSQL());
// → SELECT id, name, email FROM users WHERE active = $1 LIMIT $2

// Get SQL with params for safe execution
const { sql, params } = users.toParams();
// → { sql: "SELECT ... WHERE active = $1 LIMIT $2", params: [true, 10] }

3. Connect to a Database

To actually run queries, create a client with your database connection:

db.ts

import { createClient } from 'genaql';
import { Pool } from 'pg';

// Create a PostgreSQL pool
const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Create a genaql client
const db = createClient({
  dialect: 'postgres',
  pool
});

// Now you can run queries!
const users = await db.query(
  cook`main:users slay:* sus:role=admin`
);

4. Add Type Safety (Optional)

For compile-time validation, define your schema:

schema.ts

import { defineSchema, cook } from 'genaql';

const schema = defineSchema({
  users: {
    id: 'serial',
    name: 'text',
    email: 'text',
    role: 'text',
    created_at: 'timestamp'
  }
});

// TypeScript will catch errors!
const query = cook`main:users slay:name,email,nonexistent`;
//                                           ^^^^^^^^^^^
// Error: Column 'nonexistent' does not exist on table 'users'

You're Ready!

You now know the basics of genaql. Explore the Syntax Reference for all available utilities, or check out Type Safety for advanced TypeScript integration.