Reference

Turso PHP Installer manual references

This page will provide a detailed explanation of how to use turso-php-installer and explore the additional features it offers to support development in both local and production environments.

$ turso-php-installer

  turso-php-installer  2.0.4

  USAGE:  <command> [options] [arguments]

  install                    Install Turso libSQL Extension for PHP
  uninstall                  Uninstall Turso libSQL Extension for PHP
  update                     Update Turso libSQL Extension for PHP
  version                    Display Turso PHP Installer version

  server:ca-cert-create      Generate CA certificate
  server:ca-cert-delete      Delete a CA certificate from the global store location
  server:ca-cert-list        List all generated CA certificates
  server:ca-cert-show        Show raw CA certificate and private key
  server:ca-peer-cert-create Create a peer certificate
  server:cert-store-get      Get the cert store location
  server:cert-store-set      Set/overwrite global certificate store, to use by the server later. Default is same as {installation_dir}/certs
  server:check               Check server requirement, this will check if python3 pip and cyptography lib are installed

  sqld:env-delete            Delete an environment by name or ID
  sqld:env-edit              Edit an existing environment by ID or name
  sqld:env-list              List all created environments
  sqld:env-new               Create new sqld environment, save for future use.
  sqld:env-show              Show detail of environment
  sqld:open-db               Open database using Turso CLI
  sqld:server-run            Run sqld server based on environment id or name

  token:create               Create libSQL Server Database token for Local Development
  token:delete               Delete a database token
  token:list                 Display all generated database tokens
  token:show                 Show libSQL Server Database token for Local Development

Install

Installs the Turso libSQL Extension for PHP, enabling seamless integration of libSQL with PHP applications.

Usage:

install [options]

Options:

• --unstable
  Installs the unstable version of the Turso libSQL extension from the development repository.
  Example:

  install --unstable
  

• --thread-safe
  Installs the Thread Safe (TS) version of the extension, which is necessary for certain PHP setups.
  Example:

  install --thread-safe
  

• --php-ini[=PHP-INI]
  Specifies the path to the php.ini file to use for configuring the extension.
  Example:

  install --php-ini=/etc/php.ini
  

• --php-version[=PHP-VERSION]
  Specifies the PHP version to use for the installation.
  Example:

  install --php-version=8.1
  

• --extension-dir[=EXTENSION-DIR]
  Specifies the directory where the PHP extension should be installed.
  Example:

  install --extension-dir=/usr/local/lib/php/extensions
  

Examples:

1. Install the Turso libSQL extension with the unstable version and specify a custom php.ini file:

   install --unstable --php-ini=/etc/php.ini
   

2. Install the Thread Safe version for PHP 8.1 and specify the extension directory:

   install --thread-safe --php-version=8.1 --extension-dir=/usr/local/lib/php/extensions
   

This command is used to install the Turso libSQL extension for PHP, making it easier to integrate libSQL with PHP-based applications. You can customize the installation with options to select specific versions, configurations, or directories based on your environment.

Interactive Mode

Command

turso-php-installer install

Output

Non-interactive Mode

Command

turso-php-installer install -y --php-version=8.3 --ext-destination=$EXT_DESTINATION

Output

Make sure you have root access when using Non-intractive Mode

Update

Update Turso libSQL Extension for PHP.

Command

turso-php-installer update

Output

Uninstall

Uninstall Turso libSQL Extension for PHP.

Command

turso-php-installer uninstall

Output

Version

Display Turso PHP Installer version with Current LibSQL Core and LibSQL PHP Extension.

Command

turso-php-installer version

Output

Turso libSQL Installer (version: 2.0.3)
LibSQL Core Version : 3.45.1-3045001 - LibSQL PHP Extension Version: 1.4.2

---

This command will (below 👇) be particularly useful when using the libSQL Server on your local computer during the development process. Additional features may be developed in the future to make it easier for developers to use libSQL Database and libSQL Server without any concerns.

---

Token Management

The following commands are used to manage database tokens for the libSQL Server during local development. These commands allow developers to create, view, list, and delete tokens as needed.

token:create

Creates a libSQL Server Database token for local development purposes.

Usage:

token:create [options] [--] <db-name>

Arguments:

• <db-name>
  The name of the database for which to generate the token.

Options:

• --expire[=EXPIRE]
  The number of days until the token expires. The default value is 7 days.
  Example: --expire=14 will set the token expiration to 14 days.

