### Project commands

Source: https://github.com/drizzle-team/waddler-website/blob/main/README.md

Commands to install dependencies, run the dev server, build the site, preview the build, run Astro CLI commands, and get help.

```bash
pnpm install
```

```bash
pnpm run dev
```

```bash
pnpm run build
```

```bash
pnpm run preview
```

```bash
pnpm run astro ...
```

```bash
pnpm run astro -- --help
```

--------------------------------

### Install Waddler and @libsql/client

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-turso.mdx

Install the required packages: waddler and @libsql/client.

```bash
npm install waddler @libsql/client
```

--------------------------------

### Install waddler and op-sqlite packages

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/op-sqlite-new.mdx

Installs the required packages: waddler and @op-engineering/op-sqlite. This is step 2 of the setup process.

```bash
waddler @op-engineering/op-sqlite
```

--------------------------------

### Install Waddler and Neon serverless driver

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-neon.mdx

Install the required packages: waddler and @neondatabase/serverless.

```bash
waddler @neondatabase/serverless
```

--------------------------------

### Install packages with npm

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/connect-clickhouse.mdx

Run this npm command to install both the 'waddler' and '@clickhouse/client' packages.

```bash
npm install waddler @clickhouse/client

```

--------------------------------

### Install Waddler and PGlite packages

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-pglite.mdx

Install the required packages using npm. The command installs 'waddler' and '@electric-sql/pglite'.

```bash
npm install waddler @electric-sql/pglite
```

--------------------------------

### Install waddler and mysql2

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/mysql/connect-mysql.mdx

Install the waddler and mysql2 packages using npm.

```bash
waddler mysql2
```

--------------------------------

### Install Waddler and postgres packages

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-supabase.mdx

Install the Waddler and postgres packages using npm.

```bash
waddler postgres
```

--------------------------------

### Install waddler and @planetscale/database

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/mysql/connect-planetscale.mdx

Install the Waddler PlanetScale serverless package and the official PlanetScale database driver.

```bash
waddler @planetscale/database
```

--------------------------------

### Install packages for TiDB Serverless

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/mysql/connect-tidb.mdx

Install the waddler and @tidbcloud/serverless packages using npm.

```bash
npm install waddler @tidbcloud/serverless
```

--------------------------------

### Install waddler and @xata.io/client

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-xata.mdx

Install the waddler package and the Xata client library. This is the first step to connect Waddler to Xata.

```bash
npm install waddler @xata.io/client
```

--------------------------------

### Install Waddler and DuckDB Node API dependencies

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/gel/quick-start.mdx

Install the required packages: waddler and @duckdb/node-api. This is the first step in the quick start.

```bash
npm install waddler @duckdb/node-api
```

--------------------------------

### Install pg-query-stream package

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/query-stream.mdx

Install the pg-query-stream package via npm to enable streaming and chunking features with Waddler.

```bash
npm install pg-query-stream
```

--------------------------------

### Install waddler and better-sqlite3

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-sqlite.mdx

Install the waddler package, the better-sqlite3 driver, and the TypeScript types for better-sqlite3.

```bash
waddler better-sqlite3
-D @types/better-sqlite3
```

--------------------------------

### Install waddler pg and @types/pg

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-postgresql.mdx

Install the waddler PostgreSQL driver and the TypeScript types for node-postgres.

```bash
waddler pg
-D @types/pg
```

--------------------------------

### Example output of chunked query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/chunked.mdx

Shows the console output from the chunked query example, displaying two user objects per chunk.

```shell
[
	{
  	id: 1,
		name: "Alex",
	},
	{
	  id: 2,
		name: "Oleksii",
	}
]
…
```

--------------------------------

### Install waddler package

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-cloudflare-d1.mdx

Install the waddler package using npm.

```bash
npm install waddler
```

--------------------------------

### Basic SQL template usage

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/gel/sql-template.mdx

Import waddler from 'waddler/gel' and create a sql instance using the DATABASE_URL environment variable. The example runs a simple query 'select 1'.

```ts
import { waddler } from "waddler/gel";

const sql = waddler(process.env.DATABASE_URL!);

await sql`select 1`;
```

--------------------------------

### Install Waddler pg and drizzle-kit

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-nile.mdx

Install the Waddler PostgreSQL driver and drizzle-kit as a dev dependency.

