Introduction
After learning that Turso made a Laravel driver for LibSQL I just knew I had to try it. So in this short tutorial I will setup a simple Laravel example application with Breeze, using Turso and libsql as the database. I will then show how to prepare a server on Forge to be able to host the application. Specifically I will show how we can install the LibSQL extension for php.
Preparing the Turso Database
Lets start by getting a Turso database ready for the example. Let's create it using the Turso CLI
turso db create turso-laravel-example
We should now have a fresh new database we can use for this example. Run the following commands to get the url and generate a token to access the database.
turso db show --url turso-laravel-example
turso db tokens create turso-laravel-example
Save these for later as we will need them in the .env file for our Laravel application.
Preparing the Laravel Application
Since the point of this article is to explore how we host it and not the application it self. So it will be just a standard breeze Laravel template application.
Let's start by creating a new Laravel project.
composer create-project laravel/laravel turso-laravel-example
We now have a Laravel project named turso-laravel-example
and can continue by adding breeze and installing it.
cd turso-laravel-example/
composer require laravel/breeze --dev
php artisan breeze:install
When installing breeze we can just use the default options as they don't really matter for this tutorial.
We should now have a example application. What is missing is to install the turso-libsql-driver
and make some changes so that we can use the database we created earlier.
First step is to composer require the driver. [1]
composer require tursodatabase/turso-driver-laravel
Now we also need to do some more changes to our project code for it to work. We need to Add the LibSQLDriverServiceProvider
class to bootstrap/providers.php
After that we need to add this configuration to the connections
array in config/database.php
'libsql' => [
'driver' => 'libsql',
'url' => 'file:' . env('DB_DATABASE', 'database.sqlite'),
'authToken' => env('DB_AUTH_TOKEN', ''),
'syncUrl' => env('DB_SYNC_URL', ''),
'syncInterval' => env('DB_SYNC_INTERVAL', 5),
'read_your_writes' => env('DB_READ_YOUR_WRITES', true),
'encryptionKey' => env('DB_ENCRYPTION_KEY', ''),
'remoteOnly' => env('DB_REMOTE_ONLY', false),
'database' => null,
'prefix' => '',
],
You could now also setup your .env file and install the libsql extension/driver binary locally to test. However, since it is not yet supported in Herd I decided to skip this for now.
Final step before setting up the server is to create a git repo and add all the changes. Then push it to a repository at Github. I will not show how to do this in this tutorial.
Installing LibSQL PHP Extension on Forge Server
After the last section we should have a Github repository with our turso-laravel-example
project.
Which means we are now ready to deploy it to a server.
Before we create a new server in Forge we should first create a recipe for installing the libsql extension.
Here is a simple bash script I made that should fetch the Turso libsql php extension. It then extracts it and sets the required extension=
variable in the php.ini
files before reloading the php-fpm to pickup the changes. You should check the Release page on Github to find the libsql version and php version that will work for you.
PHP_VERSION="8.3"
TURSO_LIBSQL_VERSION="v1.2.6"
DIR_NAME="libsql_php-turso-php-extension-${TURSO_LIBSQL_VERSION}-php-${PHP_VERSION}-x86_64-unknown-linux-gnu"
ARCHIVE_NAME="${DIR_NAME}.tar.gz"
cd /home/forge
curl -L https://github.com/tursodatabase/turso-client-php/releases/download/turso-php-extension-${TURSO_LIBSQL_VERSION}/${ARCHIVE_NAME} -o $ARCHIVE_NAME
tar -xzvf $ARCHIVE_NAME
# Add the extension to the php ini files
echo "extension=/home/forge/${DIR_NAME}/liblibsql_php.so" >> /etc/php/${PHP_VERSION}/fpm/php.ini
echo "extension=/home/forge/${DIR_NAME}/liblibsql_php.so" >> /etc/php/${PHP_VERSION}/cli/php.ini
service php${PHP_VERSION}-fpm reload
If you save it as a Recipe in Forge you can then use it when creating a server.
For server provider I am using Hetzner, but you are free to choose your own. Since it is just an example project I just run a App Server with the smallest size. In Advanced Settings
I set Database
as None
as we are going to use Turso. Finally we can choose a Post-Provision Recipe
to run after the server is setup. Here we select the recipe we created earlier.
Deploying the Application to Forge
By this point we should have a Laravel application in Github and a Server in Forge with Turso LibSQL php extension.
Since this is just an example I will deploy it to the default site for the server in Forge. Choosing the Github repo and create the site.
Before we can deploy the site we need to do some changes. Firstly we should change the deployment script to also include a npm ci
and npm run build
. The full deployment script I use is:
cd /home/forge/default
git pull origin $FORGE_SITE_BRANCH
$FORGE_COMPOSER install --no-dev --no-interaction --prefer-dist --optimize-autoloader
npm ci
npm run build
( flock -w 10 9 || exit 1
echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock
if [ -f artisan ]; then
$FORGE_PHP artisan migrate --force
fi
Then secondly we need to configure our application to use the Turso database we created earlier.
I set these environment variables in the .env file for the site.
DB_CONNECTION=libsql
DB_AUTH_TOKEN=<your-database-auth-token-from-turso>
DB_SYNC_URL=<your-database-url-from-turso>
DB_REMOTE_ONLY=true
I am not sure if the DB_REMOTE_ONLY
is needed all the time, but at least I was not able to do the initial migration without having it set.
The site should now be ready to deploy. We can then access it using the IP address of the server.
And you should now see the default Laravel Breeze welcome page. You can try register and login and it should work, using your Turso database. We should also see it in the analytics for the database
Conclusion
We should now have a working Laravel deployment on Forge using a Turso libsql database.
The experience was not the easiest, and I bumped into a few errors when following the Turso guide for Laravel. Like they tell you to use the provider Turso\Driver\Laravel\LibSQLServiceProvider::class
but what I found was a provider called Turso\Driver\Laravel\LibSQLDriverServiceProvider::class
which was easy enough to fix. There was also the need to use the DB_REMOTE_ONLY=true
when deploying to Forge, which gave me not so useful error message.
The biggest thing stopping me from fully using this for my Laravel projects is that it is not supported in Herd yet. So, working with it locally is not as smooth as it could be.
Thank you for reading my article 😊 If you found it useful you can also follow me on twitter or check out my uptime monitoring SaaS I am currently working on 200.sh
Top comments (0)