Examples:

1. Create a token for a database named my_database with the default 7-day expiration:

   token:create my_database
   

2. Create a token for a database named my_database with a 14-day expiration:

   token:create --expire=14 my_database
   

token:list

Displays a list of all generated database tokens.

Usage:

token:list

Examples:

1. Display a list of all tokens for all databases:
   token:list
   

This command provides an overview of all database tokens that have been generated, including their details such as database names, token types, and expiration dates.

token:show

Displays the libSQL Server Database token or related details for local development.

Usage:

token:show [options] [--] <db-name>

Arguments:

• <db-name>
  The name of the database for which to display the token or other related details.

Options:

• --fat
  Display only the full access token.

• --roa
  Display only the read-only access token.

• --pkp
  Display only the public key in PEM format.

• --pkb
  Display only the public key in Base64 format.

Examples:

1. Show all tokens and public key details for the my_database database:

   token:show my_database
   

2. Show only the full access token for the my_database database:

   token:show --fat my_database
   

3. Show only the read-only access token for the my_database database:

   token:show --roa my_database
   

4. Show only the public key in PEM format for the my_database database:

   token:show --pkp my_database
   

5. Show only the public key in Base64 format for the my_database database:

   token:show --pkb my_database
   

token:delete

Deletes a specific database token or all tokens for local development.

Usage:

token:delete [options] [--] [<db-name>]

Arguments:

• <db-name>
  The name of the database whose token you want to delete. If omitted and --all is not specified, the command will fail.

Options:

• --all
  Deletes all database tokens for all databases. Use with caution, as this action is irreversible.

Examples:

1. Delete the token for a specific database named my_database:

   token:delete my_database
   

2. Delete all database tokens:

   token:delete --all
   

If you intend to delete a specific token, ensure you specify the correct database name to avoid unintentional token deletions.

Certificate Management

This set of commands provides a comprehensive toolkit for managing server certificates and ensuring server readiness. It includes functionalities to create, delete, and list Certificate Authority (CA) certificates, view raw certificate details, and generate peer certificates. Users can also manage the global certificate store by retrieving or setting its location, with a default setup tied to the installation directory. Additionally, a dedicated command is available to verify server prerequisites, ensuring that necessary components like Python 3, pip, and cryptography libraries are properly installed. These features streamline certificate management and server preparation tasks.

server:check

Checks the server requirements to ensure that necessary components are installed. Specifically, it verifies if:

• Python 3 is installed.
• Pip (Python package manager) is installed.
• Cryptography library is installed.

Usage:

server:check

Examples:

1. Run the requirement check:
   server:check
   

Output:
The command will provide feedback on whether the required components are installed and properly configured. If any components are missing, it will suggest steps to install them.

This command is useful for setting up the server environment and ensuring all prerequisites are met before starting development or deployment.

server:ca-cert-create

Generates a Certificate Authority (CA) certificate for the server.

Usage:

server:ca-cert-create [options] [--] [<name>]

Arguments:

• <name>
  The name of the CA certificate to generate. Defaults to "ca" if not specified.
  Example: my-ca-cert.

Options:

• --expiry[=EXPIRY]
  The expiration period of the CA certificate in days. Defaults to 30 days.
  Example: --expiry=90 sets the certificate to expire in 90 days.

Examples:

1. Generate a CA certificate with the default name ca and a 30-day expiration:

   server:ca-cert-create
   

2. Generate a CA certificate with a custom name my-ca-cert and the default 30-day expiration:

   server:ca-cert-create my-ca-cert
   

3. Generate a CA certificate with a custom name and a 90-day expiration:

   server:ca-cert-create --expiry=90 my-ca-cert
   

This command is useful for generating CA certificates for securing server communication during development or testing.

server:ca-peer-cert-create

Creates a peer certificate signed by the Certificate Authority (CA).

Usage:

server:ca-peer-cert-create [options] [--] [<name>]

Arguments:

• <name>
  The name of the peer certificate to generate. Defaults to "ca" if not specified.
  Example: peer-cert-1.

Options:

• --expiry[=EXPIRY]
  The expiration period of the peer certificate in days. Defaults to 30 days.
  Example: --expiry=60 sets the certificate to expire in 60 days.

Examples:

1. Create a peer certificate with the default name ca and a 30-day expiration:

   server:ca-peer-cert-create
   