```bash
waddler pg
-D drizzle-kit
```

--------------------------------

### Install packages with npm

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/do-new.mdx

Install the required packages: waddler, dotenv, and as dev dependencies wrangler and @cloudflare/workers-types.

```bash
waddler dotenv
-D wrangler @cloudflare/workers-types
```

--------------------------------

### Run index.ts with Bun

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/get-started/bun-sql-new.mdx

Runs the index.ts file with Bun. This is the command to execute the script after completing the setup steps.

```bash
bun src/index.ts
```

--------------------------------

### Run first query with sql template

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/gel/quick-start.mdx

Execute a simple SQL query using the tagged template literal. This is the third step in the quick start.

```ts
const result = await sql`select 1`;
```

--------------------------------

### ClickHouse metadata type and example for command methods

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/logger.mdx

Shows the metadata type returned by `sql` command methods (`.command()` and unsafe variants) for ClickHouse, including `query_id`, `summary`, and `response_headers`. Includes a concrete example with sample response headers.

```typescript
// metadata type for queries:
await sql`...`.command();
await sql.unsafe('...', [...]).command();

type metadataType = {
  query_id: string;
  summary?: {
    read_rows: string;
    read_bytes: string;
    written_rows: string;
    written_bytes: string;
    total_rows_to_read: string;
    result_rows: string;
    result_bytes: string;
    elapsed_ns: string;
    /** Available only after ClickHouse 24.9 */
    real_time_microseconds?: string;
  };
  response_headers: Record<string, string | string[] | undefined>;
}

// metadata example
{
  query_id: '4e8e2236-149f-4a33-a475-ecfe988374ed',
  summary: {
    read_rows: '0',
    read_bytes: '0',
    written_rows: '0',
    written_bytes: '0',
    total_rows_to_read: '0',
    result_rows: '0',
    result_bytes: '0',
    elapsed_ns: '11163000'
  },
  response_headers: {
    'x-clickhouse-summary': '{"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0","result_rows":"0","result_bytes":"0","elapsed_ns":"11163000"}',
    date: 'Tue, 12 Aug 2025 01:57:59 GMT',
    connection: 'Keep-Alive',
    'content-type': 'text/plain; charset=UTF-8',
    'access-control-expose-headers': 'X-ClickHouse-Query-Id,X-ClickHouse-Summary,X-ClickHouse-Server-Display-Name,X-ClickHouse-Format,X-ClickHouse-Timezone,X-ClickHouse-Exception-Code',
    'x-clickhouse-server-display-name': 'b1fb20216212',
    'transfer-encoding': 'chunked',
    'x-clickhouse-query-id': '4e8e2236-149f-4a33-a475-ecfe988374ed',
    'x-clickhouse-timezone': 'UTC',
    'keep-alive': 'timeout=10, max=9999'
  }
}
```

--------------------------------

### Connect with Bun SQLite and Expo SQLite

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-overview.mdx

Examples for runtime-specific drivers: Bun SQLite (in-memory or file-based) and Expo SQLite (using openDatabaseSync).

```ts
import { waddler } from "waddler/bun-sqlite"

const sql = waddler(); // <--- will create an in-memory db
const sql = waddler("./sqlite.db");
```

```ts
import { waddler } from "waddler/expo-sqlite";
import { openDatabaseSync } from "expo-sqlite";

const expo = openDatabaseSync("db.db");
const sql = waddler({ client: expo });
```

--------------------------------

### Initialize Neon Websockets driver for Node.js

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-neon.mdx

For Node.js environments, install 'ws' and 'bufferutil' and set the ws option in the Waddler config.

```typescript
// For Node.js - make sure to install the 'ws' and 'bufferutil' packages
import { waddler } from 'waddler/neon-serverless';
import ws from 'ws';

const sql = waddler({
  connection: process.env.DATABASE_URL,
  ws: ws,
});

const result = await sql`select 1;`;
```

--------------------------------

### Run index.ts with tsx

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/RunFile.mdx

Use the tsx command to run the index.ts script. tsx is already installed in the project.

```bash
tsx src/index.ts
```

--------------------------------

### Database connection URL format

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/connect-overview.mdx

Example of a database connection URL with annotations showing the role, password, hostname, port, and database components.

