Installation Script
Provided for ease-of-use and quick deployments, we have a hosted shell script you can execute on your local machine. This script will run through the required steps for deploying the project. All you will be prompted for is your Cloudflare account ID.
You can find your Cloudflare Account ID when you login to https://dash.cloudflare.com, click on “Workers & Pages” on the left side, and you will see your Account ID appear on the right hand side of the screen.
Two components will be deployed to your account – a Worker and a Durable Object. Workers serve as the mechanism that allows you to interact with your storage layer (e.g. via HTTP) while the Durable Object acts as your SQLite disk storage layer.
To get started you can open up a shell interface on your local machine such as Terminal and paste in the following command:
curl https://starbasedb.com/install.sh | bash
Running through the parts of the script above, it will clone the Github repository locally, compile the code, and deploy it to your provided Cloudflare account. The output of your script will look like our image below.
Finally, your resources are deployed and you will see at the bottom of the script output we automatically provide you with a built-in user interface to visualize and interact with your database with our /studio
endpoint. This is part of your deployed instance and password protected with randomly generated authentication.
You can read more here about how to manage access to the auto-deployed Outerbase Studio with your StarbaseDB instance.
Manually Deploy
For more fine-grained control over what is deployed to your Worker you can manually pull the Github repository down and deploy it yourself. Both this method and the one above will clone the repository to your local machine and allow you to manipulate the code and deploy those changes, but we’ll take it step-by-step in this section.
Clone repository
All of the logic that is deployed to your Cloudflare Worker is maintained inside the Github repository. To get started you will first need to clone the repository onto your local machine which you can do by using the following command:
git clone git@github.com:Brayden/starbasedb.git && cd starbasedb
Now the code base should be downloaded on your machine and in your Terminal the project should be the active directory.
Modify code
As you browse the source code of the project you can see that all of the application logic we provide out of the box is included, such as our REST API’s, web socket support, and more. For more advanced use cases users may want to add their own application layer logic within the Worker which they can do so by appending their code into the project.
Why would someone want to modify the code? One of the key benefits of StarbaseDB is the fact that the deployed Cloudflare Worker compute instances run on the same machine as your SQLite databases which means in turn that every SQL operation can run synchronously and incredibly quickly, as if the data itself was already cached.
This step is optional and if opted to perform any modifications, it’s a good idea to fork the Github repository and contribute your custom code into your private fork.
Configure
Nearly all of our configuration can be handled within a single wrangler.toml
file included at the root level of our project. A quick summary of the key components of the file are below so you can make any adjustments you believe are needed for your use-case.
name
By default name is starbasedb
. Changing the value of this will change the name of the resource when deployed to Cloudflare Workers.
account_id
For deploying your code via the command line, the account_id
should be the value of the Cloudflare account you want to deploy your resources to.
AUTHORIZATION_TOKEN
An authorization token is used for you to interact with any of the exposed interfaces such as the HTTP endpoints, REST API’s, web sockets and more as a Bearer authentication token you pass into each request. This value should be secure and kept as an environment secret as it does grant access to your application logic and database storage layers.
STUDIO_USER
Optional. Value should be the username for logging into the user interface. When uncommented, you can access a database UI where you can see your tables, execute queries, modify your schema and more. The functionality is provided by the open-source project Outerbase Studio.
STUDIO_PASS
Optional. Value should be the password for logging into the user interface. When uncommented, you can access a database UI where you can see your tables, execute queries, modify your schema and more. The functionality is provided by the open-source project Outerbase Studio.
Compile
Prior to deploying our code we need to install the required package dependencies and also generate the types that need to be made available to the project for references as well. It’s as simple as running the following command which handles both at once, sequentially.
npm install && npm run cf-typegen
Deploy
Now you are ready to deploy your code and resources. As mentioned before, the two resources that are deployed to your Cloudflare account are a Worker and a Durable Object. The Worker is your compute, and the Durable Object is your storage. They are located on the same machine in a shared single-threaded process.
You can pull changes from the repository at any time and run the following command. It will not delete or overwrite any of your existing SQLite data stored, it will only deploy the application layer code changes of the worker.
npm run deploy