Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/outerbase/starbasedb
HTTP SQLite scale-to-zero database on the edge built on Cloudflare Durable Objects.
https://github.com/outerbase/starbasedb
cloudflare database durableobjects sqlite
Last synced: 2 days ago
JSON representation
HTTP SQLite scale-to-zero database on the edge built on Cloudflare Durable Objects.
- Host: GitHub
- URL: https://github.com/outerbase/starbasedb
- Owner: outerbase
- License: agpl-3.0
- Created: 2024-09-29T16:43:47.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-01-16T19:15:04.000Z (10 days ago)
- Last Synced: 2025-01-17T04:04:56.304Z (9 days ago)
- Topics: cloudflare, database, durableobjects, sqlite
- Language: TypeScript
- Homepage: https://starbasedb.com
- Size: 4.06 MB
- Stars: 840
- Watchers: 5
- Forks: 17
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
StarbaseDB
Open source, scale-to-zero, HTTP SQLite database built on top of Cloudflare Durable Objects.
Features
-
HTTPS Endpoints to query & interact with your database -
Web Socket Connections to query your database with low-latency web sockets -
Transactions Support for executing interdependent collections of queries -
REST API Support automatically included for interacting with your tables -
Database Interface included out of the box deployed with your Cloudflare Worker -
Import & Export Data to import & extract your schema and data into a local `.sql`, `.json` or `.csv` file -
Bindable Microservices via templates to kickstart development and own the logic (e.g. user authentication) -
Connect to External Databases such as Postgres and MySQL and access it with the methods above -
Scale-to-zero Compute to reduce costs when your database is not in use
Throughout building this offering we are documenting as much of the journey as possible. Join us in our adventure and join the conversation on talking through our design decisions as we continue to move fast. Find more details on how we implement core features on our blog.
Roadmap
-
Migrations for applying schema updates in safe sequential order -
JWT Authentication template for quickly allowing user auth flows -
Row Level Security (RLS) template for preventing data access on unauthorized rows -
Point in Time Rollbacks for rolling back your database to any minute in the past 30 days -
Data Replication to scale reads beyond the 1,000 RPS limitation -
Data Syncing between local source and your database -
Scheduled CRON Tasks to execute code at desired intervals
The above list is not an exhaustive list of features planned, but a glimpse at the direction we have in mind. We welcome any and all ideas from the community on what features or issues you would like to see be included as part of StarbaseDB. You can create new Bug Reports and Feature Requests and each will be reviewed.
Deploy a StarbaseDB
Deploying a new SQLite database instance to a Cloudflare Durable Object can be done via a single command:
```bash
curl https://starbasedb.com/install.sh | bash
```
The above command will create two new resources in your Cloudflare account, a Worker and a Durable Object.
Your Worker will be what clients make network requests to for fetching data from your database, and the Durable
Object itself is the SQLite storage.
After your worker has been deployed, you'll receive a console message similar to the one below:
==========================================
Welcome to the StarbaseDB installation script!
This script will deploy a Cloudflare Worker and create an Outerbase Starlink session.
If you don't have a paid Cloudflare account, your deployment will fail.
IMPORTANT: You _MUST_ have a paid Cloudflare account to use SQLite in Durable Objects.
==========================================
Cloning the repository...
Please enter your Cloudflare account_id (from 'wrangler whoami' or the Cloudflare dashboard):
{{YOUR_ACCOUNT_ID}}
Deploying your worker...
Worker deployed successfully at https://starbasedb.{YOUR-IDENTIFIER}.workers.dev.
==========================================
Outerbase Studio user account created!
Use the following URL to view your database:https://starbasedb.{YOUR-IDENTIFIER}.workers.dev/studio
Username: admin
Password: passwordNOTE: You can change your Outerbase Studio password in the wrangler.toml file and redeploy.
==========================================
Executing Queries
Start executing queries against your database with the following cURL commands:
Create Table
curl --location --request POST 'https://starbasedb.YOUR-ID-HERE.workers.dev/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ABC123' \
--data-raw '{
"sql": "CREATE TABLE IF NOT EXISTS artist(artistid INTEGER PRIMARY KEY, artistname TEXT);"
}'
Insert Values
curl --location --request POST 'https://starbasedb.YOUR-ID-HERE.workers.dev/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ABC123' \
--data-raw '{
"sql": "INSERT INTO artist (artistid, artistname) VALUES (123, '\''Alice'\''), (456, '\''Bob'\''), (789, '\''Charlie'\'');"
}'
Retrieve Values
curl --location --request POST 'https://starbasedb.YOUR-ID-HERE.workers.dev/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ABC123' \
--data-raw '{
"sql": "SELECT * FROM artist WHERE artistid=$1;",
"params": [123]
}'
Transactions
curl --location --request POST 'https://starbasedb.YOUR-ID-HERE.workers.dev/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ABC123' \
--data-raw '{
"transaction": [
{
"sql": "SELECT * FROM artist WHERE artistid=$1;",
"params": [123]
},
{
"sql": "SELECT * FROM artist;",
"params": []
}
]
}'
Raw Query Response
curl --location --request POST 'https://starbasedb.YOUR-ID-HERE.workers.dev/query/raw' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ABC123' \
--data-raw '{
"sql": "SELECT * FROM artist;",
"params": []
}'
Web Sockets
Below is an example HTML script function showing how you can connect via Web Sockets.
```javascript
let socket
function connectWebSocket() {
logMessage('Connecting to WebSocket...')
socket = new WebSocket(
'wss://starbasedb.YOUR-ID-HERE.workers.dev/socket?token=ABC123'
)
socket.onopen = function () {
logMessage('WebSocket connection opened.')
}
socket.onmessage = function (event) {
logMessage('Received: ' + event.data)
}
socket.onclose = function (event) {
logMessage(
`WebSocket closed with code: ${event.code}, reason: ${event.reason}`
)
}
socket.onerror = function (error) {
logMessage('WebSocket error: ' + error.message)
}
}
function sendMessage() {
const message = document.getElementById('messageInput').value
if (socket && socket.readyState === WebSocket.OPEN) {
logMessage('Sending: ' + message)
socket.send(
JSON.stringify({
sql: message,
params: [],
action: 'query',
})
)
} else {
logMessage('WebSocket is not open.')
}
}
window.onload = connectWebSocket
```
SQL Dump
You can request a `database_dump.sql` file that exports your database schema and data into a single file.
curl --location 'https://starbasedb.YOUR-ID-HERE.workers.dev/export/dump' \
--header 'Authorization: Bearer ABC123' \
--output database_dump.sql
JSON Data Export
curl --location 'https://starbasedb.YOUR-ID-HERE.workers.dev/export/json/users' \
--header 'Authorization: Bearer ABC123' \
--output output.json
CSV Data Export
curl --location 'https://starbasedb.YOUR-ID-HERE.workers.dev/export/csv/users' \
--header 'Authorization: Bearer ABC123' \
--output output.csv
SQL Import
curl --location 'https://starbasedb.YOUR-ID-HERE.workers.dev/import/dump' \
--header 'Authorization: Bearer ABC123' \
--form 'sqlFile=@"./Desktop/sqldump.sql"'
Contributing
We welcome contributions! Please refer to our Contribution Guide for more details.
License
This project is licensed under the AGPL-3.0 license. See the LICENSE file for more info.
Contributors