```text
https://alex:AbC123dEf@ep-cool-darkness-123456.com:8443/dbname
        └──┘ └───────┘ └─────────────────────────┘  └──┘  └──┘
          ʌ    ʌ          ʌ                           ʌ     ʌ
    role -│    │          │- hostname                 │     │ - database
               │                                      │ - port
               │- password
```

--------------------------------

### Configure and use queryStream extension

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/query-stream.mdx

Install pg-query-stream and add the queryStream extension to Waddler. Then use the .stream() method to iterate over query results asynchronously.

```ts
import { queryStream } from 'waddler/extensions/pg-query-stream';

const sql = waddler(process.env.DATABASE_URL!, { extensions: [queryStream()] });

const result = sql`select * from users`.stream();

for await (const row of result) {
  console.log(row);
}
```

--------------------------------

### Combining sql.identifier and sql.default

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/sql-default.mdx

Shows a complete example using sql.identifier for table and column names alongside sql.default for inserting default values.

```ts
const table = sql.identifier("users")
const columns = sql.identifier(["id", "name", "age"]);
const values = sql.values([
  [sql.default, "Oleksii", 20],
  [sql.default, "Alex", 23],
]);

await sql`insert into ${table} (${columns}) values ${values} returning ${columns};`;
```

```sql
insert into \`users\` (\`id\`, \`name\`, \`age\`) values (default, 'Oleksii', 20), (default, 'Alex', 23);
```

--------------------------------

### Configure wrangler.toml for D1

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/d1-new.mdx

Example wrangler.toml configuration for a D1 database. Replace placeholders like 'YOUR PROJECT NAME' and 'YOUR DB ID' with actual values.

```toml
name = "YOUR PROJECT NAME"
main = "src/index.ts"
compatibility_date = "2022-11-07"
node_compat = true

[[ d1_databases ]]
binding = "DB"
database_name = "YOUR DB NAME"
database_id = "YOUR DB ID"
```

--------------------------------

### Example 1: Single schema file

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/SchemaFilePaths.mdx

Configures Drizzle Kit to use a single schema file at `./src/schema.ts`. The file tree highlights the schema file at line 7.

```plaintext
📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ ...
 │ ├ 📜 index.ts
 │ └ 📜 schema.ts 
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

```

```ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/schema.ts",
});

```

--------------------------------

### Initialize Gel project with gel project init

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/gel/get-started/gel-new.mdx

Initializes a Gel project in the current directory, setting up the necessary configuration files and database connection.

```bash
gel project init
```

--------------------------------

### Initialize postgres.js driver and query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-postgresql.mdx

Initialize the postgres.js driver with Waddler and run a query. The first example uses a connection string; the second shows how to pass connection options like ssl.

```typescript
import { waddler } from 'waddler/postgres-js';

const sql = waddler(process.env.DATABASE_URL);

const result = await sql`select 1;`;
```

```typescript
import { waddler } from 'waddler/postgres-js';

// You can specify any property from the postgres-js connection options
const sql = waddler({ 
  connection: { 
    url: process.env.DATABASE_URL, 
    ssl: true 
  }
});

const result = await sql`select 1;`;
```

--------------------------------

### Set up Turso environment variables in .env

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/turso-new.mdx

Create a .env file in the root of your project and add your Turso database URL and auth token. These values are required for connecting to your Turso database.

```plaintext
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
```

--------------------------------

### Initialize waddler libsql client (default)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/sqlite/LibsqlTabs.mdx

Imports waddler from 'waddler/libsql' and creates a client with connection URL and auth token from environment variables.

```typescript
import { waddler } from 'waddler/libsql';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});
```

--------------------------------

### Initialize waddler libsql client (web)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/sqlite/LibsqlTabs.mdx

Imports waddler from 'waddler/libsql/web' and creates a client with connection URL and auth token from environment variables.

```typescript
import { waddler } from 'waddler/libsql/web';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});
```

--------------------------------

### Install expo-sqlite package

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/expo-new.mdx

Installs the expo-sqlite package, which provides SQLite database access for Expo apps.

```bash
expo install expo-sqlite
```

--------------------------------

### Initialize Waddler with Bun SQL and run a query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-bun-sql.mdx

Initialize the Waddler driver for Bun SQL. The first example uses the default connection from DATABASE_URL. The second shows how to pass an existing Bun SQL client instance.

