SafeQL

SafeQL is an ESLint plugin designed to make writing PostgreSQL queries safer within your TypeScript code. It provides static analysis to catch common SQL errors during development rather than at runtime.

Key capabilities include:

• Schema Validation: Detects misspelled tables, columns, or functions.
• Type Safety: Identifies type mismatches between TypeScript variables and SQL operators (e.g., comparing a string to an integer).
• Type Annotation Enforcement: Warns when query TypeScript types are missing or incorrect and suggests fixes.

SafeQL provides automatic type inference and validation for PostgreSQL queries.

Key capabilities include:

• Automatic Type Inference & Validation: Infers the type of query results directly from the SQL query itself.
• Library Compatibility: Works with various PostgreSQL clients such as Prisma, Sequelize, pg, and postgres.js.
• Scalability: Designed for use in monorepos and microservices, supporting multiple database connections.

Before using @ts-safeql/plugin-auth-aws, ensure the following requirements are met:

1. RDS Configuration: Your RDS instance must have IAM database authentication enabled.
2. Database Permissions: The database user must be granted the rds_iam role.
3. AWS Credentials: Valid AWS credentials must be available via an AWS profile, environment variables, or IMDS.

Note for SSO users: If you are using AWS SSO, you must run aws sso login --profile <your-profile> before running the linting process.

When using Slonik, fragment variables are automatically inlined by SafeQL during analysis. This allows SafeQL to see the complete query structure even when parts are defined as fragments.

const where = sql.fragment`WHERE id = 1`;
const query = sql.unsafe`SELECT * FROM users ${where}`;
// Analyzed as: SELECT * FROM users WHERE id = 1

The sql tag leverages ES6 Tagged Templates to solve the problem of manual query parameterization. Instead of manually separating variables from strings to avoid SQL injection, the sql tag intercepts the template literal (a mix of strings and expressions) and returns a structured object.

For example, sql SELECT * FROM users WHERE id = ${userId} is converted at runtime into an object like:

{
  "query": "SELECT * FROM users WHERE id = $1",
  "values": [userId]
}

This allows developers to write natural SQL while the library handles the security of parameterization automatically.

SafeQL is not a replacement for your existing SQL library (such as Prisma, Sequelize, pg, or postgres). Instead, it is an ESLint plugin that adds a layer of safety to your existing setup.

Because it functions as a plugin, you can:

• Use it alongside any SQL library of your choice.
• Use it with multiple different SQL libraries simultaneously in the same project.
• Use it specifically for the raw queries that your primary library might struggle to handle (e.g., complex queries or performance-critical operations).

SafeQL validates your Zod schemas against the actual query results returned by the database. If the schema does not match the database types, SafeQL will provide an error or suggestion.

Example of a mismatch (defaults to suggestion):

import { z } from "zod";
import { sql } from "slonik";

// If the DB returns a number for 'id', this will trigger an error/suggestion
const query = sql.type(z.object({ id: z.string() }))`SELECT id FROM users`;

import { z } from "zod";
import { sql } from "slonik";

// Wrong field type → suggestion by default
const query = sql.type(z.object({ id: z.string() }))`SELECT id FROM users`;
//                                   ~~~~~~~~~~
// Error: Zod schema does not match query result.
//        Expected: z.object({ id: z.number() })

// Correct ✅
const query = sql.type(z.object({ id: z.number() }))`SELECT id FROM users`;

Create a safeql.config.ts file in your project root. Use defineConfig from @ts-safeql/eslint-plugin to specify your connection details. For @vercel/postgres, you typically provide a databaseUrl (e.g., from process.env.POSTGRES_URL) and define targets to identify which SQL tags should be linted. In the example below, ?(client.)sql is used to target SQL tagged with client.sql or similar patterns.

// safeql.config.ts

import { defineConfig } from "@ts-safeql/eslint-plugin";
import dotenv from "dotenv";

dotenv.config({ path: ".env.development.local" });

export default defineConfig({
  connections: {
    databaseUrl: process.env.POSTGRES_URL,
    targets: [{ tag: "?(client.)sql" }],
  },
});

SafeQL supports incremental adoption, allowing you to introduce typed queries one at a time without refactoring your entire codebase. You can opt-in specific query tags to SafeQL validation while leaving the rest of your queries untouched. This is achieved by creating a wrapper or alias for your database library's raw query method and configuring ESLint to target that specific tag.

At runtime, the aliased method behaves identically to the original library method (e.g., Prisma's $queryRaw). During development, SafeQL uses the ESLint plugin to intercept usages of the aliased tag and validate them against your database schema.

// db.ts
import { PrismaClient } from "@prisma/client";

export const prisma = new PrismaClient();
export const $typedQueryRaw = prisma.$queryRaw; // [!code ++]