libsql-experimental-python icon indicating copy to clipboard operation
libsql-experimental-python copied to clipboard

additional documentation for libsql sync example

Open OrthelT opened this issue 3 months ago • 0 comments

Summary

This PR improves the documentation and example for using libSQL with a synced Turso database. The updates make setup clearer and replaces command line environment variables with a .env file for easier configuration.

Changes

README.md

  • Updated install instructions:
    • Added python-dotenv dependency to support loading .env file.
  • Added Requirements section explaining an existing Turso cloud database and .env file are needed.
  • Expanded setup steps to include creating a new db in Turso CLI:
    • Included turso db create, turso db show, and turso db tokens create.
    • Added example .env file snippet.
  • Simplified run instructions:
    • Now uses python3 main.py and a '.env' file in place of inline environment variables.

main.py

  • Added a detailed docstring with more explicit instructions, requirements and setup steps.
  • Added from dotenv import load_dotenv and load_dotenv() for compatibility with '.env' file.

Motivation

The original example was functional but assumed prior knowledge that could frustrate new users:

  • It implicitly required an existing Turso database, without guidance on how to create one.
  • There were no instructions for obtaining or using Turso database credentials.
  • Users were expected to inline environment variables at runtime, which is less typical in Python and inconsistent with common practice.

Because embedded sync is a common entry point for developers new to libSQL and Turso, this update improves usability by:

  • Providing a complete, self-contained setup workflow for first-time users.
  • Adding .env support via python-dotenv to align with Python best practices for managing credentials.

Testing

  • Verified that the example runs successfully using a .env file with valid TURSO_DATABASE_URL and TURSO_AUTH_TOKEN values.
  • Confirmed that the local database syncs correctly, the users table is created, and expected query results are printed.

OrthelT avatar Sep 16 '25 06:09 OrthelT