db-connect

⚠️ This was an experimental project and is not supported.

Connect your SQL database to Cloudflare Workers. Import this lightweight Javascript library to execute commands or cache queries from a database through an Argo Tunnel. Although designed for Workers, this library can be used in any environment that has access to the Fetch and SubtleCrypto APIs.

Installation

npm i -s @cloudflare/db-connect

Example

import{DbConnect}from'@cloudflare/db-connect'constdb=newDbConnect({host: 'sql.mysite.com',// Hostname of an Argo TunnelclientId: 'xxx',// Client ID of an Access service tokenclientSecret: 'xxx'// Client Secret of an Access service token})asyncfunctionfindBirthday(name){constresp=awaitdb.submit({statement: 'SELECT * FROM users WHERE name = ? LIMIT 1',arguments: [name],cacheTtl: 60})if(!resp.ok){returnnewError('oops! could not find user.')}constusers=awaitresp.json()// [ { "id": 1111,// "name": "Matthew",// "birthday": "2009-07-01" } ]returnusers[0].birthday}findBirthday('Matthew').then(bday=>console.log(bday))

Quickstart

db-connect requires that you setup Cloudflare Access, Argo Tunnel, and Workers. You can use the quickstart command below or read the quickstart file for details on how to set this up yourself.

npm i -g @cloudflare/db-connect
db-connect-quickstart

Databases

db-connect supports the following database drivers out-of-the-box. If your database is not explicitly on the list it may still be supported. For instance, MariaDB uses the MySQL protocol and CockroachDB uses the PostgreSQL protocol.

• PostgreSQL
• MySQL
• MSSQL
• Clickhouse
• SQLite3

Documentation

new DbConnect(options)

import{DbConnect}from'@cloudflare/db-connect'constdb=newDbConnect({
host,// required, hostname of your Argo Tunnel running in db-connect mode.
clientId,// recommended, client id from your Access service token.
clientSecret,// recommended, client secret from your Access service token.})

Promise<Response> db.ping()

import{DbConnect}from'@cloudflare/db-connect'constdb=newDbConnect({...})asyncfunctionmyPing(){constresp=awaitdb.ping()if(resp.ok){returntrue}thrownewError(awaitresp.text())}

new Command(options)

import{Command}from'@cloudflare/db-connect'constcmd=newCommand({
statement,// required, the database statement to submit.
arguments,// optional, either an array or object of arguments.
mode,// optional, type of command as either 'query' or 'exec'.
isolation,// optional, type of transaction isolation, defaults to 'none' for no transactions.
timeout,// optional, number of seconds before a timeout, defaults to infinite.
cacheTtl,// optional, number of seconds to cache responses, defaults to -1.
staleTtl,// optional, after cacheTtl expires, number of seconds to serve stale, defaults to -1.})

Promise<Response> db.submit(command)

import{DbConnect,Command}from'@cloudflare/db-connect'constdb=newDbConnect({...})constcmd=newCommand({statement: 'SELECT COUNT(*) AS n FROM books',cacheTtl: 60})asyncfunctionmySubmit(){constresp=awaitdb.submit(cmd)if(resp.ok){returnawaitresp.json()// [ { "n": 1234 } ]}thrownewError(awaitresp.text())}

Testing

If you want to test db-connect without a database you can use the following command to create an in-memory SQLite3 database:

cloudflared db-connect --playground