2. Create a peer certificate with a custom name peer-cert-1 and the default 30-day expiration:

   server:ca-peer-cert-create peer-cert-1
   

3. Create a peer certificate with a custom name and a 60-day expiration:

   server:ca-peer-cert-create --expiry=60 peer-cert-1
   

This command is useful for generating peer certificates for secure communication between entities, such as servers or clients, during development or testing.

server:ca-cert-list

Lists all generated Certificate Authority (CA) certificates.

Usage:

server:ca-cert-list

Examples:

1. Display a list of all CA certificates:
   server:ca-cert-list
   

This command provides an overview of all CA certificates that have been created, including details such as their names, expiration dates, and other metadata. It is useful for managing and reviewing existing certificates during development or testing.

server:ca-cert-show

Displays the raw CA certificate and private key.

Usage:

server:ca-cert-show [options]

Options:

• --raw
  Outputs the raw CA certificate and private key directly as text.

Examples:

1. Display the raw CA certificate and private key:
   server:ca-cert-show --raw
   

This command is useful for retrieving the CA certificate and private key in raw format for debugging or integration purposes. Use the --raw option to view the certificate and key as plain text.

server:ca-cert-delete

Deletes a specific Certificate Authority (CA) certificate or all CA certificates from the global store location.

Usage:

server:ca-cert-delete [options] [--] [<name>]

Arguments:

• <name>
  The name of the CA certificate to delete. Defaults to "ca" if not specified.
  Example: my-ca-cert.

Options:

• --all
  Deletes all CA certificates from the global store location. Use this option with caution as it is irreversible.

Examples:

1. Delete a specific CA certificate with the default name ca:

   server:ca-cert-delete
   

2. Delete a specific CA certificate with a custom name my-ca-cert:

   server:ca-cert-delete my-ca-cert
   

3. Delete all CA certificates from the global store location:

   server:ca-cert-delete --all
   

This command is useful for removing outdated or unnecessary CA certificates to maintain a clean global store. Ensure you specify the correct certificate name or use the --all option carefully.

server:cert-store-get

Retrieves the location of the certificate store.

Usage:

server:cert-store-get

Examples:

1. Get the certificate store location:
   server:cert-store-get
   

This command is useful for identifying the file system path where certificates are stored, allowing for manual inspection, backup, or other management tasks.

server:cert-store-set

Sets or overwrites the global certificate store location to be used by the server. By default, the store location is {installation_dir}/certs.

Usage:

server:cert-store-set [<path>]

Arguments:

• <path>
  The file system path to set as the new global certificate store.
  Example: /custom/path/to/certs.

Examples:

1. Set a custom global certificate store location:

   server:cert-store-set /custom/path/to/certs
   

2. Reset the certificate store location to the default by not specifying a path:

   server:cert-store-set
   

This command is useful for customizing the location of the certificate store to suit specific development or deployment needs. Ensure the specified path is accessible and writable by the server.

SQLD / libSQL Environment Management

This set of commands is designed to efficiently manage SQLD environments and interact with databases. It enables users to create, edit, delete, and list environments, ensuring streamlined organization and easy access for future use. Detailed information about specific environments can also be viewed as needed. Additionally, users can open databases using the Turso CLI and run the SQLD server based on a selected environment, providing a seamless workflow for database and server management.

sqld:env-new

Creates a new sqld environment and saves it for future use. If the environment already exists, it can be overwritten using the --force option.

Usage:

sqld:env-new [options] [--] <name>

Arguments:

• <name>
  The name of the environment to create. This is required.
  Example: development, staging, or production.

Options:

• --variables[=VARIABLES]
  Specifies the variables for the environment in either JSON or DSN (Data Source Name) format.
  Example in JSON format:

  --variables='{"SQLD_DB_PATH": "/your/database/path", "SQLD_HTTP_LISTEN_ADDR": "127.0.0.1:8080", "SQLD_AUTH_JWT_KEY_FILE": "/path/to/jwt_key.pem"}'
  

  Example in DSN format:

  --variables="SQLD_DB_PATH=/your/database/path;SQLD_HTTP_LISTEN_ADDR=127.0.0.1:8080;SQLD_AUTH_JWT_KEY_FILE=/path/to/jwt_key.pem"
  

• --force
  Forces the creation of the environment by overwriting it if an environment with the same name already exists.

Examples:

