When you already have a database from another provider but you want tools to access it easily and with the ability to customize functionality, you can tell your StarbaseDB instance that you also have an external data source that can be queried through your StarbaseDB URL. This guide will show you the required steps to connect your existing Postgres or MySQL database and be able to access it via the provided REST API or Web Socket support that exists as features today.
Connect to Outerbase
Currently this is the only supported way to connect to your external data sources. In a future contribution your StarbaseDB instance will be able to connect directly to your databases without having to route requests through the Outerbase API. We will continue to support the Outerbase API method though to maximize the number of data sources we can support.
Connecting to your database requires an Outerbase API Key. To get started visit https://outerbase.com to create an account, connect your database, and access the API token. For more information you can refer to the Outerbase documentation here: https://docs.outerbase.com/introduction/quick-start
Update Wrangler
Going back to our StarbaseDB code instance we need to define two new variables for our Worker to be able to access. This will tell us what type of database we are connecting to, and what API key value we should pass onto the Outerbase API for it to connect and make the request.
[vars]
# Add the following two lines
EXTERNAL_DB_TYPE = "postgres | mysql | sqlite"
OUTERBASE_API_KEY = "INSERT YOUR KEY HERE"
With the values added to our Wrangler file we need to deploy the latest changes to take affect.
npm run cf-typegen && npm run deploy
Request Data
Finally, our StarbaseDB instance is aware we have an external data source while we still have our internal SQLite data source! The two can coexist. To make a request to our external data source below is a sample request to our instance.
The notable difference here is the addition of the header X-Starbase-Source and having it set to external. By default, all requests use the internal source unless explicitly defined otherwise. When external is present we are informing our instance to query the connected database via the same HTTP or web socket methods we have exposed instead of our internal SQLite offering.
curl --location --request GET 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/rest/SCHEMA_NAME/TABLE_NAME' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Starbase-Source: external' \
--data-urlencode 'Content-type=application/json'
Conclusion
The ability to have one endpoint to connect to the internal SQLite and/or an external data source can have some massive benefits. For example, imagine being able to query your external database and cache the results in the internal one for subsequent queries can have a faster response time.
There is plenty more to come on how we plan on using this paradigm so stay tuned.