From cff806cb41243bfb1d1e5b5e4caf3f7cde45a01d Mon Sep 17 00:00:00 2001 From: Olly Cope Date: Thu, 3 Nov 2022 14:57:06 +0000 Subject: docs: replace example command lines with structured reference --- doc/index.rst | 77 +++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 48 insertions(+), 29 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 4adfee7..5937bc1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -75,55 +75,74 @@ Check your migration has been created with ``yoyo list`` and apply it with Command line usage ================== -Start a new migration: +You can see the list of available commands by running: -.. code:: shell +.. command-output:: yoyo --help - yoyo new ./migrations -m "Add column to foo" -Apply migrations from directory ``migrations`` to a PostgreSQL database: +You can check options for any command with ``yoyo --help`` -.. code:: shell +yoyo new +-------- - yoyo apply --database postgresql://scott:tiger@localhost/db ./migrations +Start a new migration. ``yoyo new`` will create a new migration file and opens it your configured editor. -Rollback migrations previously applied to a MySQL database: +By default a Python formation migration will be created. To use the simpler SQL format, specify ``--sql``. .. code:: shell - yoyo rollback --database mysql://scott:tiger@localhost/database ./migrations + yoyo new -m "Add column to foo" + yoyo new --sql -Reapply (ie rollback then apply again) migrations to a SQLite database at -location ``/home/sheila/important.db``: +yoyo list +---------- -.. code:: shell +List available migrations. Each migration will be prefixed with one of ``U`` +(unapplied) or ``A`` (applied). - yoyo reapply --database sqlite:////home/sheila/important.db ./migrations +yoyo apply +---------- -List available migrations: +Apply migrations to the target database. By default this will prompt you for each unapplied migration. To turn off prompting use ``--batch`` or specify ``batch_mode = on`` in ``yoyo.ini``. -.. code:: shell - yoyo list --database sqlite:////home/sheila/important.db ./migrations +yoyo rollback +------------- + +By default this will prompt you for each applied migration, starting with the most recently applied. +If you wish to rollback a single migration, specify the migration with the ``-r``/``--revision`` flag. Note that this will also cause any migrations that depend on the selected migration to be rolled back. -During development, the ``yoyo develop`` command applies any -pending migrations without prompting: -.. code:: shell +yoyo reapply +------------- - $ yoyo develop --database postgresql://localhost/mydb migrations - Applying 3 migrations: - [00000000_initial-schema] - [00000001_add-table-foo] - [00000002_add-table-bar] +Reapply (ie rollback then apply again) migrations. As with `yoyo rollback`_, you can select a target migration with ``-r``/``--revision`` + + +yoyo develop +------------ + +Apply any unapplied migrations without prompting. + +If there are no unapplied migrations, rollback and reapply the most recent +migration. Use ``yoyo develop -n `` to act on just the *n* most recently +applied migrations. + +yoyo mark +--------- + +Mark one or more migrations as applied, without actually applying them. + +yoyo unmark +----------- + +Unmark one or more migrations as unapplied, without actually rolling them back. -If there are no migrations waiting to be applied the ``develop`` command will -instead roll back and reapply the last migration. Connecting to a database ------------------------- +======================== Database connections are specified using a URL, for example: @@ -152,7 +171,7 @@ and the DB-API driver used. The host part especially tends to be interpreted differently by drivers. A few of the more important differences are listed below. MySQL connections -````````````````` +----------------- mysqlclient_ and pymysql_ have different ways to interpret the ``host`` part of the connection URL: @@ -192,7 +211,7 @@ Example configurations: database = mysql+mysqldb://scott:tiger@localhost/mydatabase?ssl=yes&sslca=/path/to/cert PostgreSQL connections -`````````````````````` +---------------------- The psycopg family of drivers will use a unix socket if the host is left empty (or the value of ``PGHOST`` if this is set in your environment). Otherwise it will attempt a tcp connection to the specified host. @@ -222,7 +241,7 @@ Example configurations: database = postgresql://scott:tiger@/mydatabase?schema=some_schema SQLite connections -`````````````````` +------------------ The SQLite backend ignores everything in the connection URL except the database name, which should be a filename, or the special value ``:memory:`` for an in-memory database. -- cgit v1.2.1