github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/docs/RFCS/20160201_remove_sql_cli.md (about)

     1  - Title: Supersede the SQL command-line client with psql
     2  - Status: rejected
     3  - Start Date: 2016-02-01
     4  - Authors: knz
     5  - RFC PR: [#4059](https://github.com/cockroachdb/cockroach/pull/4059)
     6  - Cockroach Issue: [#4052](https://github.com/cockroachdb/cockroach/issues/4052),
     7                     [#4016](https://github.com/cockroachdb/cockroach/issues/4016),
     8                     [#4018](https://github.com/cockroachdb/cockroach/issues/4018),
     9                     [#4017](https://github.com/cockroachdb/cockroach/issues/4017),
    10                     [#3985](https://github.com/cockroachdb/cockroach/issues/3985),
    11                     perhaps [#3529](https://github.com/cockroachdb/cockroach/issues/3529)
    12  
    13  Summary
    14  =======
    15  
    16  Reduce/demote support for `cockroach sql`.
    17  
    18  Advertise `psql` (from the package `postgresql-client`)
    19  or possibly `pgcli` (from https://github.com/dbcli/pgcli ) instead.
    20  
    21  Keep minimal own CLI support for marketing.
    22  
    23  Motivation
    24  ==========
    25  
    26  `cockroach sql` has severe limitations currently, and not all can be
    27  solved within CockroachDB:
    28  
    29  - only one result set is returned for a query containing multiple
    30    statements (#4016). This is actually caused by a limitation in the
    31    interfaces offered by Go's standard `sql` module.
    32  
    33  - update/insert do not report the number of rows affected.
    34  
    35  - the output format is not configurable.
    36  
    37  Since this client talks over pgwire anyways, it seems obvious to consider
    38  using a native command-line PostgreSQL client instead, for example
    39  the official client `psql` from `postgresql-client`.
    40  
    41  Pros:
    42  
    43  - solves the existing issues in CockroachDB's own client (#4016, #4052, #4018, #4017);
    44  
    45  - automatically brings in numerous psql features:
    46      
    47    - provides customizable output formatting (including HTML; see
    48      #3985);
    49    - adds support for colors in interactive prompts!
    50    - (psql) support per-client preconfigured statements (eg `:mystatement`
    51      configured in `~/.psqlrc`)
    52    - many more! see
    53      http://www.postgresql.org/docs/9.4/static/app-psql.html
    54      https://github.com/dbcli/pgcli
    55    
    56  - reduces CockroachDB's code base: less code to maintain, test, debug,
    57    etc.
    58  - brings us fast closer to Beta (no need to spend dev time on sql cli)
    59      
    60  Cons:
    61  
    62  - at least in the beginning, the `\d` meta-commands from psql would not
    63    work and fail with non-intuitive error messages. This can be
    64    mitigated by appropriate documentation, though.
    65  
    66  - using psql would tie CockroachDB to PostgreSQL slightly, by requiring
    67    CLI SQL users to install the PostgreSQL client package.
    68  
    69    (Note that devs using cockroach in their applications would probably already
    70    use the pg driver anyway, so this Cons only pertains to CLI users.)
    71  
    72  Detailed design
    73  ===============
    74  
    75  - update the documentation to advertise compatibility with / use of
    76    `psql`;
    77    
    78  - remove the code for the interactive CLI; keep only minimal code to
    79    execute a single statement, print its results then exit, and
    80    use that in our own sql tests;
    81  
    82  - extend the test suite with SQL testing using `psql`;
    83    
    84  - eventually, if using psql submit a PR to the PostgreSQL team to
    85    enable the redefinition of meta-commands by means of
    86    configuration, and provide a configuration of meta-commands
    87    suitable for use with CockroachDB.
    88  
    89      
    90  Drawbacks
    91  =========
    92  
    93  Peter: We're implementing a SQL database, we should provide a SQL
    94  shell with our product. It is pretty awesome that we're compatible
    95  with psql and any other SQL shell that can utilize the pgwire
    96  protocol, but that doesn't mean we shouldn't provide our own. Yes, our
    97  SQL shell has bugs and limitations right now, but those can be fixed.
    98  
    99  Ben: we should ship our own client (for branding purposes and
   100  minimizing user confusion if nothing else). I think the main issues
   101  with our current client should be easy and worthwhile to fix. We may
   102  not have as many features as other clients at first but that's OK. A
   103  custom client also gives us a place to put commands that are not
   104  (currently) exposed via SQL, like splits, and gives us the opportunity
   105  to switch from pgwire to another protocol when/if that becomes
   106  desirable.
   107  
   108  I'd be OK with forking and extending some existing client if there is
   109  a suitable one. We don't have to build everything from scratch as long
   110  as the finished product is under our control (I wouldn't want to count
   111  on the PostgreSQL team making the behavior of \d configurable in psql,
   112  for example). I was hoping pgcli would be a good basis since they have
   113  both mysql and postgres clients, but it doesn't look like there's
   114  actually much shared code between the two.
   115  
   116  Alternatives
   117  ============
   118  
   119  Keep and advertise only the current custom client and deal with its limitations (NIH syndrome?).
   120  
   121  Unresolved questions
   122  ====================
   123  
   124  None