Saltar a contenido

Instalación

Hay dos instalaciones, y confundirlas es de donde salen los problemas

Qué instala Con qué
La herramienta Lo que necesita tai-sql en tu máquina para conectarse, comparar, generar y dibujar pip install 'tai-sql[...]'
El proyecto Lo que necesita el cliente generado en tiempo de ejecución tai-sql install dentro del proyecto

tai-sql no está instalado donde se despliega el cliente generado: es una herramienta de desarrollo, no una dependencia de producción. Por eso los extras de tai-sql y los del pyproject.toml que escribe tai-sql init son dos listas distintas, y una dependencia que solo importa el código generado no va en los extras de tai-sql.

1. La herramienta

pip install tai-sql            # PostgreSQL funciona sin nada más
pip install 'tai-sql[all]'     # todo

Requiere Python 3.10 o superior.

Los extras, y cuándo hace falta cada uno

Hace falta el DBAPI del motor al que apunte tu datasource(provider=...). PostgreSQL no necesita nada: su DBAPI es una dependencia dura de tai-sql.

pip install 'tai-sql[mysql]'       # pymysql
pip install 'tai-sql[sqlserver]'   # pyodbc (+ el ODBC Driver del sistema)
pip install 'tai-sql[bigquery]'    # sqlalchemy-bigquery

Sin él, el fallo aparece en el primer comando que abra conexión (tai-sql ping) como un ModuleNotFoundError de SQLAlchemy que no dice qué instalar.

Los pide lo que declares, no lo que quieras hacer.

pip install 'tai-sql[vectors]'     # alguna vector_column()
pip install 'tai-sql[encryption]'  # alguna column(encrypt=True)
pip install 'tai-sql[diagrams]'    # ERDiagramGenerator con un formato de imagen
  • vectors: lo necesitan push y feed, que construyen el MetaData y ahí hace falta el tipo Vector. generate no: el cliente que produce define su propio tipo.
  • encryption: lo necesitan generate —valida la clave secreta antes de emitir el cliente— y feed, que cifra los valores que inserta.
  • diagrams: solo para los formatos de imagen, y necesita además el binario de Graphviz (ver abajo). El formato html, que es el de por defecto, no necesita ninguno de los dos.
pip install 'tai-sql[backup]'      # tai-sql backup / tai-sql restore

Dependencias del sistema

Hay dos cosas que pip no instala:

# Graphviz — solo para ERDiagramGenerator con format 'svg', 'png', 'pdf', 'dot', 'eps' o 'ps'
sudo apt install graphviz          # Ubuntu/Debian
brew install graphviz              # macOS
# Windows: https://graphviz.org/download/

# pg_dump / pg_restore — solo para tai-sql backup y tai-sql restore
sudo apt install postgresql-client

2. El proyecto y su cliente generado

Dentro de un proyecto ya creado:

tai-sql install            # lee el schema y resuelve los extras que necesite
tai-sql install --async    # añade también el driver asíncrono
tai-sql install -y         # sin confirmación

tai-sql install no instala tai-sql

Analiza el schema del proyecto y ejecuta poetry install --extras ... con lo que el cliente generado va a necesitar en runtime: el driver síncrono del motor, pgvector si hay columnas vectoriales, cryptography si hay columnas cifradas, y el paquete de langchain del encoder que declares.

Esos extras están escritos en el pyproject.toml del proyecto, que crea tai-sql init:

[project.optional-dependencies]
postgresql = ["psycopg2-binary (>=2.9.10,<3.0)"]
mysql = ["pymysql (>=1.1.1,<2.0)"]
sqlserver = ["pyodbc (>=5.2.0,<6.0)"]
bigquery = ["sqlalchemy-bigquery (>=1.11.0,<2.0)"]

postgresql-async = ["asyncpg (>=0.30.0,<1.0)"]
mysql-async = ["aiomysql (>=0.2.0,<1.0)"]
sqlserver-async = ["aioodbc (>=0.5.0,<1.0)"]

encryption = ["cryptography (>=45.0.4,<46.0)"]
vectors = ["pgvector (>=0.4.0,<1.0)"]
vectors-encoding = [...]   # langchain-huggingface | langchain-openai | langchain-google-genai

Comprobar que todo está

tai-sql info     # valida el schema sin tocar la base de datos
tai-sql ping     # ¿responde el servidor?
tai-sql ping -d  # ¿y existe la base de datos concreta?