1. Create a new environment named development with variables in JSON format:

   sqld:env-new development --variables='{"SQLD_DB_PATH": "/your/database/path", "SQLD_HTTP_LISTEN_ADDR": "127.0.0.1:8080", "SQLD_AUTH_JWT_KEY_FILE": "/path/to/jwt_key.pem"}'
   

2. Create a new environment named production with variables in DSN format:

   sqld:env-new production --variables="SQLD_DB_PATH=/your/database/path;SQLD_HTTP_LISTEN_ADDR=127.0.0.1:8080;SQLD_AUTH_JWT_KEY_FILE=/path/to/jwt_key.pem"
   

3. Overwrite an existing environment named staging:

   sqld:env-new staging --force
   

This command is useful for setting up and managing different environments (e.g., development, staging, production) with their respective configurations for sqld.

sqld:env-list

Lists all created sqld environments.

Usage:

sqld:env-list

Examples:

1. List all available environments:
   sqld:env-list
   

This command is useful for getting an overview of all environments that have been created, allowing you to quickly see which environments are available for use or management.

sqld:env-show

Displays detailed information about a specific sqld environment based on its name or ID.

Usage:

sqld:env-show <name-or-id>

Arguments:

• <name-or-id>
  The name or ID of the environment whose details you want to view.
  Example: development, staging, or an environment ID like 677e5e0155167.

Examples:

1. Show details of an environment named development:

   sqld:env-show development
   

2. Show details of an environment by its ID:

   sqld:env-show 677e5e0155167
   

The output includes information such as environment variables, configurations, and other relevant details, making this command useful for reviewing or debugging specific environments.

sqld:env-edit

Edits an existing sqld environment by its ID or name.

Usage:

sqld:env-edit <env-id-or-name>

Arguments:

• <env-id-or-name>
  The ID or name of the environment you want to edit.
  Example: development, staging, or 677e5e0155167.

Examples:

1. Edit an environment named development:

   sqld:env-edit development
   

2. Edit an environment by its ID, for example, 677e5e0155167:

   sqld:env-edit 677e5e0155167
   

This command allows you to modify an existing environment’s settings and configurations. It’s useful for updating environment details such as database connections, credentials, or any other environment-specific variables.

sqld:env-delete

Deletes an sqld environment by its name or ID.

Usage:

sqld:env-delete <name-or-id>

Arguments:

• <name-or-id>
  The name or ID of the environment you want to delete.
  Example: development, staging, or 677e5e0155167.

Examples:

1. Delete an environment named development:

   sqld:env-delete development
   

2. Delete an environment by its ID, for example, 677e5e0155167:

   sqld:env-delete 677e5e0155167
   

This command is useful for removing environments that are no longer needed. Once deleted, the environment and its associated configurations will be permanently removed.

sqld:server-run

Runs the sqld server based on the specified environment ID or name, and connects it to the specified database. This command also will return a URL to open SQLD Studio in browser with current database credential / running database.

Usage:

sqld:server-run [options] [--] <env-id-or-name> <db-name>

Arguments:

• <env-id-or-name>
  The ID or name of the environment in which to run the sqld server.
  Example: development, staging, or 677e5e0155167.

• <db-name>
  The name of the database to connect the server to.
  Example: my_database.

Options:

• -d, --daemon
  Runs the sqld server in daemon mode, allowing it to run in the background.

Examples:

1. Run the sqld server for the development environment and connect to the my_database database:

   sqld:server-run development my_database
   

2. Run the sqld server for the staging environment, connect to the prod_db database, and run it in daemon mode:

   sqld:server-run -d staging prod_db
   

This command is used to start the sqld server in a specified environment and connect it to a database. The --daemon option is useful for running the server in the background without blocking the terminal.

sqld:open-db

Opens a database using the Turso CLI for the specified environment and database in Turso Database Shell.

Usage:

sqld:open-db <env-id-or-name> <db-name>

Arguments:

• <env-id-or-name>
  The ID or name of the environment where the database is located.
  Example: development, staging, or 677e5e0155167.

• <db-name>
  The name of the database to open.
  Example: my_database.

Examples:

1. Open the my_database from the development environment:

   sqld:open-db development my_database
   

2. Open the prod_db from the staging environment:

   sqld:open-db staging prod_db
   

This command allows you to open and interact with a specific database in a given environment using the Turso CLI, which is useful for managing and querying your databases directly.