Skip to content

Home

Jump to bottom
Arunkumar Bhat edited this page Jun 3, 2026 · 2 revisions

Welcome to the File SQL Wiki!

File SQL is a VS Code extension that turns your local and Amazon S3 files into queryable SQL tables. It uses DuckDB's high-performance engine under the hood, allowing you to instantly load and query CSV, JSON, Parquet, or plain-text files without needing a database server.

📚 Table of Contents

  1. Features Overview
  2. Quick Start & Installation
  3. Supported File Formats
  4. Connecting to AWS S3
  5. Query Examples
  6. Troubleshooting & FAQ
  7. Development Guide

Features Overview

  • Direct Queries: Query local and S3 files using fully standard SQL syntax.
  • S3 Integration: Stream S3 files directly to a local temp directory, and automatically configure AWS regions and profiles.
  • Advanced Editor: CodeMirror-based SQL editor offering syntax highlighting, autocomplete, and theme support.
  • Interactive Results: View data in an interactive grid format and copy contents effortlessly.
  • Partitioned Data: Automatically maps folders full of partitioned files (e.g., s3://bucket/part-*.parquet) to a single queryable table.

Quick Start & Installation

1. Install

  1. Open VS Code -> Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  2. Search for "File SQL"
  3. Click Install (Requires VS Code version 1.85.0+)

2. Add Data

Open the File SQL sidebar (click the database icon in the Activity Bar).

  • Click the ＋ icon to add a specific file path (e.g., /data/sales.csv or s3://bucket/data.parquet).
  • Click the 📁 icon to select an entire local folder to register all valid files as tables.

3. Start Querying

Click the ▶ icon in the sidebar (or run the File SQL: Open Query Editor command). Write your SQL query and hit Ctrl+Enter (or Cmd+Enter) to run it!

Supported File Formats

Extension Format How DuckDB Reads It
.csv, .tsv CSV read_csv('path', AUTO_DETECT=TRUE)
.json, .jsonl, .ndjson JSON read_json_auto('path')
.parquet Parquet read_parquet('path') or read_parquet('dir/*.parquet')
.txt, .log Text read_csv('path', DELIM='\n', COLUMNS={'line':'VARCHAR'})

Connecting to AWS S3

File SQL offers first-class support for Amazon S3.

Prerequisites

Make sure your AWS CLI is configured correctly. You can set it up by running:

aws configure --profile my-profile

Ensure your IAM user has s3:GetObject, s3:ListBucket, and s3:GetBucketLocation permissions.

S3 Settings in VS Code

Open your VS Code Settings (JSON) and configure your AWS Profile:

{
  "fileSql.awsProfile": "my-profile",
  "fileSql.awsRegion": "us-east-1"
}

Note: fileSql.awsRegion is used as a fallback. File SQL attempts to auto-detect bucket regions using GetBucketLocation.

Query Examples

Joining Two Files

SELECT o.order_id, c.name, o.total
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE o.total > 100;

JSON Processing

SELECT json_extract(payload, '$.user.name') AS user_name
FROM api_logs;

Troubleshooting & FAQ

Warning

⚠ Results Truncated If you see this warning, it means your query exceeded the configured row limit. DuckDB wraps queries in LIMIT N+1. You can increase this by changing fileSql.maxResultRows in your settings.

S3 Import Fails?

  1. Check your AWS CLI credentials: aws sts get-caller-identity --profile your-profile
  2. Ensure you have the right IAM permissions.
  3. Check the URI format: s3://bucket/path/file.csv.

Extension isn't Activating? Verify that your VS Code version is at least 1.85.0. Try reloading the window via the command palette.

Development Guide

If you'd like to contribute or run File SQL locally:

git clone https://github.com/arunkumar1997/vscode-sql-files.git
cd vscode-sql-files
npm install
npm run watch

Press F5 in VS Code to launch the Extension Development Host.

File SQL's bundle relies on esbuild.mjs, which generates two main bundles:

  1. Extension Host (dist/extension.js)
  2. Webview UI (dist/webview.js & dist/webview.css)

Clone this wiki locally