Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ npm install @tidbcloud/serverless

To query from TiDB Serverless, you need to create a connection first. Then you can use the connection to execute raw SQL queries.

Overlapping operations on the same connection are rejected. Await each operation before starting another, or use separate connections for concurrent queries. Each transaction or stateful handle should belong to one logical unit of work; sharing a handle across users does not provide tenant isolation.

```ts
import { connect } from '@tidbcloud/serverless'

Expand All @@ -36,7 +38,7 @@ If you want to keep session state across multiple queries, create a stateful con
> **Note:**
>
> Connections idle for 10 minutes will be closed automatically.
> The Stateful connection is not concurrent-safe. You are not allowed to run SQLs parallel in the same stateful connection.
> Overlapping queries or `close()` on the same stateful connection are rejected. Await each operation before starting another.

```ts
import { connect } from '@tidbcloud/serverless'
Expand All @@ -59,7 +61,7 @@ You can also perform interactive transactions with the serverless driver. For ex
> **Note:**
>
> Transactions idle for 10 minutes will be rolled back automatically if it has not been committed or rolled back.
> The transaction is not concurrent-safe. You are not allowed to run SQLs parallel in the same transaction.
> Overlapping queries, `commit()`, or `rollback()` on the same transaction are rejected. Await each operation before starting another.

