{"id":14972130,"url":"https://github.com/jchristn/restdb","last_synced_at":"2025-05-09T00:07:45.335Z","repository":{"id":76080554,"uuid":"90178522","full_name":"jchristn/RestDb","owner":"jchristn","description":"RESTful HTTP/HTTPS server for Microsoft SQL Server, MySQL, and PostgreSQL","archived":false,"fork":false,"pushed_at":"2024-07-28T21:48:00.000Z","size":387,"stargazers_count":45,"open_issues_count":0,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-09T00:07:37.112Z","etag":null,"topics":["database","db","microsoft-sql","microsoft-sql-server","mono","mysql","mysql-client","mysql-database","postgresql","rest","restdb","sql"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jchristn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["jchristn"],"custom":["https://paypal.me/joelchristner"]}},"created_at":"2017-05-03T18:05:00.000Z","updated_at":"2024-10-27T12:44:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"c113ffd1-9973-417c-9b12-9d1f8cb3e39d","html_url":"https://github.com/jchristn/RestDb","commit_stats":{"total_commits":48,"total_committers":3,"mean_commits":16.0,"dds":0.0625,"last_synced_commit":"0f048bb1e09ae498cb34a00683bf41809e851cf0"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchristn%2FRestDb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchristn%2FRestDb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchristn%2FRestDb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchristn%2FRestDb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jchristn","download_url":"https://codeload.github.com/jchristn/RestDb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166520,"owners_count":21864482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","db","microsoft-sql","microsoft-sql-server","mono","mysql","mysql-client","mysql-database","postgresql","rest","restdb","sql"],"created_at":"2024-09-24T13:46:25.815Z","updated_at":"2025-05-09T00:07:45.292Z","avatar_url":"https://github.com/jchristn.png","language":"C#","readme":"# RestDb\n\nRESTful HTTP/HTTPS server for Microsoft SQL Server, MySQL, and PostgreSQL database tables written in C#.  \n\n## Description\n\nRestDb spawns a RESTful HTTP/HTTPS server that exposes a series of APIs allowing you to perform SELECT, INSERT, UPDATE, DELETE, TRUNCATE, and DROP against tables in Microsoft SQL Server, MySQL, PostgreSQL, and Sqlite.\n \n## New in v2.0.x\n\n- Dependency update to silence dependabot\n- Preflight OPTIONS fix from @Andrei-Errapart\n\n## Important Notes\n\n- If you specify a listener other than `localhost` or `127.0.0.1`, you may have to run with elevated privileges.\n- The HTTP HOST header MUST match the listener hostname, otherwise you'll get `Bad Request` errors back.\n- By default, access to RestDb is **UNAUTHENTICATED**.  Configure `restdb.json` with API keys to enable authentication, and set the `RequireAuthentication` value to `true`.\n\n## Running in Docker and Docker Compose\n\nThe easiest way to get started running in Docker or Docker Compose is to clone the repository and use the scripts found in the `Docker` directory.\n\n```\ngit clone https://github.com/jchristn/restdb\ncd restdb/Docker\nchmod +x *.sh\n\n#\n# Start and stop using Docker Compose\n#\n./compose-up.sh\n./compose-down.sh\n\n#\n# Run within Docker\n#\n./run.sh\n```\n\n## Execution\n  \n```\n\u003e cd RestDb\\bin\\debug\\net8.0\n\u003e dotnet RestDb.dll\n```\n  \n## Setup\n \n1) Start RestDb as described above.  You will be guided through a setup process to connect to your databases.  Alternatively, you can start with `Sqlite` which requires no database setup.\n\n```\n                 _      _ _\n   _ __ ___  ___| |_ __| | |__\n  | '__/ _ \\/ __| __/ _  |  _ \\\n  | | |  __/\\__ \\ || (_| | |_) |\n  |_|  \\___||___/\\__\\__,_|_.__/\n\n\nListening for requests on http://localhost:8000\n\n```\n\n2) Verify Connectivity\n\nPoint your browser to `http://localhost:8000`.  You should see a default webpage for RestDb.\n\n## Simple Examples\n\n### List databases\n```\nGET http://localhost:8000/_databases\n\nResp:\n200/OK\n[\n  \"test\"\n]\n```\n\n### Create a Table\n```\nPOST http://localhost:8000/test\nData: \n{\n  \"Name\": \"person\",\n  \"PrimaryKey\": \"person_id\",\n  \"Columns\": [\n    {\n      \"Name\": \"person_id\",\n      \"Type\": \"int\",\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"first_name\",\n      \"Type\": \"nvarchar\",\n      \"MaxLength\": 32,\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"last_name\",\n      \"Type\": \"nvarchar\",\n      \"MaxLength\": 32,\n      \"Nullable\": true\n    },\n    {\n      \"Name\": \"age\",\n      \"Type\": \"int\",\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"created\",\n      \"Type\": \"datetime\",\n      \"Nullable\": true\n    }\n  ]\n}\n\nResp:\n201/Created\n```\n\n### Retrieve a Database\n```\nGET http://localhost:8000/test\n\nResp:\n200/OK\n{\n  \"Name\": \"test\",\n  \"Type\": \"mssql\",\n  \"Hostname\": \"localhost\",\n  \"Port\": 1433,\n  \"Instance\": \"sqlexpress\",\n  \"Debug\": false,\n  \"TableNames\": [\n    \"person\"\n  ]\n}\n```\n\n### Describe a Table\n```\nGET http://localhost:8000/test/person?_describe\n\nResp:\n200/OK\n{\n  \"Name\": \"person\",\n  \"PrimaryKey\": \"person_id\",\n  \"Columns\": [\n    {\n      \"Name\": \"person_id\",\n      \"Type\": \"int\",\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"first_name\",\n      \"Type\": \"nvarchar\",\n      \"MaxLength\": 32,\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"last_name\",\n      \"Type\": \"nvarchar\",\n      \"MaxLength\": 32,\n      \"Nullable\": true\n    },\n    {\n      \"Name\": \"age\",\n      \"Type\": \"int\",\n      \"Nullable\": false\n    },\n    {\n      \"Name\": \"created\",\n      \"Type\": \"datetime\",\n      \"Nullable\": true\n    }\n  ]\n}\n```\n\n### Create an Object\n\nBe sure to use timestamps appropriate to your database type, for instance:\n\n- MsSql:  MM/dd/yyyy HH:mm:ss\n- MySql:  yyyy-MM-dd HH:mm:ss\n- PgSql:  MM/dd/yyyy HH:mm:ss\n- Sqlite: yyyy-MM-dd HH:mm:ss\n\n```\nPOST http://localhost:8000/test/person\nData: { first_name: 'joel', last_name: 'christner', age: 40, created: '05/03/2017' }\n\nResp:\n201/Created\n{\n  \"person_id\": 1,\n  \"first_name\": \"joel\",\n  \"last_name\": \"christner\",\n  \"age\": 40,\n  \"created\": \"05/03/2017 00:00:00\"\n}\n```\n\n### Create Multiple Objects\n\nTo create multiple objects, send a JSON array containing a series of dictionaries appropriate for the specified table.\n\n```\nPOST http://localhost:8080/test/person?_multiple\nData: [ { first_name: 'person1', last_name: 'last', age: 50, created '5/1/2017' }, ... ]\n\nResp:\n201/Created\n```\n\n### Retrieve Objects\n\nYou can retrieve all of a table's contents, retrieve by a specific ID, and filter by key-value pairs (using the querystring). \n\n```\nGET http://localhost:8000/test/person \nGET http://localhost:8000/test/person/1\nGET http://localhost:8000/test/person?first_name=joel \n\nResp:\n200/OK\n[\n  {\n    \"person_id\": 1,\n    \"first_name\": \"joel\",\n    \"last_name\": \"christner\",\n    \"age\": 18,\n    \"created\": \"1990-04-23T00:00:00Z\"\n  }, \n  { ... }\n]\n```\n\n### Retrieve Objects with Pagination\n\nYou can retrieve results and use pagination to return only a subset.  Include `_index`, `_max`, `_order`, and  `_order_by` in the querystring.  \n\n- `_index` is the starting index\n- `_max` is the maximum number of results to retrieve\n- `_order` must be either `asc` (ascending) or `desc` (descending).\n- `_order_by` is one or more column names in a comma-separated list.\n\nBy default, `SELECT` requests are ordered ASCENDING by the table's primary key.\n\n```\nGET http://localhost:8000/test/person?_max=1\u0026_index=1\u0026_order=asc\u0026_order_by=person_id,first_name\n\nResp:\n200/OK\n[\n  {\n    \"__row_num__\": 1,\n    \"person_id\": 1,\n    \"first_name\": \"joel\",\n    \"last_name\": \"christner\",\n    \"age\": 40,\n    \"created\": \"05/03/2017 00:00:00\"\n  },\n  { ... }\n]\n```\n\n### Update an Object\n\nSupply the ID in the URL and include the key-value pairs to change in the request body.\n\n```\nPUT http://localhost:8000/test/person/1\nData: { age: 18 }\n\nResp:\n200/OK\n{\n  \"person_id\": 1,\n  \"first_name\": \"joel\",\n  \"last_name\": \"christner\",\n  \"age\": 18,\n  \"created\": \"05/03/2017 00:00:00\"\n}\n```\n\n### Search for an Object\n\nUses the Expression syntax found in DatabaseWrapper (refer to examples here: https://github.com/jchristn/DatabaseWrapper).  These can be nested in a hierarchical manner.\n\n```\nPUT http://localhost:8000/test/person\nData: \n{\n  \"Left\": \"person_id\",\n  \"Operator\": \"GreaterThan\",\n  \"Right\": 0\n}\n\nResp:\n200/OK\n[\n  {\n    \"person_id\": 1,\n    \"first_name\": \"joel\",\n    \"last_name\": \"christner\",\n    \"age\": 18,\n    \"created\": \"05/03/2017 00:00:00\"\n  }\n]\n```\n\n### Delete an Object\n```\nDELETE http://localhost:8000/test/person/1\n\nResp: \n204/Deleted\n```\n\n### Truncating a Table\n```\nDELETE http://localhost:8000/test/person?_truncate\n\nResp: \n204/Deleted\n```\n\n### Dropping a Table\n```\nDELETE http://localhost:8000/test/person?_drop\n\nResp:\n204/Deleted\n```\n\n### Executing a Raw Query\n```\nPOST http://localhost:8000/test?raw\nData:\nSELECT * FROM person;\n\nResp:\n200/OK \n[\n  {\n    \"person_id\": 1,\n    \"first_name\": \"joel\",\n    \"last_name\": \"christner\",\n    \"age\": 18,\n    \"created\": \"05/03/2017 00:00:00\"\n  }\n]\n```\n\n## Enabling Authentication\n\nTo enable authentication, set `Server.RequireAuthentication` to `true` and specify an API key header in `Server.ApiKeyHeader` in the `restdb.json` file.  Then, add a section called `ApiKeys` with each of the keys you wish to allow or disallow.  An example with one API key is below.\n\n```\n{\n  \"Version\": \"1.1.0\",\n  \"Server\": {\n    \"ListenerHostname\": \"localhost\",\n    \"ListenerPort\": 8000,\n    \"Ssl\": false,\n    \"Debug\": false,\n    \"RequireAuthentication\": true,\n    \"ApiKeyHeader\": \"x-api-key\"\n  },\n  \"Logging\": { \n    \"ServerIp\": \"127.0.0.1\",\n    \"ServerPort\": 514,\n    \"MinimumLevel\": 1,\n    \"LogHttpRequests\": false,\n    \"LogHttpResponses\": false,\n    \"ConsoleLogging\": true\n  },\n  \"Databases\": [\n    {\n      \"Name\": \"test\",\n      \"Type\": \"MsSql\",\n      \"Hostname\": \"localhost\",\n      \"Port\": 1433,\n      \"Instance\": \"SQLEXPRESS\",\n      \"Username\": \"root\",\n      \"Password\": \"password\",\n      \"Debug\": false\n    }\n  ],\n  \"ApiKeys\": [\n    {\n      \"Key\": \"default\",\n      \"AllowGet\": true,\n      \"AllowPost\": true,\n      \"AllowPut\": true,\n      \"AllowDelete\": true\n    }\n  ]\n}\n```\n\n## Version History\n\nPlease refer to CHANGELOG.md for details.\n","funding_links":["https://github.com/sponsors/jchristn","https://paypal.me/joelchristner"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchristn%2Frestdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjchristn%2Frestdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchristn%2Frestdb/lists"}