### Development Setup

Source: https://github.com/planetscale/database-js/blob/main/README.md

Basic commands to set up the development environment for the PlanetScale Database JS project, including installing dependencies and running tests.

```bash
npm install
npm test
```

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

### Install PlanetScale Database Driver

Source: https://github.com/planetscale/database-js/blob/main/README.md

Installs the PlanetScale database driver using npm. This is the first step to using the driver in your JavaScript or TypeScript project.

```sh
npm install @planetscale/database
```

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

### Custom Query Parameter Formatting

Source: https://github.com/planetscale/database-js/blob/main/README.md

Shows how to use custom functions for formatting query parameters, including support for both positional `?` and named `:param` placeholders. It provides an example using the `sqlstring` library.

```typescript
const results1 = await conn.execute('select 1 from dual where 1=?', [42])
const results2 = await conn.execute('select 1 from dual where 1=:id', { id: 42 })

import { connect } from '@planetscale/database'
import SqlString from 'sqlstring'

const config = {
  format: SqlString.format,
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [42])
console.log(results)
```

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

### Basic Connection and Query Execution

Source: https://github.com/planetscale/database-js/blob/main/README.md

Demonstrates how to establish a connection to PlanetScale using configuration options and execute a simple SQL query. It uses the `connect` function with host, username, and password.

```typescript
import { connect } from '@planetscale/database'

const config = {
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [1])
console.log(results)
```

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

### Using Connection Factory

Source: https://github.com/planetscale/database-js/blob/main/README.md

Illustrates the use of the `Client` class to create new connections for each transaction or request handler. This is useful for managing connection lifecycles in dynamic environments.

```typescript
import { Client } from '@planetscale/database'

const client = new Client({
  host: '<host>',
  username: '<user>',
  password: '<password>'
})

const conn = client.connection()
const results = await conn.execute('select 1 from dual')
console.log(results)
```

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

### Connection using Database URL

Source: https://github.com/planetscale/database-js/blob/main/README.md

Shows how to configure the PlanetScale connection using a single database URL, which can be sourced from environment variables. This simplifies configuration by consolidating connection details.

```typescript
import { connect } from '@planetscale/database'

const config = {
  url: process.env['DATABASE_URL'] || 'mysql://user:pass@host'
}

const conn = connect(config)
```

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

### Using Custom Fetch Function (undici)

Source: https://github.com/planetscale/database-js/blob/main/README.md

Explains how to provide a custom `fetch` implementation, particularly for older Node.js versions or when specific fetch behavior is needed. It recommends the `undici` package.

```typescript
import { connect } from '@planetscale/database'
import { fetch } from 'undici'

const config = {
  fetch,
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.execute('select 1 from dual')
console.log(results)
```

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

### Using Custom Fetch Function (fetch-h2)

Source: https://github.com/planetscale/database-js/blob/main/README.md

Demonstrates using the `fetch-h2` package to leverage HTTP/2 with the PlanetScale driver, compatible with Node.js 12+.

```typescript
import { connect } from '@planetscale/database'
import { context } from 'fetch-h2'
const { fetch, disconnectAll } = context()

const config = {
  fetch,
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.execute('select 1 from dual')
console.log(results)
await disconnectAll()
```

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

### Performing Database Transactions

Source: https://github.com/planetscale/database-js/blob/main/README.md

Demonstrates how to execute database transactions safely using the `transaction` function. If any errors occur within the transaction block, it will be automatically rolled back.

```typescript
import { connect } from '@planetscale/database'

const config = {
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.transaction(async (tx) => {
  const whenBranch = await tx.execute('INSERT INTO branches (database_id, name) VALUES (?, ?)', [42, "planetscale"])
  const whenCounter = await tx.execute('INSERT INTO slotted_counters(record_type, record_id, slot, count) VALUES (?, ?, RAND() * 100, 1) ON DUPLICATE KEY UPDATE count = count + 1', ['branch_count', 42])
  return [whenBranch, whenCounter]
})
console.log(results)
```

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

### PlanetScale Database Table Schema

Source: https://github.com/planetscale/database-js/blob/main/golden/cli.txt

This snippet displays the schema of a table within a PlanetScale database. It outlines the columns, their data types, and other relevant metadata. This is useful for understanding the structure of your data.

