Getting Started

import { Tabs, TabItem, Steps } from ‘@astrojs/starlight/components’;

SQLAnvil compiles SQLX files and action configs into SQL, then executes them against your data warehouse. Projects are driven by a workflow_settings.yaml file that declares your warehouse connection and default schema.

Prerequisites

• Node.js 20 LTS or later
• One of: a BigQuery project with a service account, a PostgreSQL database, or a Supabase project

Install

npm install -g @sqlanvil/cli

Or run without installing:

npx @sqlanvil/cli --help

Create a project

1. Initialize a new SQLAnvil project in an empty directory:

   mkdir my-project && cd my-project
   sqlanvil init

   This creates:

   my-project/
   ├── definitions/        ← your SQLX and SQL files go here
   ├── includes/           ← shared JavaScript helpers
   └── workflow_settings.yaml

2. Configure your warehouse by editing workflow_settings.yaml:

   ```yaml warehouse: kind: bigquery project: my-gcp-project location: US defaultDataset: analytics ``` ```yaml warehouse: kind: postgres host: localhost port: 5432 database: analytics user: sqlanvil_writer password: ${PG_PASSWORD} ssl: disable defaultSchema: public ``` ```yaml warehouse: kind: supabase projectRef: abcdefghijklmnop serviceRoleKey: ${SUPABASE_SERVICE_ROLE_KEY} defaultSchema: public ```

3. Write your first action in definitions/my_view.sqlx:

   config {
     type: "view",
     description: "My first SQLAnvil view."
   }
   
   SELECT 1 AS id, 'hello' AS greeting

4. Compile to inspect the SQL that will run:

   sqlanvil compile

5. Run against your warehouse:

   sqlanvil run

Project structure

Path	Purpose
workflow_settings.yaml	Warehouse connection, default schema/dataset, vars
definitions/	SQLX files, SQL files, actions.yaml, JS files
includes/	Shared JS macros and constants
package.json	Declares @sqlanvil/core version and any packages

Action types

Type	Creates
table	A full-replace table
view	A SQL view
incremental	An incrementally-updated table
assertion	A data quality test
operation	Arbitrary SQL statements
declaration	A reference to an external table

See the Reference section in the sidebar for full API documentation on each action type.