```typescript
import 'dotenv/config';
import { waddler } from 'waddler/bun-sql';

const sql = waddler(process.env.DATABASE_URL);

const result = await sql`select 1;`;
```

```typescript
import 'dotenv/config';
import { waddler } from 'waddler/bun-sql';
import { SQL } from 'bun';

const client = new SQL(process.env.DATABASE_URL!);
const sql = waddler({ client });

const result = await sql`select 1;`;
```

--------------------------------

### Install waddler package

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/get-started/expo-new.mdx

Installs the waddler package using npm. This is required to use Waddler with Expo SQLite.

```bash
waddler
```

--------------------------------

### Initialize driver with existing client (web)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-turso.mdx

Use an existing @libsql/client instance with Waddler in a web environment. The client is created with DATABASE_URL and DATABASE_AUTH_TOKEN environment variables.

```typescript
import { waddler } from 'waddler/libsql/web';
import { createClient } from '@libsql/client/web';

const client = createClient({ 
  url: process.env.DATABASE_URL,
  authToken: process.env.DATABASE_AUTH_TOKEN
});

const sql = waddler({ client });

const result = await sql`select 1;`.all();
```

--------------------------------

### Install Waddler PostgreSQL drivers

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-prisma-postgres.mdx

Install the Waddler PostgreSQL drivers for node-postgres (pg) and postgres.js. Run the appropriate command for your chosen driver.

```bash
waddler pg
```

```bash
waddler postgres
```

--------------------------------

### Initialize Waddler with Vercel Postgres and run a query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-vercel-postgres.mdx

Import `waddler` from `waddler/vercel-postgres`, create a client, and execute a simple query to verify the connection. Requires the `waddler` and `@vercel/postgres` packages installed.

```typescript
import { waddler } from 'waddler/vercel-postgres';

const sql = waddler();

const result = await sql`select 1;`;
```

--------------------------------

### Initialize node-postgres driver and query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/connect-postgresql.mdx

Initialize the node-postgres driver with Waddler and run a simple query. The first example uses a connection string; the second shows how to pass connection options like ssl.

```typescript
import 'dotenv/config';
import { waddler } from 'waddler/node-postgres';

const sql = waddler(process.env.DATABASE_URL!);
const result = await sql`select 1;`;
```

```typescript
import 'dotenv/config';
import { waddler } from 'waddler/node-postgres';

// You can specify any property from the node-postgres connection options
const sql = waddler({ 
  connection: { 
    connectionString: process.env.DATABASE_URL!,
    ssl: true
  }
});
const result = await sql`select 1;`;
```

--------------------------------

### Install pg-query-stream extension

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/chunked.mdx

Required for streaming in chunks with node-postgres and other PostgreSQL drivers. Install the `pg-query-stream` package and add the `queryStream()` extension to the Waddler client.

```ts
import { queryStream } from 'waddler/extensions/pg-query-stream';

const sql = waddler(process.env.DATABASE_URL!, { extensions: [queryStream()] })
```

--------------------------------

### Generate and apply Gel migrations

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/gel/get-started/gel-new.mdx

Generates a Gel migration file and then applies it to the database. Run these commands in sequence to push the schema changes.

```bash
gel migration create
```

```bash
gel migration apply
```

--------------------------------

### Initialize Waddler with better-sqlite3 driver

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-sqlite.mdx

Initialize the Waddler driver with the better-sqlite3 driver. The first example uses a connection URL from the DATABASE_URL environment variable. The second example shows how to pass a connection object with a source property.

```typescript
import { waddler } from 'waddler/better-sqlite3';

const sql = waddler(process.env.DATABASE_URL);

const result = await sql`select 1;`;
```

```typescript
import { waddler } from 'waddler/better-sqlite3';

// You can specify any property from the better-sqlite3 connection options
const sql =  waddler({ connection: { source: process.env.DATABASE_URL }});

const result = await sql`select 1;`;
```

--------------------------------

### Initialize Waddler with libsql driver

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-sqlite.mdx

Initialize the Waddler driver with the libsql driver. The first example uses a connection URL from the DATABASE_URL environment variable. The second example shows how to pass a connection object with url and authToken properties.

```typescript
import { waddler } from 'waddler/libsql';

const sql = waddler(process.env.DATABASE_URL);
 
const result = await sql`select 1;`;
```