```APIDOC
Table Schema:
  Columns:
    - id: INTEGER
    - a: INTEGER
    - b: INTEGER
    - c: INTEGER
    - d: INTEGER
    - e: INTEGER
    - f: FLOAT
    - g: FLOAT
    - h: FLOAT
    - i: FLOAT
    - j: HEX
    - k: DATE
    - l: DATETIME
    - m: DATETIME
    - n: TIME
    - o: INTEGER
    - p: VARCHAR
    - q: VARCHAR
    - r: HEX
    - s: HEX
    - t: HEX
    - u: HEX
    - v: HEX
    - w: HEX
    - x: VARCHAR
    - y: VARCHAR
    - z: VARCHAR
    - aa: VARCHAR
    - ab: VARCHAR
    - ac: VARCHAR
    - ad: JSON
    - ae: BLOB
    - af: BLOB
    - ag: BLOB
    - ah: BLOB
    - ai: INTEGER
    - aj: INTEGER
    - ak: INTEGER
    - al: INTEGER
    - xa: VARCHAR
    - xb: VARCHAR
    - xc: HEX
    - xd: VARCHAR
```

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

### Row Return Values as Objects or Arrays

Source: https://github.com/planetscale/database-js/blob/main/README.md

Illustrates how to specify the format of returned rows using the `as` option in the `execute` method. Rows can be returned as an array of column values (`'array'`) or as an object with column names as keys (`'object'`).

```typescript
const query = 'select 1 as one, 2 as two where 1=?'
const objects = conn.execute(query, [1], { as: 'object' })
// objects.rows => [{one: '1', two: '2'}]

const arrays = conn.execute(query, [1], { as: 'array' })
// arrays.rows => [['1', '2']]
```

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

### Custom Type Casting with Connection Configuration

Source: https://github.com/planetscale/database-js/blob/main/README.md

Demonstrates how to provide a custom `cast` function in the connection configuration to handle specific data types like INT64 and UINT64 by converting them to BigInt. This function is applied to all queries made with this connection.

```typescript
import { connect, cast } from '@planetscale/database'

function inflate(field, value) {
  if (field.type === 'INT64' || field.type === 'UINT64') {
    return BigInt(value)
  }
  return cast(field, value)
}

const config = {
  cast: inflate,
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
```

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

### Custom Type Casting with Execute Option

Source: https://github.com/planetscale/database-js/blob/main/README.md

Shows how to override the connection's `cast` function for a specific query by providing a custom `cast` function within the `execute` options. This allows for field-specific casting, such as converting a 'balance' field to BigInt.

```typescript
const result = await conn.execute(
  'SELECT userId, SUM(balance) AS balance FROM UserBalanceItem GROUP BY userId',
  {},
  {
    cast: (field, value) => {
      if (field.name === 'balance') {
        return BigInt(value)
      }
      return cast(field, value)
    }
  }
)
```

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

### PlanetScale Database Row Data

Source: https://github.com/planetscale/database-js/blob/main/golden/cli.txt

This snippet shows a sample row of data retrieved from a PlanetScale database table. It demonstrates how data is represented, including various data types like integers, floats, dates, times, hexadecimal strings, and JSON objects.

```javascript
const row = {
  id: 1,
  a: 1,
  b: 1,
  c: 1,
  d: 1,
  e: 1,
  f: 1.1,
  g: 1.1,
  h: 1.1,
  i: 1.1,
  j: '0x07',
  k: '1000-01-01',
  l: '1000-01-01 01:01:01',
  m: '1970-01-01 00:01:01',
  n: '01:01:01',
  o: 2006,
  p: 'p',
  q: 'q',
  r: '0x72000000',
  s: '0x73',
  t: '0x74',
  u: '0x75',
  v: '0x76',
  w: '0x77',
  x: 'x',
  y: 'y',
  z: 'z',
  aa: 'aa',
  ab: 'foo',
  ac: 'foo,bar',
  ad: '{"ad": null}',
  ae: '0x0000000001020000000300000000000000000000000000000000000000000000000000F03F000000000000F03F00000000000000400000000000000000',
  af: '0x000000000101000000000000000000F03F000000000000F03F',
  ag: '0x0000000001020000000300000000000000000000000000000000000000000000000000F03F000000000000F03F00000000000000400000000000000000',
  ah: '0x000000000103000000020000000400000000000000000000000000000000000000000000000000000000000000000084000000000000008400000000000000000000000000000000000000000000000004000000000000000000F03F000000000000F03F000000000000F03F00000000000000400000000000000040000000000000F03F000000000000F03F000000000000F03F',
  ai: 1,
  aj: 1,
  ak: 1,
  al: 1,
  xa: 'xa',
  xb: 'xb',
  xc: '0x78630000',
  xd: 'xd'
}; console.log(row);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.