Skip to content

Commit

Permalink
docs: updated README with new cli options
Browse files Browse the repository at this point in the history
  • Loading branch information
@robinvandernoord
robinvandernoord committed Jul 31, 2023
1 parent ad31040 commit 7725ddd
Showing 1 changed file with 148 additions and 62 deletions.
210 changes: 148 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# pydal2sql


[![PyPI - Version](https://img.shields.io/pypi/v/pydal2sql.svg)](https://pypi.org/project/pydal2sql)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydal2sql.svg)](https://pypi.org/project/pydal2sql)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
Expand All @@ -9,22 +10,141 @@

-----

Convert pydal define_tables to SQL using pydal's CREATE TABLE logic

**Table of Contents**
`pydal2sql` is a command line interface (CLI) tool that translates pydal `define_table` Table definitions into SQL
statements. It supports different SQL dialects including SQLite, Postgres and MySQL. The tool generates
both `CREATE TABLE` and `ALTER TABLE` SQL statements. It does this using pydal's own logic.

## Table of Contents

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Create](#create)
- [Git Integration](#git-integration)
- [Options](#options)
- [Alter](#alter)
- [Global Options](#global-options)
- [Configuration](#configuration)
- [Magic](#-experimental-magic)
- [As a Python Library](#as-a-python-library)
- [License](#license)

## Example
## Installation

```bash
pip install pydal2sql
# or
pipx install pydal2sql
```

## Basic Usage

### `CREATE`

The following commands are supported:

- `pydal2sql create [file-name]`: Translate the file into SQL statements.
- `pydal2sql create [file-name]@[git-branch-or-commit-hash]`: Translate a specific version of the file into SQL
statements.
- `pydal2sql create [file-name]@latest`: Translate the latest version of the file in git into SQL statements.
- `pydal2sql create [file-name]@current`: Translate the current version of the file on disk into SQL statements.
- `pydal2sql create` or `pydal2sql create -`: Prompts the user to input the table definitions via stdin.

Bash pipe or redirect is also supported:

- `cat [file-name] | pydal2sql create`
- `pydal2sql create < [file-name]`

#### Git Integration

The tool allows you to specify a git branch or commit hash when translating a file. Using the 'latest' keyword will
use the latest commit, and 'current' will use the file as it currently is on disk.

#### Options

- `--table`, `--tables`, `-t`: Specify which database tables to generate CREATE statements for (default is all).
- `--db-type`, `--dialect`: Specify the SQL dialect to use (SQLite, Postgres, MySQL). The default is guessed from the
code or else the user is queried.
- `--magic`: If variables are missing, this flag will insert variables with that name so the code does (probably) not
crash.
- `--noop`: Doesn't create the migration code but only shows the Python code that would run to create it.

### `ALTER`

- `pydal2sql alter [file1] [file2]`: Generates the ALTER migration from the state in file1 to the state in file2.
- `pydal2sql alter [file1]@[branch-or-commit-hash] [file2]@[branch-or-commit-hash]`: Compares the files at those
specific versions and generates the ALTER migration.

Using `-` instead of a file name will prompt the user via stdin to paste the define tables code.

### Global Options

Global options that go before the subcommand:

- `--verbosity`: Sets how verbose the program should be, with a number between 1 and 4 (default is 2).
- `--config`: Path to a specific config toml file. Default is pyproject.toml at the key [tool.pydal2sql].
- `--version`: Prints the CLI tool version and exits.
- `--show-config`: Prints the currently used config and exits.

Example:

```bash
pydal2sql --verbosity 3 create
pydal2sql --version
```

### Configuration

A configuration file (in toml) can be selected with `--config`. By default, `pyproject.toml` is used.
In the configuration file, the following keys are supported under the [tool.pydal2sql] section:

- `dialect`/`db-type`: Default database dialect to use.
- `magic`: A boolean flag to use the `--magic` option (default is False).
- `noop`: A boolean flag to use the `--noop` option (default is False).
- `tables`: A list of table names to generate CREATE/ALTER statements for.

The CLI command options can overwrite the config values. For example, `--no-magic` will still set magic to False even if
it's set to True in the config file.

Example of the toml configuration:

```toml
[tool.pydal2sql]
dialect = "postgres" # postgres, mysql or sqlite
magic = true
noop = false
tables = ["table1", "table2"]
```

All keys are optional.

### ⚠️ Experimental 🪄✨Magic🌟💻

If you're copy-pasting some `define_table` statements which have validators or defaults that are defined elsewhere,
the SQL generation could crash due to msising variables. However, if these variables are irrelevant to the samentics of
the table definition (i.e. only used at runtime, not for the schema definition), you can now try the `--magic` flag.

This flag will replace all missing variables with a special `Empty` class, which does nothing but
prevent `NameError`, `AttributeError` and `TypeError`s.
This is of course not production-safe, so it shouldn't be used anywhere else.

#### TODO:
The following patterns are currently not supported:
- in `models.py`: from `.common import db`
- `def define_tables(db): ...`

## As a Python Library

`pydal2sql` also exposes a `generate_sql` method that can perform the same actions on one (for CREATE) or two (for
ALTER) `pydal.Table` objects when used within Python.

```python
from pydal import DAL, Field
from pydal2sql import generate_sql

db = DAL(None, migrate=False) # <- without running database or with a different type of database

db.define_table(
person_initial = db.define_table(
"person",
Field(
"name",
Expand Down Expand Up @@ -56,72 +176,38 @@ CREATE TABLE person
);
```

## Installation

```console
pip install pydal2sql
# or
pipx install pydal2sql
```

## cli

Given a Python file:

```python
# model_fragment.py
db.define_table(
person_new = db.define_table(
"person",
Field(...)
Field(
"name",
"text",
),
Field("birthday", "datetime"),
redefine=True
)

# optionally:
# db_type = 'postgres'
# tables = ['person']
```

Then in the terminal:

```bash
cat model_fragment.py | pydal2sql # without cli args if settings are set in code, or
cat model_fragment.py | pydal2sql postgres --table person # with args if settings are not in code
# both output the CREATE TABLE statements to stdout.

# alternatively, you can simply run `pydal2sql` and you will be prompted for the code, which you can then paste.
generate_sql(
person_initial,
person_new,
db_type="psql"
)
```

### Config via pyproject.toml

You can also configure settings via project settings instead of cli flags:

```toml
[tool.pydal2sql]
db_type = "postgres" # postgres, mysql or sqlite
filename = "examples/magic.py" # path to Python file to load
magic = true # bool
verbose = true # bool
noop = false # bool
tables = ["person"] # list of tables
```sql
ALTER TABLE person ADD "name__tmp" TEXT;
UPDATE person SET "name__tmp"=name;
ALTER TABLE person DROP COLUMN name;
ALTER TABLE person ADD name TEXT;
UPDATE person SET name="name__tmp";
ALTER TABLE person DROP COLUMN "name__tmp";
ALTER TABLE person ADD birthday TIMESTAMP;
ALTER TABLE person DROP COLUMN age;
ALTER TABLE person DROP COLUMN float;
ALTER TABLE person DROP COLUMN nicknames;
ALTER TABLE person DROP COLUMN obj;
```

All keys are optional.

### Example with pipx

[![asciicast](https://asciinema.org/a/upl4wB4QPDf9qO278ijWyPMby.svg)](https://asciinema.org/a/upl4wB4QPDf9qO278ijWyPMby)

### ⚠️ Experimental 🪄✨Magic🌟💻

If you're copy-pasting some `define_table` statements which have validators or defaults that are defined elsewhere,
the SQL generation could crash due to msising variables. However, if these variables are irrelevant to the samentics of
the table definition (i.e. only used at runtime, not for the schema definition), you can now try the `--magic` flag.

This flag will replace all missing variables with a special `Empty` class, which does nothing but
prevent `NameError`, `AttributeError` and `TypeError`s.
This is of course not production-safe, so it shouldn't be used anywhere else.

[![asciicast](https://asciinema.org/a/UQFaG2DWmXsJYzQ72CXer4oCu.svg)](https://asciinema.org/a/UQFaG2DWmXsJYzQ72CXer4oCu)

## License

`pydal2sql` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

0 comments on commit 7725ddd

Please sign in to comment.