```typescript
import { waddler } from 'waddler/libsql';

// You can specify any property from the libsql connection options
const sql = waddler({ connection: { url:'', authToken: '' }});
 
const result = await sql`select 1;`;
```

--------------------------------

### Initialize waddler libsql client (node)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/sqlite/LibsqlTabs.mdx

Imports waddler from 'waddler/libsql/node' and creates a client with connection URL and auth token from environment variables.

```typescript
import { waddler } from 'waddler/libsql/node';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});
```

--------------------------------

### Initialize waddler libsql client (web sockets)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/sqlite/LibsqlTabs.mdx

Imports waddler from 'waddler/libsql/ws' and creates a client with connection URL and auth token from environment variables.

```typescript
import { waddler } from 'waddler/libsql/ws';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});
```

--------------------------------

### ClickHouse metadata type and example for query methods

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/logger.mdx

Shows the metadata type returned by `sql` query methods (`.query()` and unsafe variants) for ClickHouse, including fields like `query_id`, `meta`, `statistics`, and `rows`. Includes a concrete example of the metadata object.

```typescript
// metadata type for queries:
await sql`...`.query();
await sql`...`;
await sql.unsafe('...', [...]).query();
await sql.unsafe('...', [...]);

type metadataType = {
  query_id?: string;
  totals?: T;
  extremes?: Record<string, any>;
  meta?: Array<{
      name: string;
      type: string;
  }>;
  statistics?: {
      elapsed: number;
      rows_read: number;
      bytes_read: number;
  };
  rows?: number;
  rows_before_limit_at_least?: number;
}

// metadata example
{
	meta: [ { name: "_CAST(1, 'Int32')", type: 'Int32' } ],
	rows: 1,
	statistics: { elapsed: 0.013193458, rows_read: 1, bytes_read: 1 }
}
```

--------------------------------

### Metadata type and example for durable-sqlite

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/logger.mdx

For durable-sqlite, the metadata type includes `columnNames`, `rowsRead`, and `rowsWritten`.

```ts
// metadata type
type metadataType = {
  columnNames: string[];
  get rowsRead(): number;
  get rowsWritten(): number;
}

// metadata example
{ columnNames: [ '?' ], rowsRead: 0, rowsWritten: 0 }
```

--------------------------------

### Metadata type and example for libsql

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/logger.mdx

For libsql, the metadata type includes `columns`, `columnTypes`, `rowsAffected`, and `lastInsertRowid`.

```ts
// metadata type
type metadataType = {
  columns: Array<string>;
  columnTypes: Array<string>;
  rowsAffected: number;
  lastInsertRowid: bigint | undefined;
}

// metadata example
{
  columnTypes: [ '' ],
  columns: [ '?' ],
  lastInsertRowid: undefined,
  rowsAffected: 0
}
```

--------------------------------

### Connect to serverless databases with Waddler

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/clickhouse/connect-overview.mdx

Shows how to initialize Waddler for various serverless databases: Neon HTTP, Neon with websockets, Vercel Postgres, PlanetScale HTTP, and Cloudflare D1. Each uses a different import path and initialization method.

```ts
import { waddler } from "waddler/neon-http";

const sql = waddler(process.env.DATABASE_URL);
```

```ts
import { waddler } from "waddler/neon-serverless";

const sql = waddler(process.env.DATABASE_URL);
```

```ts
import { waddler } from "waddler/vercel-postgres";

const sql = waddler();
```

```ts
import { waddler } from "waddler/planetscale";

const sql = waddler(process.env.DATABASE_URL);
```

```ts
import { waddler } from "waddler/d1";

const sql = waddler({ connection: env.DB });
```

--------------------------------

### xata-http metadata type and example

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/logger.mdx

Metadata structure for the xata-http driver. Includes columns and an optional warning.

```ts
// metadata type
type metadataType = {
  columns: Array<{
    name: string;
    type: string;
  }>;
  warning?: string;
}

// metadata example
{
  rows: undefined,
	warning: undefined,
	columns: [ { name: '?column?', type: 'text' } ]
}
```

--------------------------------

### Initialize waddler libsql client (http)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/mdx/get-started/sqlite/LibsqlTabs.mdx

Imports waddler from 'waddler/libsql/http' and creates a client with connection URL and auth token from environment variables.