```ts
import { connect } from '@tidbcloud/serverless'
Expand Down
129 changes: 129 additions & 0 deletions __tests__/session.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
import { connect, Config } from '../dist/index'

function response(session: string) {
return {
ok: true,
headers: { get: () => session },
json: async () => ({ types: [], rows: [] })
}
}

function deferred<T>() {
let resolve!: (value: T) => void
let reject!: (reason: Error) => void
const promise = new Promise<T>((res, rej) => {
resolve = res
reject = rej
})
return { promise, resolve, reject }
}

function connection(fetch: Config['fetch']) {
return connect({ host: 'gateway.example.com', username: 'user', password: 'secret', fetch })
}

describe('connection concurrency', () => {
test('rejects overlap without sending another query and preserves the returned session', async () => {
const pending = deferred<ReturnType<typeof response>>()
const fetch = jest
.fn()
.mockResolvedValueOnce(response('initial'))
.mockReturnValueOnce(pending.promise)
.mockResolvedValue(response('next'))
const conn = connection(fetch)
await conn.execute('select 1')
const first = conn.execute('select 2')
try {
await expect(conn.execute('select 3')).rejects.toThrow('already in progress')
expect(fetch).toHaveBeenCalledTimes(2)
expect(fetch.mock.calls[1][1].headers['TiDB-Session']).toBe('initial')
} finally {
pending.resolve(response('updated'))
await first
}
await conn.execute('select 4')
expect(fetch.mock.calls[2][1].headers['TiDB-Session']).toBe('updated')
})

test('allows retry after a failed request', async () => {
const pending = deferred<ReturnType<typeof response>>()
const fetch = jest.fn().mockReturnValueOnce(pending.promise).mockResolvedValue(response('recovered'))
const conn = connection(fetch)
const first = conn.execute('select 1')
const failure = expect(first).rejects.toThrow('network failure')
pending.reject(new Error('network failure'))
await failure
await expect(conn.execute('select 2')).resolves.toEqual([])
})

test('allows retry after an invalid session response', async () => {
const fetch = jest.fn().mockResolvedValueOnce(response('')).mockResolvedValue(response('recovered'))
const conn = connection(fetch)
await expect(conn.execute('select 1')).rejects.toThrow('empty session')
await expect(conn.execute('select 2')).resolves.toEqual([])
})

test.each(['commit', 'rollback'] as const)('rejects overlapping transaction %s', async (operation) => {
const pending = deferred<ReturnType<typeof response>>()
const fetch = jest
.fn()
.mockResolvedValueOnce(response('transaction'))
.mockReturnValueOnce(pending.promise)
.mockResolvedValue(response('done'))
const tx = await connection(fetch).begin()
const first = tx.execute('select 1')
try {
await expect(tx[operation]()).rejects.toThrow('already in progress')
expect(fetch).toHaveBeenCalledTimes(2)
} finally {
pending.resolve(response('transaction-updated'))
await first
}
await tx[operation]()
expect(fetch.mock.calls[2][1].headers['TiDB-Session']).toBe('transaction-updated')
})

test('rejects overlapping stateful close', async () => {
const pending = deferred<ReturnType<typeof response>>()
const fetch = jest
.fn()
.mockResolvedValueOnce(response('stateful'))
.mockReturnValueOnce(pending.promise)
.mockResolvedValue(response('done'))
const stateful = await connection(fetch).persist()
const first = stateful.execute('select 1')
try {
await expect(stateful.close()).rejects.toThrow('already in progress')
expect(fetch).toHaveBeenCalledTimes(2)
} finally {
pending.resolve(response('stateful-updated'))
await first
}
await stateful.close()
expect(fetch.mock.calls[2][1].headers['TiDB-Session']).toBe('stateful-updated')
})

test('allows independent transaction and stateful connections to run concurrently', async () => {
const pending = deferred<ReturnType<typeof response>>()
const fetch = jest
.fn()
.mockResolvedValueOnce(response('tx'))
.mockResolvedValueOnce(response('stateful'))
.mockReturnValueOnce(pending.promise)
.mockResolvedValue(response('other'))
const conn = connection(fetch)
const tx = await conn.begin()
const stateful = await conn.persist()
const first = tx.execute('select 1')
try {
await expect(stateful.execute('select 2')).resolves.toEqual([])
await expect(conn.execute('select 3')).resolves.toEqual([])
expect(fetch.mock.calls[2][1].headers['TiDB-Session']).toBe('tx')
expect(fetch.mock.calls[3][1].headers['TiDB-Session']).toBe('stateful')
expect(fetch.mock.calls[4][1].headers['TiDB-Session']).toBe('')
} finally {
pending.resolve(response('tx-updated'))
await first
}
})
})
89 changes: 49 additions & 40 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ export type ExecuteResult<E extends ExecuteOptions, T extends Config> = E extend
export class Connection<T extends Config> {
private config: T
private session: Session
private inFlight = false

constructor(config: T) {
this.session = null
Expand Down Expand Up @@ -121,49 +122,57 @@ export class Connection<T extends Config> {
txOptions: TxOptions = {},
statefulAction?: 'open' | 'close'
): Promise<ExecuteResult<E, T>> {
const sql = args ? format(query, args) : query
const body = JSON.stringify({ query: sql })
const debug = options.debug ?? this.config.debug ?? false
if (debug) {
console.log(`[serverless-js debug] sql: ${sql}`)
}
const resp = await postQuery<QueryExecuteResponse>(
this.config,
body,
this.session ?? '',
sql == 'BEGIN' ? txOptions.isolation : null,
debug,
statefulAction
)

this.session = resp?.session ?? null
if (this.session === null || this.session === '') {
throw new DatabaseError('empty session, please try again', 500, null)
if (this.inFlight) {
throw new Error('An operation is already in progress on this connection')
}
this.inFlight = true
try {
const sql = args ? format(query, args) : query
const body = JSON.stringify({ query: sql })
const debug = options.debug ?? this.config.debug ?? false
if (debug) {
console.log(`[serverless-js debug] sql: ${sql}`)
}
const resp = await postQuery<QueryExecuteResponse>(
this.config,
body,
this.session ?? '',
sql == 'BEGIN' ? txOptions.isolation : null,
debug,
statefulAction
)

this.session = resp?.session ?? null
if (this.session === null || this.session === '') {
throw new DatabaseError('empty session, please try again', 500, null)
}

const arrayMode = options.arrayMode ?? this.config.arrayMode ?? false
const fullResult = options.fullResult ?? this.config.fullResult ?? false
const decoders = { ...this.config.decoders, ...options.decoders }

const fields = resp?.types ?? []
const rows = resp ? parse(fields, resp?.rows ?? [], cast, arrayMode, decoders) : []

if (fullResult) {
const rowsAffected = resp?.rowsAffected ?? null
const lastInsertId = resp?.sLastInsertID ?? null
const typeByName = (acc, { name, type }) => ({ ...acc, [name]: type })
const types = fields.reduce<Types>(typeByName, {})
return {
statement: sql,
types,
rows,
rowsAffected,
lastInsertId,
rowCount: rows.length
} as ExecuteResult<E, T>
}
const arrayMode = options.arrayMode ?? this.config.arrayMode ?? false
const fullResult = options.fullResult ?? this.config.fullResult ?? false
const decoders = { ...this.config.decoders, ...options.decoders }

const fields = resp?.types ?? []
const rows = resp ? parse(fields, resp?.rows ?? [], cast, arrayMode, decoders) : []

if (fullResult) {
const rowsAffected = resp?.rowsAffected ?? null
const lastInsertId = resp?.sLastInsertID ?? null
const typeByName = (acc, { name, type }) => ({ ...acc, [name]: type })
const types = fields.reduce<Types>(typeByName, {})
return {
statement: sql,
types,
rows,
rowsAffected,
lastInsertId,
rowCount: rows.length
} as ExecuteResult<E, T>
}

return rows as ExecuteResult<E, T>
return rows as ExecuteResult<E, T>
} finally {
this.inFlight = false
}
}
}

Expand Down
Loading