CartoDB-SQL-API/README.md

111 lines
4.3 KiB
Markdown
Raw Normal View History

2019-12-27 23:30:01 +08:00
# CartoDB-SQL-API [![Build Status](https://travis-ci.org/CartoDB/CartoDB-SQL-API.svg?branch=master)](https://travis-ci.org/CartoDB/CartoDB-SQL-API)
2012-06-02 04:19:02 +08:00
2019-12-30 16:50:28 +08:00
The [`CARTOs SQL API`](https://carto.com/developers/sql-api/) allows you to interact with your data inside CARTO, as if you were running SQL statements against a normal database.
2013-10-01 00:02:48 +08:00
2019-12-27 23:30:01 +08:00
* Run queries with fine-grained permissions through [`Auth API`](https://carto.com/developers/auth-api/).
2019-12-29 02:43:55 +08:00
* Export data in multiple geospatial formats (CVS, geopackage, KML, SHP, spatialite, geojson, topojson, etc).
2019-12-27 23:30:01 +08:00
* Schedule jobs using [`Batch Queries`](https://carto.com/developers/sql-api/guides/batch-queries/).
2019-12-30 16:53:37 +08:00
* [`Copy queries`](https://carto.com/developers/sql-api/guides/copy-queries/) allows you to use the [`PostgreSQL copy command`](https://www.postgresql.org/docs/10/static/sql-copy.html) for efficient streaming of data to and from CARTO.
2019-12-27 23:30:01 +08:00
## Build
2019-12-27 23:30:01 +08:00
Requirements:
2011-10-08 00:19:02 +08:00
2020-12-17 18:11:49 +08:00
* [`Node 12.x`](https://nodejs.org/dist/latest-v12.x/)
* [`PostgreSQL >= 11.0`](https://www.postgresql.org/download/)
2019-12-27 23:30:01 +08:00
* [`PostGIS >= 2.4`](https://postgis.net/install/)
* [`CARTO Postgres Extension >= 0.24.1`](https://github.com/CartoDB/cartodb-postgresql)
* [`Redis >= 4`](https://redis.io/download)
2017-08-11 20:48:01 +08:00
* GDAL `1.11.0` (bin utils). See [installing GDAL](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries)
2019-12-27 23:30:01 +08:00
* `C++11` to build internal dependencies. When there's no pre-built binaries for your OS/architecture distribution.
Optional:
* [`Varnish`](http://www.varnish-cache.org)
* [`Statsd`](https://github.com/statsd/statsd)
### PostGIS setup
A `template_postgis` database is expected. One can be set up with
```shell
$ createdb --owner postgres --template template0 template_postgis
$ psql -d template_postgis -c 'CREATE EXTENSION postgis;'
```
2011-06-30 19:13:13 +08:00
2019-12-27 23:30:01 +08:00
### Install
2014-09-24 16:32:54 +08:00
2019-12-27 23:30:01 +08:00
To fetch and build all node-based dependencies, run:
2019-12-27 23:30:01 +08:00
```shell
$ npm install
```
2019-12-27 23:30:01 +08:00
### Run
2014-09-24 16:32:54 +08:00
2020-12-17 18:11:49 +08:00
You can inject the configuration through environment variables at run time. Check the file `./config/environments/config.js` to see the ones you have available.
While the migration to the new environment based configuration, you can still use the old method of copying a config file. To enabled the one with environment variables you need to pass `CARTO_SQL_API_ENV_BASED_CONF=true`. You can use the docker image to run it.
Old way:
2012-03-14 02:32:01 +08:00
2019-12-27 23:30:01 +08:00
```shell
$ node app.js <env>
```
2019-12-27 23:30:01 +08:00
Where `<env>` is the name of a configuration file under `./config/environments/`.
2012-03-14 02:32:01 +08:00
2019-12-27 23:30:01 +08:00
### Test
2019-12-27 23:30:01 +08:00
```shell
$ npm test
2012-03-14 02:32:01 +08:00
```
2020-12-17 18:11:49 +08:00
You can try to run the tests against the dependencies from the `dev-env`. To do so, you need to build the test docker image:
2012-03-16 17:31:03 +08:00
2019-12-27 23:30:01 +08:00
```shell
2020-12-17 18:16:51 +08:00
$ docker-compose -f private/docker-compose.yml build
2019-12-27 23:30:01 +08:00
```
2012-03-14 02:32:01 +08:00
2020-12-17 18:11:49 +08:00
Then you can run the tests like:
2019-12-27 23:30:01 +08:00
2020-12-17 18:11:49 +08:00
```shell
2020-12-17 18:16:51 +08:00
$ docker-compose -f private/docker-compose.yml run sql-api-tests
2020-12-17 18:11:49 +08:00
```
2019-12-27 23:30:01 +08:00
2020-12-17 18:11:49 +08:00
It will mount your code inside a volume. In case you want to play and run `npm test` or something else you can do:
2019-12-27 23:30:01 +08:00
```shell
2020-12-17 18:16:51 +08:00
$ docker-compose -f private/docker-compose.yml run --entrypoint bash sql-api-tests
2019-12-27 23:30:01 +08:00
```
2020-12-17 18:11:49 +08:00
So you will have a bash shell inside the test container, with the code from your host.
2019-12-27 23:30:01 +08:00
2020-12-17 18:11:49 +08:00
⚠️ *WARNING* Some tests still fail inside the docker environment. Inside CI they don't yet use the `ci` folder to run the tests either. There is a failing test which prevents it.
2019-12-27 23:30:01 +08:00
2020-12-17 18:11:49 +08:00
### Coverage
2019-12-27 23:30:01 +08:00
```shell
2020-12-17 18:11:49 +08:00
$ npm run cover
2014-09-24 16:32:54 +08:00
```
2020-12-17 18:11:49 +08:00
Open `./coverage/lcov-report/index.html`.
2019-12-27 23:30:01 +08:00
## Documentation
You can find an overview, guides, full reference, and support in [`CARTO's developer center`](https://carto.com/developers/sql-api/). The [docs directory](https://github.com/CartoDB/CartoDB-SQL-API/tree/master/docs) contains different documentation resources, from a higher level to more detailed ones.
## Contributing
* The issue tracker: [`Github`](https://github.com/CartoDB/CartoDB-SQL-API/issues).
* We love Pull Requests from everyone, see [contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/#contributing).
* You'll need to sign a Contributor License Agreement (CLA) before submitting a Pull Request. [Learn more here](https://carto.com/contributions).
## Versioning
2019-12-27 23:30:01 +08:00
We follow [`SemVer`](http://semver.org/) for versioning. For available versions, see the [tags on this repository](https://github.com/CartoDB/CartoDB-SQL-API/tags).
2015-09-08 22:40:12 +08:00
2019-12-27 23:30:01 +08:00
## License
2015-09-08 22:40:12 +08:00
2019-12-27 23:30:01 +08:00
This project is licensed under the BSD 3-clause "New" or "Revised" License. See the [LICENSE](LICENSE) file for details.