Skip to content

Commit 3ae3b82

Browse files
Add MSSQL via DuckDB documentation (#285)
Document how to query SQL Server through DuckDB's mssql community extension using additionalExtensions and setupSQL in malloy-config.json.
1 parent 992a027 commit 3ae3b82

2 files changed

Lines changed: 84 additions & 0 deletions

File tree

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
>>>markdown
2+
# MSSQL via DuckDB
3+
4+
Malloy can query Microsoft SQL Server through DuckDB's
5+
[mssql community extension](https://duckdb.org/community_extensions/extensions/mssql).
6+
This extension uses the native TDS protocol to connect directly to SQL Server—no
7+
ODBC or JDBC drivers required.
8+
9+
Because the connection runs through DuckDB, Malloy uses the **DuckDB dialect** for
10+
SQL generation, and DuckDB handles translating queries to SQL Server where needed.
11+
12+
## How It Works
13+
14+
DuckDB's `mssql` extension ATTACHes a SQL Server database, making its schemas and
15+
tables appear in DuckDB's catalog. Malloy then queries these tables through its
16+
standard DuckDB connection.
17+
18+
## Configuration
19+
20+
MSSQL via DuckDB is configured as a `duckdb` connection in your `malloy-config.json`.
21+
The `additionalExtensions` field automatically installs and loads the mssql extension,
22+
and `setupSQL` ATTACHes to your SQL Server and sets the default catalog and schema:
23+
24+
```json
25+
{
26+
"connections": {
27+
"mssql": {
28+
"is": "duckdb",
29+
"additionalExtensions": "mssql",
30+
"setupSQL": "ATTACH 'Server=myserver;Port=1433;Database=mydb;User Id=myuser;Password=secret;TrustServerCertificate=true' AS mydb (TYPE mssql);\nUSE mydb.dbo"
31+
}
32+
}
33+
}
34+
```
35+
36+
The `setupSQL` runs once per session. The `USE` must include both catalog and
37+
schema (e.g., `mydb.dbo`) — `USE mydb` alone is not sufficient.
38+
39+
See [Configuration](../../setup/config.malloynb) for more details on `malloy-config.json`.
40+
41+
Once configured, query SQL Server tables like any other Malloy source:
42+
43+
```malloy
44+
source: orders is mssql.table('dbo.orders')
45+
46+
run: orders -> {
47+
group_by: status
48+
aggregate: order_count is count()
49+
}
50+
```
51+
52+
## Authentication
53+
54+
The connection string supports standard SQL Server authentication parameters.
55+
See the [mssql extension documentation](https://github.com/hugr-lab/mssql-extension)
56+
for the full list of supported connection string options, including:
57+
58+
- SQL Server authentication (User Id / Password)
59+
- Encrypted connections (TLS/SSL)
60+
- Azure SQL Database
61+
62+
**Note:** The mssql extension's "interactive" authentication mode prints a
63+
URL to stdout that you must visit to complete login. This does not work
64+
with the VS Code extension, which has no visible stdout. Use
65+
username/password or other non-interactive authentication methods instead.
66+
67+
## Limitations
68+
69+
- **DuckDB dialect**: Malloy generates DuckDB SQL, which the extension translates
70+
for SQL Server. Some DuckDB-specific functions or syntax may not push down to
71+
SQL Server.
72+
- **No nested/array data**: SQL Server does not support array or nested struct
73+
columns, so Malloy features that depend on these (e.g., nested sources from
74+
JSON arrays) are not available.
75+
- **Extension maturity**: The mssql extension is a community extension and may
76+
not cover all SQL Server edge cases.
77+
78+
## External Resources
79+
80+
* [DuckDB mssql Extension (Community Extensions)](https://duckdb.org/community_extensions/extensions/mssql)
81+
* [mssql Extension GitHub](https://github.com/hugr-lab/mssql-extension)
82+
* [DuckDB ATTACH Documentation](https://duckdb.org/docs/sql/statements/attach)

src/documentation/setup/database_support.malloynb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Malloy connects to a variety of databases. This page provides an overview of sup
1414
| [PostgreSQL](../language/dialect/postgres.malloynb) | `postgres` | Standard credentials |
1515
| [MySQL](../language/dialect/mysql.malloynb) | `mysql` | Standard credentials |
1616
| [Trino / Presto](../language/dialect/presto-trino.malloynb) | `trino` / `presto` | Server URL + optional auth |
17+
| [MSSQL via DuckDB](../language/dialect/mssql-via-duckdb.malloynb) | `duckdb` | Query SQL Server through DuckDB's [mssql extension](https://duckdb.org/community_extensions/extensions/mssql) |
1718

1819
---
1920

@@ -93,3 +94,4 @@ Each database has unique capabilities and limitations. See the dialect documenta
9394
- [PostgreSQL](../language/dialect/postgres.malloynb) - String aggregation extensions, limited bigint precision
9495
- [MySQL](../language/dialect/mysql.malloynb) - Boolean type workarounds, full bigint precision
9596
- [Trino / Presto](../language/dialect/presto-trino.malloynb) - HyperLogLog, array operations, limited bigint precision
97+
- [MSSQL via DuckDB](../language/dialect/mssql-via-duckdb.malloynb) - Query SQL Server through DuckDB's mssql extension, no nested/array data

0 commit comments

Comments
 (0)