```typescript
import { waddler } from 'waddler/libsql/http';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});
```

--------------------------------

### Initialize driver with existing client (default)

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-turso.mdx

Use an existing @libsql/client instance with Waddler in a Node.js environment. The client is created with DATABASE_URL and DATABASE_AUTH_TOKEN environment variables.

```typescript
import { waddler } from 'waddler/libsql';
import { createClient } from '@libsql/client';

const client = createClient({ 
  url: process.env.DATABASE_URL,
  authToken: process.env.DATABASE_AUTH_TOKEN
});

const sql = waddler({ client });

const result = await sql`select 1;`.all();
```

--------------------------------

### pglite metadata type and example

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/logger.mdx

Metadata structure for the pglite driver. Includes affectedRows, fields, and an optional blob.

```ts
// metadata type
type metadataType = {
  affectedRows?: number;
  fields: {
    name: string;
    dataTypeID: number;
  }[];
  blob?: Blob;
}

// metadata example
{ 
  fields: [ { name: '?column?', dataTypeID: 25 } ],
  affectedRows: 0 
}
```

--------------------------------

### SQL template: basic parameterized query

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/landing/showcase.mdx

Shows how to wrap a driver with waddler and execute a parameterized query. The first example imports from a generic subpackage, the second from 'waddler/duckdb-neo'. The SQL output shows the parameter placeholder $1 and the passed parameter array.

```ts
// Import from any driver subpackage to wrap it with waddler
import { waddler } from 'waddler/...';

const sql = waddler({ dbUrl: "" })

await sql`select * from "users" where "id" = ${10}`;
```

```ts
// Example wrapping "duckdb-neo" driver with waddler
import { waddler } from 'waddler/duckdb-neo';

const sql = waddler({ dbUrl: ":memory:" })

await sql`select * from "users" where "id" = ${10}`;
```

```sql
select * from "users" where "id" = $1;
-- 10 will be passed as a param [10]
```

--------------------------------

### neon-serverless metadata type and example

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/logger.mdx

Metadata structure for the neon-serverless driver. Includes command, rowCount, oid, and fields.

```ts
// metadata type
type metadataType = {
  command: string;
  rowCount: number | null;
  oid: number;
  fields: {
    name: string;
    tableID: number;
    columnID: number;
    dataTypeID: number;
    dataTypeSize: number;
    dataTypeModifier: number;
    format: string;
  }[];
}

// metadata example:
{
  command: 'SELECT',
  fields: [
    Field {
      name: '?column?',
      tableID: 0,
      columnID: 0,
      dataTypeID: 25,
      dataTypeSize: -1,
      dataTypeModifier: -1,
      format: 'text'
    }
  ],
  oid: null,
  rowCount: 1
}
```

--------------------------------

### neon-http metadata type and example

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/pg/logger.mdx

Metadata structure for the neon-http driver. Includes fields, command, rowCount, and rowAsArray.

```ts
// metadata type
type metadataType = {
  fields: {
    name: string;
    tableID: number;
    columnID: number;
    dataTypeID: number;
    dataTypeSize: number;
    dataTypeModifier: number;
    format: string;
  }[];
  command: string;
  rowCount: number;
  rowAsArray: ArrayMode;
}

// metadata example
{
  command: 'SELECT',
  fields: [
    {
      name: '?column?',
      dataTypeID: 25,
      tableID: 0,
      columnID: 0,
      dataTypeSize: -1,
      dataTypeModifier: -1,
      format: 'text'
    }
  ],
  rowAsArray: false,
  rowCount: 1
}
```

--------------------------------

### Configure D1 database in wrangler.json

Source: https://github.com/drizzle-team/waddler-website/blob/main/src/content/docs/sqlite/connect-cloudflare-d1.mdx

Example wrangler.json configuration for a D1 database. Replace placeholders with your project details.

```json
{
    "name": "YOUR_PROJECT_NAME",
    "main": "src/index.ts",
    "compatibility_date": "2024-09-26",
    "compatibility_flags": [
        "nodejs_compat"
    ],
    "d1_databases": [
        {
            "binding": "BINDING_NAME",
            "database_name": "YOUR_DB_NAME",
            "database_id": "YOUR_DB_ID",
            "migrations_dir": "waddler/migrations"
        }
    ]
}
```