Getting Started

Getting Started

A complete guide to get up and running with PawQL.

Prerequisites

  • Node.js 18+ or Bun 1.0+
  • TypeScript 5+
  • A supported database: PostgreSQL, MySQL/MariaDB, or SQLite

Installation

npm install pawql

# Install your database driver:
npm install pg              # PostgreSQL
npm install mysql2          # MySQL / MariaDB
npm install better-sqlite3  # SQLite (Node.js — Bun has built-in support)

Install only the driver you need. PawQL auto-detects the runtime for SQLite.

First Setup

1. Create a Database Connection

import { connect } from 'pawql';

const db = await connect({
  users: {
    id: { type: Number, primaryKey: true },
    name: String,
    email: { type: String, nullable: true },
    isActive: { type: Boolean, default: true },
  }
}, 'postgresql://user:password@localhost:5432/mydb');

// Alternatively via manual imports:
// import { createDB, PostgresAdapter } from 'pawql';
// const db = createDB(schema, new PostgresAdapter(...));

2. Synchronize Database (DDL)

PawQL can automatically create tables based on your schema — dialect-aware:

await db.createTables();
// Runs dialect-correct DDL:
// PostgreSQL: "id" UUID NOT NULL, "meta" JSONB
// MySQL:      `id` VARCHAR(36), `meta` JSON (backticks)
// SQLite:     "id" TEXT, "meta" TEXT, "flag" INTEGER (BOOLEAN→INTEGER)

Note: createTables() only creates tables that don't already exist. This is intended for development/prototyping — use Migrator for production. See Adapters Guide for type mapping.

3. Your First Query

// Insert
await db.query('users')
  .insert({ id: 1, name: 'Alice', email: 'alice@example.com' })
  .execute();

// Select
const users = await db.query('users')
  .where({ isActive: true })
  .execute();

console.log(users); 
// [{ id: 1, name: 'Alice', email: 'alice@example.com', isActive: true }]

4. Close the Connection

await db.close();

Adapter Configuration

PostgreSQL

import { PostgresAdapter } from 'pawql';

const adapter = new PostgresAdapter({
  connectionString: 'postgresql://user:pass@host:5432/db',
  // or individual parameters:
  // host: 'localhost', port: 5432, database: 'mydb', user: 'postgres', password: 'secret',
  max: 20,                    // Max pool connections
  idleTimeoutMillis: 30000,   // Close idle clients after 30s
});

MySQL / MariaDB

import { MysqlAdapter } from 'pawql';

const adapter = new MysqlAdapter({
  host: 'localhost',
  user: 'root',
  password: 'secret',
  database: 'mydb',
});

SQLite

import { SqliteAdapter } from 'pawql';

const adapter = new SqliteAdapter('mydb.sqlite');
// or ':memory:' for in-memory databases (great for testing)

See the Adapters Guide for more details.

my-app/
├── src/
│   ├── db/
│   │   ├── schema.ts     ← Schema definition
│   │   └── connection.ts ← Database connection
│   ├── services/         ← Business logic
│   └── index.ts
├── test/
│   └── *.test.ts
├── package.json
└── tsconfig.json

src/db/schema.ts

export const schema = {
  users: {
    id: { type: Number, primaryKey: true },
    name: String,
    email: { type: String, nullable: true },
    isActive: { type: Boolean, default: true },
  },
  posts: {
    id: { type: Number, primaryKey: true },
    userId: Number,
    title: String,
    content: String,
    publishedAt: { type: Date, nullable: true },
  }
} as const;

src/db/connection.ts

import { connect, consoleLogger } from 'pawql';
import { schema } from './schema.js';

export const db = await connect(
  schema, 
  process.env.DATABASE_URL!, 
  { logger: consoleLogger } // Optional: log all SQL to console
);

Next Steps