diff --git a/README.md b/README.md index d4d0534..a0cdd79 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,13 @@ Using DNS "as a database" is not a novel idea, but the concept of running a data However none of them exposes a well-known API like serverless' DynamoDB, which makes it very convenient supporting existing tools and code (including benchmarks!). This is the main driver behind this project. -## Limitations +## Documentation -See [Limitations](doc/limitations.md). +* [Running Dyna53](doc/running.md) +* [Limitations](doc/limitations.md) +* [FAQ](doc/FAQ.md) ## Disclaimer -This is a toy, side-project. It is not intended to be used in production. Use at your own risk. +Dyna53 is not a service or software by Amazon AWS. It is also not a production-ready service. It is not even a true product/service. It is essentially a joke. There is no affiliation with Amazon AWS. Use at your own risk. Amazon AWS charges may apply when using the software. "Amazon Web Services", "AWS" and "DynamoDB" are registered trademarks of Amazon Technologies, Inc. diff --git a/doc/FAQ.md b/doc/FAQ.md new file mode 100644 index 0000000..7dec209 --- /dev/null +++ b/doc/FAQ.md @@ -0,0 +1,34 @@ +# FAQ + +> Is this a serious project? Can I run it in production? + +No, it is not a serious project, just a hobby project which turned out to be a funny programming exercise. Technically it could be run in production but there's little sense in doing so. You may incur in AWS costs. No guarantee is provided. + + +> Is this project affiliated with AWS? + +No, it is not. It is a project created by [Alvaro Hernandez](https://aht.es), founder of [OnGres](https://ongres.com) and [AWS Data Hero](https://aws.amazon.com/developer/community/heroes/alvaro-hernandez/). There's no affiliation with Amazon AWS and this is not a project nor a service by AWS. "Amazon Web Services", "AWS" and "DynamoDB" are registered trademarks of Amazon Technologies, Inc. + + +> Are there any limitations compared to DynamoDB? + +Yes, see [Limitations](limitations.md). + + +> What's this software license? Can I run this as-a-Service? + +The project is licensed under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) Open Source license. + +There would be very little sense in running Dyna53 as-a-Service, but it could be done. AGPLv3 license terms ensure that the project will remain Open Source for its users, so if you would run a modified version of it your users would have the right to get a copy of the modified source code. + + +> How far will be Dyna53 be developed? Are contributions accepted? + +Dyna53 is just an excercise and there should be little expectations that it will be developed much further. It is a non-goal to emulate DynamoDB completely. + +Contributions are welcomed, though, specially in polishing and testing the existing code, more than adding new features. + + +> Is there an Easter Egg in the program? + +Yes! If you have found it, please open an issue to discuss it :) \ No newline at end of file diff --git a/doc/limitations.md b/doc/limitations.md index 8df70c6..9b5e2bf 100644 --- a/doc/limitations.md +++ b/doc/limitations.md @@ -10,6 +10,29 @@ * Tables names cannot start or end with a hyphen (`-`), and would be removed. Hyphens are allowed in the middle of the table name. * A maximum lenght of 63 characters is supported. Requests for table names longer than this will be capped to 63 characters. +## Items +* Item characters should be contained within the extended ASCII 8-bit character set. No UTF-8 characters are supported (sorry, no emojis!). +* Item length is limited to 4,000 characters, including the JSON-like formatting, minus additional characters that may be used to escape characters that require escaping. +* **Tables with hash key primary key**: + * A maximum of 10,000 items can be stored (unless the quota for the number of records on the Route53 zone is raised). More precisely, three records will be used for the NS and SOA records and table definition, so at most 9,997 items can be stored. +* **Tables with hash key and range key primary key**: + * A maximum of 4 million records can be stored, with a maximum of 400 different items with the same hash key. Less than 400 items with the same hash key will be stored if their combined length is greater than 32,000 characters (which means that to fit 400 records per hash key records need to be less than 80 characters). + + +## Implemented Dynamo commands + +All of the following commands are implemented with basic behavior, with potentially flags being ignored by the implementation and information missing from the responses: + +* Create table. +* Describe table. +* Describe time to live. +* List tables. +* Put item. +* Get item. +* Scan. + +However, existing operations work well with usual Dynamo clients like the AWS CLI or Dynobase. + ## References diff --git a/doc/running.md b/doc/running.md new file mode 100644 index 0000000..a6a00a9 --- /dev/null +++ b/doc/running.md @@ -0,0 +1,31 @@ +# How to run Dyna53 + +## CLI and configuration + +Dyna53 can be either downloaded from the Releases or compiled by yourself. Once the binary is downloaded or generated it can be run calling the binary `dyna53`. + +It requires four parameters for configuration, that can be passed by any of the mechanisms supported by [MicroProfile Configuration](https://microprofile.io/microprofile-config/). Most typically it would be either command line arguments or environment variables: + +CLI arguments, Java style: +```sh +./dyna53 -Dhosted_zone=XXX -Daccess_key_id=XXX -Dsecret_access_key=XXX -Droute53_aws_profile=XXX +``` + +Environment variables: +```sh +export hosted_zone=XXX +export access_key_id=XXX +export secret_access_key=XXX +export route53_aws_profile=XXX +./dyna53 +``` + +The configuration variables are the following, and all are compulsory: +* `hosted_zone`: the ID (e.g. `ZXXXXXXXXXXXXXXXU`) of the Route53 DNS zone where data will be stored. It can be public (WARNING: data will become public!) or a private zone. +* `route53_aws_profile`: the name of the configured AWS profile where `dyna53` will be running that has permissions to perform the required operation on Route53. +* `access_key_id` and `secret_access_key`: the credentials used to authenticate the users against Dyna53. Note that these credentials are entirely made up, they don't need to exist on IAM. + + +## Environment + +Dyna53 is a Linux binary that could run anywhere. It could be your laptop, but for production-like performance you probably want to run it on a Lambda or EC2 instance. For a true serverless experience, it should run as a Lambda (with a custom runtime, to support the Linux binary).