Orm yaml

.dockerignore

@@ -0,0 +1,7 @@
+.*
+*.yaml.gz
+orm.yaml
+config.yaml
+src-stats.yaml
+ssg.py
+dist

.gitignore

@@ -143,6 +143,9 @@ docs/temp/*
 # vim swap files
 *.swp
 
+# tool outputs
 ssg.py
-orm.py
+orm.yaml
 src-stats.yaml
+config.yaml
+*.yaml.gz

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.13.3-alpine3.21
+RUN apk add bash poetry
+WORKDIR /app
+ADD . /app
+RUN mkdir /pypoetry
+ENV POETRY_VIRTUALENVS_PATH=/pypoetry/cache/virtualenv
+ENV SHELL=/bin/bash
+ENV HOME=/
+RUN poetry install
+RUN poetry run sqlsynthgen --install-completion bash
+WORKDIR /data
+CMD ["poetry", "--directory=/app", "shell"]

docs/source/configuration.rst

@@ -4,6 +4,11 @@ Configuration Reference
 SqlSynthGen is configured using a YAML file, which is passed to several commands with the ``--config-file`` option.
 Throughout the docs, we will refer to this file as ``config.yaml`` but it can be called anything (the exception being that there will be a naming conflict if you have a vocabulary table called ``config``).
 
+You can generate an example configuration file, based on your source database and filled with only default values (therefore you can safely delete any parts of the generated configuration file you don't need) like this:
+
+.. code-block:: shell
+   sqlsynthgen generate-config
+
 Below, we see the schema for the configuration file.
 Note that our config file format includes a section of SmartNoise SQL metadata, which is explained more fully `here <https://docs.smartnoise.org/sql/metadata.html#yaml-format>`_.
 

docs/source/docker.rst

@@ -0,0 +1,37 @@
+Using Docker
+============
+
+Sqlsynthgen can be run in a docker container. You can build it locally or run it directly from Docker Hub.
+
+Building Docker locally
+-----------------------
+
+This will build a Docker image locally called ``ssg``:
+
+.. code-block:: shell
+   docker build -t ssg .
+
+Running sqlsynthgen in Docker
+-----------------------------
+
+Let us run the image built above in a way that can access a source
+database on the local machine (with DSN
+``postgresql://tim:tim@localhost:5432/pagila`` and schema ``public``),
+and stores the files produced in a directory called ``output``:
+
+.. code-block:: shell
+   mkdir output
+   docker run --rm --user $(id -u):$(id -g) --network host -e SRC_SCHEMA=public -e SRC_DSN=postgresql://tim:tim@localhost:5432/pagila -itv ./output:data ssg
+
+You do need to create the output folder first.
+
+You don't need ``--network host`` if the source database is not on the local
+computer.
+
+Running the image in this way will give you a command prompt from which
+sqlsynthgen can be called. Tab completion can be used. For example, if
+you type ``sq<TAB> ma<TAB>t<TAB>`` you will see
+``sqlsynthgen make-tables``; although you might have to wait a second
+or two after some of the ``<TAB>`` key presses for the completed text
+to appear. Tab completion can also be used for command options such
+as ``--force``. Press ``<TAB>`` twice to see a list of possible completions.

docs/source/health_data.rst

@@ -16,7 +16,7 @@ Before getting into the config itself, we need to discuss a few peculiarities of
 1. Some versions of OMOP contain a circular foreign key, for instance between the ``vocabulary``, ``concept``, and ``domain`` tables.
 2. There are several standardized vocabulary tables (``concept``, ``concept_relationship``, etc).
    These should be marked as such in the sqlsynthgen config file.
-   The tables will be exported to ``.yaml`` files during the ``make-generators`` step.
+   The tables will be exported to ``.yaml`` files during the ``create-generators`` step.
    However, some of these vocabulary tables may be too large to practically be writable to ``.yaml`` files, and will need to be dealt with manually.
    You should also check the license agreement of each standardized vocabulary before sharing any of the ``.yaml`` files.
 
@@ -106,15 +106,15 @@ The usual way is to run
 
 .. code-block:: shell
 
-  sqlsynthgen make-generators --config-file=config.yaml
+  sqlsynthgen create-generators --config-file=config.yaml
   sqlsynthgen create-vocab --config-file=config.yaml
 
-``make-generators`` downloads all the vocabulary tables to your local machine as YAML files and ``create-vocab`` uploads them to the target database.
+``create-generators`` downloads all the vocabulary tables to your local machine as YAML files and ``create-vocab`` uploads them to the target database.
 In the CCHIC dataset we were looking at some of the vocabulary tables were several gigabytes, and downloading those as YAML files was a bad idea.
 Thus we rather set SSG to ignore those tables and copied them over from the source schema to the destination schema manually, which was easier to do (in our case the source and the destination were just different schemas within the same database).
 
 The ``ignore: true`` option can also be used to make SSG ignore tables that we are not interested in at all.
-Note though that if one of the ignored tables is foreign key referenced by one of the tables we are `not` ignoring, the ignored table is still included in the ``orm.py`` and created by ``create-tables``, although ignored by ``make-generators`` and ``create-data``.
+Note though that if one of the ignored tables is foreign key referenced by one of the tables we are `not` ignoring, the ignored table is still included in the ``orm.py`` and created by ``create-tables``, although ignored by ``create-generators`` and ``create-data``.
 This is necessary to not break the network of foreign key relations.
 It is also good, because it means that after we copy the big vocabulary tables over manually, all foreign key references and things like automatically generating default values for referencing columns work as usual.
 

docs/source/index.rst

@@ -14,13 +14,6 @@ The latter also goes through some more advanced features of SSG and how to use t
 
    This project will be under active development from Jan - Oct 2023
 
-
-.. note::
-
-   We do not currently support tables without primary keys.
-   If you have tables without primary keys, some sqlsynthgen functionality
-   may work but vocabulary tables will not.
-
 Contents:
 ---------
 

docs/source/installation.rst

@@ -7,10 +7,13 @@ To use SqlSynthGen, first install it:
 
 .. code-block:: console
 
-   $ pip install sqlsynthgen
+   $ pipx install git+https://github.com/tim-band/sqlsynthgen
 
 Check that you can view the help message with:
 
 .. code-block:: console
 
    $ sqlsynthgen --help
+
+It can also be used directly within a Docker container by downloading image ``timband/ssg``.
+See the :ref:`quickstart guide <page-quickstart>` for more information.